# quantum-blade1/halluciguard architecture

> Architecture diagram of the GitHub repository quantum-blade1/halluciguard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quantum-blade1/halluciguard
- Repository: https://github.com/quantum-blade1/halluciguard

## Overview

HalluciGuard detects hallucinated and risky Python/JavaScript package imports, then presents findings and remediation in VS Code; it also exposes a Python pipeline through a dashboard/LSP runtime. The documented editor flow is scan → validate → score → offer a fix → show diagnostics and results. The graph uses the sampled `src` pipeline for the dashboard flow and shows the extension-to-bundled-scanner handoff documented in the README. Some extension and bundled-scanner internals were not sampled, so their links are limited to documented relationships.

Main entry points: [`src/core/pipeline.py`](https://github.com/quantum-blade1/halluciguard/blob/main/src/core/pipeline.py) (Pipeline orchestrator), [`vscode-extension/src/extension.ts`](https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/extension.ts) (Editor extension), [`src/agents/validator.py`](https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/validator.py) (Package validation), [`src/agents/profiler.py`](https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/profiler.py) (Risk profiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["VS Code experience"]
  node_extension["Editor extension<br/>[extension.ts]"]
  node_bridge["Scanner bridge<br/>[scanner_bridge.ts]"]
  node_diagnostics["Inline diagnostics<br/>[diagnostics.ts]"]
  node_results["Sidebar results"]
  node_webview["Risk WebView<br/>[webview_panel.ts]"]
end

subgraph group_runtime["Python runtime"]
  node_bundled_scanner["Bundled scanner CLI"]
  node_entrypoint["Runtime entrypoint<br/>[main.py]"]
  node_dashboard["Dashboard API<br/>[app.py]"]
  node_pipeline["Pipeline orchestrator<br/>[pipeline.py]"]
end

subgraph group_detection["Detection pipeline"]
  node_sentinel["Import extraction<br/>[sentinel.py]"]
  node_validator["Package validation<br/>[validator.py]"]
  node_profiler["Risk profiler<br/>[profiler.py]"]
  node_ast_parser["AST parser<br/>[ast_parser.py]"]
end

subgraph group_intelligence["Package intelligence"]
  node_bloom["Package bloom filter<br/>[bloom_filter.py]"]
  node_registry["Registry clients<br/>[registry_client.py]"]
  node_hallucinations[("Hallucination database")]
  node_levenshtein["Typosquat matching<br/>[levenshtein.py]"]
  node_cve[("CVE lookup and cache<br/>[cve_client.py]")]
end

subgraph group_audit["Remediation and audit"]
  node_remediator["Safe replacements<br/>[remediator.py]"]
  node_chroma[("Safe-package search<br/>[chroma_manager.py]")]
  node_auditor["Audit logging<br/>[auditor.py]"]
end

node_developer(("Developer"))

node_developer -->|"edits code"| node_extension
node_extension -.->|"starts scan"| node_bridge
node_bridge -->|"spawns; reads NDJSON"| node_bundled_scanner
node_bundled_scanner -.->|"runs agents"| node_sentinel
node_extension -->|"renders findings"| node_diagnostics
node_extension -->|"updates TreeView"| node_results
node_extension -->|"updates panel"| node_webview
node_entrypoint -->|"starts dashboard"| node_dashboard
node_dashboard -->|"calls process"| node_pipeline
node_pipeline -->|"extracts imports"| node_sentinel
node_pipeline -->|"validates imports"| node_validator
node_pipeline -->|"scores packages"| node_profiler
node_pipeline -->|"finds replacements"| node_remediator
node_pipeline -->|"logs decisions"| node_auditor
node_sentinel -->|"parses source"| node_ast_parser
node_validator -->|"checks names"| node_bloom
node_validator -->|"checks misses"| node_registry
node_validator -->|"checks names"| node_hallucinations
node_profiler -->|"checks typos"| node_levenshtein
node_profiler -->|"checks vulnerabilities"| node_cve
node_remediator -->|"searches alternatives"| node_chroma

click node_extension "https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/extension.ts"
click node_bridge "https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/scanner_bridge.ts"
click node_diagnostics "https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/diagnostics.ts"
click node_results "https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/results_provider.ts"
click node_webview "https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/webview_panel.ts"
click node_bundled_scanner "https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/scanner/halluciguard_scanner.py"
click node_entrypoint "https://github.com/quantum-blade1/halluciguard/blob/main/src/main.py"
click node_dashboard "https://github.com/quantum-blade1/halluciguard/blob/main/dashboard/app.py"
click node_pipeline "https://github.com/quantum-blade1/halluciguard/blob/main/src/core/pipeline.py"
click node_sentinel "https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/sentinel.py"
click node_validator "https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/validator.py"
click node_profiler "https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/profiler.py"
click node_ast_parser "https://github.com/quantum-blade1/halluciguard/blob/main/src/utils/ast_parser.py"
click node_bloom "https://github.com/quantum-blade1/halluciguard/blob/main/src/data/bloom_filter.py"
click node_registry "https://github.com/quantum-blade1/halluciguard/blob/main/src/data/registry_client.py"
click node_hallucinations "https://github.com/quantum-blade1/halluciguard/blob/main/src/data/hallucination_db.py"
click node_levenshtein "https://github.com/quantum-blade1/halluciguard/blob/main/src/utils/levenshtein.py"
click node_cve "https://github.com/quantum-blade1/halluciguard/blob/main/src/data/cve_client.py"
click node_remediator "https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/remediator.py"
click node_chroma "https://github.com/quantum-blade1/halluciguard/blob/main/src/data/chroma_manager.py"
click node_auditor "https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/auditor.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_extension,node_bridge,node_diagnostics,node_results,node_webview toneBlue
class node_bundled_scanner,node_entrypoint,node_dashboard,node_pipeline toneAmber
class node_sentinel,node_validator,node_profiler,node_ast_parser toneMint
class node_bloom,node_registry,node_hallucinations,node_levenshtein,node_cve toneRose
class node_remediator,node_chroma,node_auditor,node_developer toneIndigo
```

## Components

### VS Code experience

- [Editor extension](https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/extension.ts): `vscode-extension/src/extension.ts`
- [Scanner bridge](https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/scanner_bridge.ts): `vscode-extension/src/scanner_bridge.ts`
- [Inline diagnostics](https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/diagnostics.ts): `vscode-extension/src/diagnostics.ts`
- [Sidebar results](https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/results_provider.ts): `vscode-extension/src/results_provider.ts`
- [Risk WebView](https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/src/webview_panel.ts): `vscode-extension/src/webview_panel.ts`

### Python runtime

- [Bundled scanner CLI](https://github.com/quantum-blade1/halluciguard/blob/main/vscode-extension/scanner/halluciguard_scanner.py): `vscode-extension/scanner/halluciguard_scanner.py`
- [Runtime entrypoint](https://github.com/quantum-blade1/halluciguard/blob/main/src/main.py): `src/main.py`
- [Dashboard API](https://github.com/quantum-blade1/halluciguard/blob/main/dashboard/app.py): `dashboard/app.py`
- [Pipeline orchestrator](https://github.com/quantum-blade1/halluciguard/blob/main/src/core/pipeline.py): `src/core/pipeline.py`

### Detection pipeline

- [Import extraction](https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/sentinel.py): `src/agents/sentinel.py`
- [Package validation](https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/validator.py): `src/agents/validator.py`
- [Risk profiler](https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/profiler.py): `src/agents/profiler.py`
- [AST parser](https://github.com/quantum-blade1/halluciguard/blob/main/src/utils/ast_parser.py): `src/utils/ast_parser.py`

### Package intelligence

- [Package bloom filter](https://github.com/quantum-blade1/halluciguard/blob/main/src/data/bloom_filter.py): `src/data/bloom_filter.py`
- [Registry clients](https://github.com/quantum-blade1/halluciguard/blob/main/src/data/registry_client.py): `src/data/registry_client.py`
- [Hallucination database](https://github.com/quantum-blade1/halluciguard/blob/main/src/data/hallucination_db.py): `src/data/hallucination_db.py`
- [Typosquat matching](https://github.com/quantum-blade1/halluciguard/blob/main/src/utils/levenshtein.py): `src/utils/levenshtein.py`
- [CVE lookup and cache](https://github.com/quantum-blade1/halluciguard/blob/main/src/data/cve_client.py): `src/data/cve_client.py`

### Remediation and audit

- [Safe replacements](https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/remediator.py): `src/agents/remediator.py`
- [Safe-package search](https://github.com/quantum-blade1/halluciguard/blob/main/src/data/chroma_manager.py): `src/data/chroma_manager.py`
- [Audit logging](https://github.com/quantum-blade1/halluciguard/blob/main/src/agents/auditor.py): `src/agents/auditor.py`

### Other components

- **Developer**

## Connections

- Developer → Editor extension: edits code (evidence: `README.md`)
- Editor extension → Scanner bridge: starts scan
- Scanner bridge → Bundled scanner CLI: spawns; reads NDJSON (evidence: `README.md`)
- Bundled scanner CLI → Import extraction: runs agents
- Editor extension → Inline diagnostics: renders findings (evidence: `README.md`)
- Editor extension → Sidebar results: updates TreeView (evidence: `README.md`)
- Editor extension → Risk WebView: updates panel (evidence: `README.md`)
- Runtime entrypoint → Dashboard API: starts dashboard (evidence: `src/main.py`)
- Dashboard API → Pipeline orchestrator: calls process (evidence: `dashboard/app.py`)
- Pipeline orchestrator → Import extraction: extracts imports (evidence: `src/core/pipeline.py`)
- Pipeline orchestrator → Package validation: validates imports (evidence: `src/core/pipeline.py`)
- Pipeline orchestrator → Risk profiler: scores packages (evidence: `src/core/pipeline.py`)
- Pipeline orchestrator → Safe replacements: finds replacements (evidence: `src/core/pipeline.py`)
- Pipeline orchestrator → Audit logging: logs decisions (evidence: `src/core/pipeline.py`)
- Import extraction → AST parser: parses source (evidence: `src/agents/sentinel.py`)
- Package validation → Package bloom filter: checks names (evidence: `src/agents/validator.py`)
- Package validation → Registry clients: checks misses (evidence: `src/agents/validator.py`)
- Package validation → Hallucination database: checks names (evidence: `src/agents/validator.py`)
- Risk profiler → Typosquat matching: checks typos (evidence: `src/agents/profiler.py`)
- Risk profiler → CVE lookup and cache: checks vulnerabilities (evidence: `src/agents/profiler.py`)
- Safe replacements → Safe-package search: searches alternatives (evidence: `src/agents/remediator.py`)