# ilyasmeziani2-hub/mavd-public-edition architecture

> Architecture diagram of the GitHub repository ilyasmeziani2-hub/mavd-public-edition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ilyasmeziani2-hub/mavd-public-edition
- Repository: https://github.com/ilyasmeziani2-hub/mavd-public-edition

## Overview

MAVD is a local SAST-triage product: a user starts an analysis through either the CLI or dashboard-backed launcher, which runs Semgrep, adds source context, obtains LLM qualification and (for confirmed findings) mitigation, then records evaluation, provenance and reports. The dashboard reads saved artifacts and presents analyses, findings, evaluation and reports. The README documents the linear pipeline; some backend orchestration and dashboard-to-API links are documented but their full implementation was not excerpted.

Main entry points: [`main.py`](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/main.py) (CLI runner), [`launcher.py`](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/launcher.py) (Local API runner), [`outputs`](https://github.com/ilyasmeziani2-hub/mavd-public-edition/tree/main/outputs) (Analysis artifacts), [`context.py`](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/context.py) (Source context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI runner<br/>[main.py]"]
  node_launcher["Local API runner<br/>[launcher.py]"]
end

subgraph group_pipeline["Analysis pipeline"]
  node_scanner["Semgrep scanner<br/>[scanner.py]"]
  node_context["Source context<br/>[context.py]"]
  node_triage["Finding qualification<br/>[triage.py]"]
  node_mitigation["Mitigation advice<br/>[mitigation.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_artifacts["Results and reporting"]
  node_evaluation["Metrics evaluation<br/>[evaluation.py]"]
  node_provenance["Run provenance<br/>[provenance.py]"]
  node_report["HTML report<br/>[report.py]"]
  node_artifacts_store[("Analysis artifacts")]
end

subgraph group_dashboard["Dashboard"]
  node_web_data["Artifact access<br/>[academic-data.ts]"]
  node_analysis_model["Artifact interpretation<br/>[analysis-model.ts]"]
  node_dashboard_home["Overview dashboard<br/>[page.tsx]"]
  node_analysis_pages["Analysis views<br/>[page.tsx]"]
  node_finding_pages["Finding views<br/>[page.tsx]"]
  node_evaluation_ui["Evaluation summary"]
  node_report_pages["Report views<br/>[page.tsx]"]
  node_sidebar["Workspace navigation<br/>[sidebar.tsx]"]
end

node_analyst(("Analyst"))
node_provider(("LLM service"))

node_analyst -->|"runs analysis"| node_cli
node_analyst -->|"views results"| node_dashboard_home
node_dashboard_home -.->|"starts analysis"| node_launcher
node_cli -->|"runs scan"| node_scanner
node_launcher -->|"runs scan"| node_scanner
node_scanner -->|"provides findings"| node_context
node_context -->|"provides source window"| node_triage
node_triage -->|"requests qualification"| node_llm
node_mitigation -->|"requests suggestion"| node_llm
node_llm -->|"sends prompt"| node_provider
node_launcher -->|"extracts context"| node_context
node_launcher -->|"qualifies findings"| node_triage
node_launcher -->|"mitigates confirmed"| node_mitigation
node_cli -->|"extracts context"| node_context
node_cli -->|"qualifies findings"| node_triage
node_cli -->|"mitigates confirmed"| node_mitigation
node_launcher -->|"evaluates findings"| node_evaluation
node_launcher -->|"records provenance"| node_provenance
node_launcher -->|"generates report"| node_report
node_cli -->|"evaluates findings"| node_evaluation
node_cli -->|"records provenance"| node_provenance
node_cli -->|"generates report"| node_report
node_launcher -->|"writes run artifacts"| node_artifacts_store
node_cli -->|"writes run artifacts"| node_artifacts_store
node_report -->|"saves HTML report"| node_artifacts_store
node_web_data -->|"reads saved artifacts"| node_artifacts_store
node_web_data -->|"interprets artifacts"| node_analysis_model
node_artifacts_store -->|"supplies analysis data"| node_dashboard_home
node_artifacts_store -->|"supplies analysis data"| node_analysis_pages
node_artifacts_store -->|"supplies findings"| node_finding_pages
node_artifacts_store -->|"supplies evaluation"| node_evaluation_ui
node_artifacts_store -->|"supplies reports"| node_report_pages

click node_cli "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/main.py"
click node_launcher "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/launcher.py"
click node_scanner "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/scanner.py"
click node_context "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/context.py"
click node_triage "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/triage.py"
click node_mitigation "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/mitigation.py"
click node_llm "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/llm_client.py"
click node_evaluation "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/evaluation.py"
click node_provenance "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/provenance.py"
click node_report "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/report.py"
click node_artifacts_store "https://github.com/ilyasmeziani2-hub/mavd-public-edition/tree/main/outputs"
click node_web_data "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/lib/academic-data.ts"
click node_analysis_model "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/lib/analysis-model.ts"
click node_dashboard_home "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/app/page.tsx"
click node_analysis_pages "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/app/analyses/%5Bid%5D/page.tsx"
click node_finding_pages "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/app/findings/page.tsx"
click node_evaluation_ui "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/components/analysis/evaluation-summary.tsx"
click node_report_pages "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/app/reports/%5Bid%5D/page.tsx"
click node_sidebar "https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/components/layout/sidebar.tsx"

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_cli,node_launcher toneBlue
class node_scanner,node_context,node_triage,node_mitigation,node_llm toneAmber
class node_evaluation,node_provenance,node_report,node_artifacts_store toneMint
class node_web_data,node_analysis_model,node_dashboard_home,node_analysis_pages,node_finding_pages,node_evaluation_ui,node_report_pages,node_sidebar toneRose
class node_analyst,node_provider toneIndigo
```

## Components

### Entry points

- [CLI runner](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/main.py): `main.py`
- [Local API runner](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/launcher.py): `launcher.py`

### Analysis pipeline

- [Semgrep scanner](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/scanner.py): `scanner.py`
- [Source context](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/context.py): `context.py`
- [Finding qualification](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/triage.py): `triage.py`
- [Mitigation advice](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/mitigation.py): `mitigation.py`
- [LLM client](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/llm_client.py): `llm_client.py`

### Results and reporting

- [Metrics evaluation](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/evaluation.py): `evaluation.py`
- [Run provenance](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/provenance.py): `provenance.py`
- [HTML report](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/report.py): `report.py`
- [Analysis artifacts](https://github.com/ilyasmeziani2-hub/mavd-public-edition/tree/main/outputs): `outputs`

### Dashboard

- [Artifact access](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/lib/academic-data.ts): `web/lib/academic-data.ts`
- [Artifact interpretation](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/lib/analysis-model.ts): `web/lib/analysis-model.ts`
- [Overview dashboard](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [Analysis views](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/app/analyses/%5Bid%5D/page.tsx): `web/app/analyses/[id]/page.tsx`
- [Finding views](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/app/findings/page.tsx): `web/app/findings/page.tsx`
- [Evaluation summary](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/components/analysis/evaluation-summary.tsx): `web/components/analysis/evaluation-summary.tsx`
- [Report views](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/app/reports/%5Bid%5D/page.tsx): `web/app/reports/[id]/page.tsx`
- [Workspace navigation](https://github.com/ilyasmeziani2-hub/mavd-public-edition/blob/main/web/components/layout/sidebar.tsx): `web/components/layout/sidebar.tsx`

### Other components

- **Analyst**
- **LLM service**

## Connections

- Analyst → CLI runner: runs analysis (evidence: `README.md`)
- Analyst → Overview dashboard: views results (evidence: `README.md`)
- Overview dashboard → Local API runner: starts analysis (evidence: `README.md`)
- CLI runner → Semgrep scanner: runs scan (evidence: `main.py`)
- Local API runner → Semgrep scanner: runs scan (evidence: `README.md`)
- Semgrep scanner → Source context: provides findings (evidence: `README.md`)
- Source context → Finding qualification: provides source window (evidence: `README.md`)
- Finding qualification → LLM client: requests qualification (evidence: `triage.py`)
- Mitigation advice → LLM client: requests suggestion (evidence: `mitigation.py`)
- LLM client → LLM service: sends prompt (evidence: `llm_client.py`)
- Local API runner → Source context: extracts context (evidence: `README.md`)
- Local API runner → Finding qualification: qualifies findings (evidence: `README.md`)
- Local API runner → Mitigation advice: mitigates confirmed (evidence: `README.md`)
- CLI runner → Source context: extracts context (evidence: `main.py`)
- CLI runner → Finding qualification: qualifies findings (evidence: `main.py`)
- CLI runner → Mitigation advice: mitigates confirmed (evidence: `main.py`)
- Local API runner → Metrics evaluation: evaluates findings (evidence: `README.md`)
- Local API runner → Run provenance: records provenance (evidence: `launcher.py`)
- Local API runner → HTML report: generates report (evidence: `README.md`)
- CLI runner → Metrics evaluation: evaluates findings (evidence: `main.py`)
- CLI runner → Run provenance: records provenance (evidence: `main.py`)
- CLI runner → HTML report: generates report (evidence: `main.py`)
- Local API runner → Analysis artifacts: writes run artifacts (evidence: `README.md`)
- CLI runner → Analysis artifacts: writes run artifacts (evidence: `main.py`)
- HTML report → Analysis artifacts: saves HTML report (evidence: `README.md`)
- Artifact access → Analysis artifacts: reads saved artifacts (evidence: `web/lib/academic-data.ts`)
- Artifact access → Artifact interpretation: interprets artifacts (evidence: `web/lib/academic-data.ts`)
- Analysis artifacts → Overview dashboard: supplies analysis data (evidence: `README.md`)
- Analysis artifacts → Analysis views: supplies analysis data (evidence: `README.md`)
- Analysis artifacts → Finding views: supplies findings (evidence: `README.md`)
- Analysis artifacts → Evaluation summary: supplies evaluation (evidence: `README.md`)
- Analysis artifacts → Report views: supplies reports (evidence: `README.md`)
