# thivakar101/code-vulnerability-guardian architecture

> Architecture diagram of the GitHub repository thivakar101/code-vulnerability-guardian, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thivakar101/code-vulnerability-guardian
- Repository: https://github.com/thivakar101/code-vulnerability-guardian

## Overview

#### Purpose and Entry Points
Code Vulnerability Guardian is a local web-based source-code security scanner. It combines fast regex detection with local-LLM review, and includes a separate LoRA fine-tuning pipeline for vulnerability-focused model adaptation. Runtime entry points are `app.py` for the Flask service and `finetune.py` for training.

#### Web Application Boundary
The Flask backend serves the scanner UI, accepts uploaded source files or ZIP archives, orchestrates analysis, and returns findings to the browser. The presentation layer is deliberately thin:
- `app.py`
- `templates/index.html`
- `static/style.css`

The browser is an operator interface, not the analysis engine; upload handling and model routing remain server-side.

#### Stage 1: Static Heuristic Scan
The backend performs an immediate rule-based pass over submitted source content. This layer targets recognizable high-risk patterns such as dynamic execution, shell-command invocation, embedded secrets, unsafe deserialization, and weak cryptography. Its purpose is low-latency, deterministic findings before AI analysis.
- `app.py`

#### Stage 2: Local LLM Security Review
After heuristic scanning, the backend submits code/context to a local LLM provider, described as Ollama with models such as Llama 3. The expected result is structured security analysis containing summary, severity, and remediation information. This is an external-process/service boundary: availability and output quality depend on the locally running model service rather than Flask itself.
- `app.py`

#### Scan Data Flow
User upload flows from the HTML interface into Flask. Flask processes individual code files or expands ZIP contents, applies regex rules, then coordinates deep LLM review. Results are returned to the UI for visual inspection and security-assistant interaction. The main control-flow owner is:
- `app.py`
- `templates/index.html`

#### Fine-Tuning Pipeline
`finetune.py` is an offline ML workflow, separate from request-time scanning. It loads vulnerability training records, tokenizes them, trains a causal language model using PEFT/LoRA, and writes adapter artifacts/checkpoints. The default proof-of-concept model is CPU-friendly DialoGPT-small; the design can be retargeted to Llama-family models with CUDA and appropriate LoRA target modules.
- `finetune.py`
- `data.jsonl`
- `cpu_finetune/adapter_model.safetensors`

#### Model Artifacts and Training State
The repository contains a completed/exported adapter plus resumable checkpoints. The root adapter directory is the likely inference-ready fine-tune output; checkpoint directories retain optimizer, scheduler, tokenizer, and trainer state for continuing training.
- `cpu_finetune/adapter_config.json`
- `cpu_finetune/checkpoint-25/trainer_state.json`
- `cpu_finetune/checkpoint-50/optimizer.pt`

#### Runtime and Infrastructure
Request-time infrastructure is Python/Flask plus HTTP communication to a local Ollama-hosted LLM. Training requires PyTorch, Hugging Face Transformers/Datasets, and PEFT; CPU execution is supported for the default model, while larger Llama training requires CUDA-capable GPU infrastructure. Dependency declarations are centralized in:
- `requirements.txt`
- `verifygpusupport.py`

Main entry points: [`finetune.py`](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/finetune.py) (LoRA training workflow), [`app.py`](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py) (Flask scanner service), [`templates/index.html`](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/templates/index.html) (Scanner UI), [`requirements.txt`](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/requirements.txt) (Dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Request-time scanner"]
  node_browser["Scanner UI<br/>browser interface<br/>[index.html]"]
  node_styles["UI styles<br/>stylesheet<br/>[style.css]"]
  node_flask["Flask scanner service<br/>Python entry point<br/>[app.py]"]
  node_upload["Source upload<br/>input payload"]
  node_archive["ZIP expansion<br/>archive handling<br/>[app.py]"]
  node_heuristics["Regex heuristic scan<br/>static analysis<br/>[app.py]"]
  node_findings["Scan findings<br/>security results<br/>[app.py]"]
end

subgraph group_llm["Local model service"]
  node_ollama{{"Ollama service<br/>local LLM provider"}}
  node_review["Security review<br/>structured LLM analysis<br/>[app.py]"]
end

subgraph group_training["Offline fine-tuning"]
  node_training_data["Vulnerability records<br/>JSONL dataset<br/>[data.jsonl]"]
  node_finetune["LoRA training workflow<br/>Python entry point<br/>[finetune.py]"]
  node_base_model["Base causal model<br/>HF model<br/>[finetune.py]"]
  node_adapter[("Exported LoRA adapter<br/>model artifact")]
  node_adapter_config["Adapter configuration<br/>model metadata"]
  node_checkpoints[("Resumable checkpoints<br/>training state<br/>[trainer_state.json]")]
  node_optimizer_state["Optimizer state<br/>checkpoint artifact<br/>[optimizer.pt]"]
  node_gpu_check["GPU capability check<br/>hardware utility"]
end

node_dependencies["Dependencies<br/>runtime requirements<br/>[requirements.txt]"]

node_styles -->|"styles"| node_browser
node_browser -->|"submits"| node_upload
node_upload -->|"received by"| node_flask
node_flask -->|"expands ZIPs"| node_archive
node_flask -->|"scans source"| node_heuristics
node_flask -->|"requests deep review"| node_review
node_review -->|"uses HTTP"| node_ollama
node_heuristics -->|"deterministic findings"| node_findings
node_review -->|"structured analysis"| node_findings
node_findings -->|"renders results"| node_browser
node_training_data -->|"loads records"| node_finetune
node_base_model -->|"adapted with LoRA"| node_finetune
node_finetune -->|"exports"| node_adapter
node_finetune -->|"writes"| node_adapter_config
node_finetune -->|"saves state"| node_checkpoints
node_finetune -->|"persists optimizer"| node_optimizer_state
node_gpu_check -.->|"guides hardware mode"| node_finetune
node_dependencies -.->|"supports"| node_flask
node_dependencies -.->|"supports"| node_finetune

click node_browser "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/templates/index.html"
click node_styles "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/static/style.css"
click node_flask "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py"
click node_archive "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py"
click node_heuristics "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py"
click node_findings "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py"
click node_review "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py"
click node_training_data "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/data.jsonl"
click node_finetune "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/finetune.py"
click node_base_model "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/finetune.py"
click node_adapter "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/cpu_finetune/adapter_model.safetensors"
click node_adapter_config "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/cpu_finetune/adapter_config.json"
click node_checkpoints "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/cpu_finetune/checkpoint-25/trainer_state.json"
click node_optimizer_state "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/cpu_finetune/checkpoint-50/optimizer.pt"
click node_dependencies "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/requirements.txt"
click node_gpu_check "https://github.com/thivakar101/code-vulnerability-guardian/blob/main/verifygpusupport.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_styles,node_flask,node_upload,node_archive,node_heuristics,node_findings toneBlue
class node_ollama,node_review toneAmber
class node_training_data,node_finetune,node_base_model,node_adapter,node_adapter_config,node_checkpoints,node_optimizer_state,node_gpu_check toneMint
class node_dependencies toneNeutral
```

## Components

### Request-time scanner

Local Flask application and scan stages.

- [Scanner UI](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/templates/index.html): browser interface · `templates/index.html`
- [UI styles](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/static/style.css): stylesheet · `static/style.css`
- [Flask scanner service](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py): Python entry point · Owns uploads, scan orchestration, and result responses. · `app.py`
- **Source upload**: input payload · Individual source files or ZIP archives.
- [ZIP expansion](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py): archive handling · `app.py`
- [Regex heuristic scan](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py): static analysis · Fast deterministic checks for risky code patterns. · `app.py`
- [Scan findings](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py): security results · Combined heuristic and LLM results for the operator. · `app.py`

### Local model service

LLM review runs outside the Flask process.

- **Ollama service**: local LLM provider · Locally running model-service boundary.
- [Security review](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/app.py): structured LLM analysis · Returns summary, severity, and remediation. · `app.py`

### Offline fine-tuning

Separate LoRA adaptation workflow.

- [Vulnerability records](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/data.jsonl): JSONL dataset · `data.jsonl`
- [LoRA training workflow](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/finetune.py): Python entry point · Tokenizes records and trains a causal language model. · `finetune.py`
- [Base causal model](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/finetune.py): HF model · Defaults to CPU-friendly DialoGPT-small; can target Llama models. · `finetune.py`
- [Exported LoRA adapter](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/cpu_finetune/adapter_model.safetensors): model artifact · Likely inference-ready fine-tune output. · `cpu_finetune/adapter_model.safetensors`
- [Adapter configuration](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/cpu_finetune/adapter_config.json): model metadata · `cpu_finetune/adapter_config.json`
- [Resumable checkpoints](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/cpu_finetune/checkpoint-25/trainer_state.json): training state · Retains trainer, optimizer, scheduler, and tokenizer state. · `cpu_finetune/checkpoint-25/trainer_state.json`
- [Optimizer state](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/cpu_finetune/checkpoint-50/optimizer.pt): checkpoint artifact · `cpu_finetune/checkpoint-50/optimizer.pt`
- [GPU capability check](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/verifygpusupport.py): hardware utility · Supports deciding CPU versus CUDA training. · `verifygpusupport.py`

### Other components

- [Dependencies](https://github.com/thivakar101/code-vulnerability-guardian/blob/main/requirements.txt): runtime requirements · Declares Flask, training, and ML dependencies. · `requirements.txt`

## Connections

- UI styles → Scanner UI: styles
- Scanner UI → Source upload: submits
- Source upload → Flask scanner service: received by
- Flask scanner service → ZIP expansion: expands ZIPs
- Flask scanner service → Regex heuristic scan: scans source
- Flask scanner service → Security review: requests deep review
- Security review → Ollama service: uses HTTP
- Regex heuristic scan → Scan findings: deterministic findings
- Security review → Scan findings: structured analysis
- Scan findings → Scanner UI: renders results
- Vulnerability records → LoRA training workflow: loads records
- Base causal model → LoRA training workflow: adapted with LoRA
- LoRA training workflow → Exported LoRA adapter: exports
- LoRA training workflow → Adapter configuration: writes
- LoRA training workflow → Resumable checkpoints: saves state
- LoRA training workflow → Optimizer state: persists optimizer
- GPU capability check → LoRA training workflow: guides hardware mode
- Dependencies → Flask scanner service: supports
- Dependencies → LoRA training workflow: supports