# defiaudit0x/smart-contract-auditor architecture

> Architecture diagram of the GitHub repository defiaudit0x/smart-contract-auditor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/defiaudit0x/smart-contract-auditor
- Repository: https://github.com/defiaudit0x/smart-contract-auditor

## Overview

Smart Contract Auditor accepts contract code through web/API and CLI entry points, routes requests to audit modes, and combines multi-pass LLM analysis with deterministic scans and verification to produce findings and reports. Its documented capabilities also include multi-language analysis, streaming, diff audits, gas profiling, SBOM and SARIF output, and persistent learned knowledge. The graph uses README statements and SOURCE INDEX references; unsampled implementation details are represented only where those sources support the relationship.

Main entry points: [`orchestrator.py`](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/orchestrator.py) (Analysis dispatch), [`agents/pipeline.py`](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/pipeline.py) (LLM pipeline), [`audit_service.py`](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/audit_service.py) (Audit service), [`agents/pre_scan.py`](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/pre_scan.py) (Parallel pre-scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_web["Web interface<br/>[web_ui.py]"]
  node_api["REST API<br/>[api_routes.py]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_routing["Audit orchestration"]
  node_service["Audit service<br/>[audit_service.py]"]
  node_dispatch["Analysis dispatch<br/>[orchestrator.py]"]
end

subgraph group_analysis["Analysis engines"]
  node_pipeline["LLM pipeline<br/>[pipeline.py]"]
  node_prescan["Parallel pre-scan<br/>[pre_scan.py]"]
  node_llm["Model clients<br/>[llm_client.py]"]
  node_static["Static analysis"]
  node_languages["Language analyzers"]
  node_multiaudit["Multi-model audit<br/>[multiaudit.py]"]
  node_hierarchical["Hierarchical audit"]
  node_diff["Diff audit<br/>[diff_audit.py]"]
  node_gas["Gas profiling<br/>[gas_profiler.py]"]
end

subgraph group_verification["Verification and reports"]
  node_validation["Finding validation<br/>[validation.py]"]
  node_gate["Audit gate<br/>[gate_validator.py]"]
  node_scoring["CVSS scoring<br/>[cvss_scorer.py]"]
  node_reports["Report formats<br/>[sarif_export.py]"]
  node_sbom["SBOM generation<br/>[sbom.py]"]
end

subgraph group_knowledge["Learning and knowledge"]
  node_pattern["Pattern learner<br/>[pattern_learner.py]"]
  node_rag["Knowledge retrieval<br/>[rag.py]"]
  node_database[("Knowledge database<br/>[db.py]")]
end

node_user(("Auditor user"))
node_modelservice["LLM provider"]

node_user -->|"submits code"| node_web
node_user -->|"submits code"| node_api
node_user -->|"runs audit"| node_cli
node_api -->|"routes analysis"| node_dispatch
node_web -.->|"dispatches analysis"| node_dispatch
node_cli -->|"runs audit"| node_service
node_service -->|"runs multi-audit"| node_multiaudit
node_service -->|"runs hierarchical"| node_hierarchical
node_service -->|"runs diff audit"| node_diff
node_dispatch -->|"dispatches audit"| node_pipeline
node_dispatch -->|"dispatches mode"| node_multiaudit
node_dispatch -->|"dispatches mode"| node_hierarchical
node_dispatch -->|"dispatches analysis"| node_static
node_dispatch -->|"dispatches analysis"| node_gas
node_pipeline -->|"runs pre-scan"| node_prescan
node_pipeline -->|"validates findings"| node_validation
node_pipeline -->|"requests analysis"| node_llm
node_llm -->|"sends prompts"| node_modelservice
node_prescan -->|"loads learned patterns"| node_pattern
node_prescan -->|"runs scan"| node_sbom
node_validation -->|"scores findings"| node_scoring
node_validation -.->|"applies gate"| node_gate
node_pipeline -->|"retrieves context"| node_rag
node_pattern -->|"mines candidates"| node_llm
node_rag -->|"queries patterns"| node_database
node_pattern -->|"stores patterns"| node_database
node_service -.->|"exports reports"| node_reports
node_user -.->|"compares versions"| node_diff
node_user -.->|"requests profiling"| node_gas
node_user -.->|"requests SBOM"| node_sbom
node_user -.->|"requests SARIF"| node_reports
node_user -.->|"configures provider"| node_modelservice
node_pipeline -.->|"analyzes contracts"| node_languages

click node_web "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/web_ui.py"
click node_api "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/api_routes.py"
click node_cli "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/main.py"
click node_service "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/audit_service.py"
click node_dispatch "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/orchestrator.py"
click node_pipeline "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/pipeline.py"
click node_prescan "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/pre_scan.py"
click node_llm "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/llm_client.py"
click node_static "https://github.com/defiaudit0x/smart-contract-auditor/tree/main/static_analysis"
click node_languages "https://github.com/defiaudit0x/smart-contract-auditor/tree/main/analyzers"
click node_multiaudit "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/multiaudit.py"
click node_hierarchical "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/hierarchical_audit.py"
click node_diff "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/diff_audit.py"
click node_gas "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/gas_profiler.py"
click node_validation "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/validation.py"
click node_gate "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/gate_validator.py"
click node_scoring "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/cvss_scorer.py"
click node_reports "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/sarif_export.py"
click node_sbom "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/sbom.py"
click node_pattern "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/pattern_learner.py"
click node_rag "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/knowledge_base/rag.py"
click node_database "https://github.com/defiaudit0x/smart-contract-auditor/blob/main/knowledge_base/db.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_web,node_api,node_cli,node_user toneBlue
class node_service,node_dispatch toneAmber
class node_pipeline,node_prescan,node_llm,node_static,node_languages,node_multiaudit,node_hierarchical,node_diff,node_gas toneMint
class node_validation,node_gate,node_scoring,node_reports,node_sbom toneRose
class node_pattern,node_rag,node_database,node_modelservice toneIndigo
```

## Components

### User interfaces

- [Web interface](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/web_ui.py): `web_ui.py`
- [REST API](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/api_routes.py): `api_routes.py`
- [CLI](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/main.py): `main.py`

### Audit orchestration

- [Audit service](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/audit_service.py): `audit_service.py`
- [Analysis dispatch](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/orchestrator.py): `orchestrator.py`

### Analysis engines

- [LLM pipeline](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/pipeline.py): `agents/pipeline.py`
- [Parallel pre-scan](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/pre_scan.py): `agents/pre_scan.py`
- [Model clients](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/llm_client.py): `agents/llm_client.py`
- [Static analysis](https://github.com/defiaudit0x/smart-contract-auditor/tree/main/static_analysis): `static_analysis`
- [Language analyzers](https://github.com/defiaudit0x/smart-contract-auditor/tree/main/analyzers): `analyzers`
- [Multi-model audit](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/multiaudit.py): `multiaudit.py`
- [Hierarchical audit](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/hierarchical_audit.py): `hierarchical_audit.py`
- [Diff audit](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/diff_audit.py): `diff_audit.py`
- [Gas profiling](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/gas_profiler.py): `gas_profiler.py`

### Verification and reports

- [Finding validation](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/validation.py): `agents/validation.py`
- [Audit gate](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/gate_validator.py): `gate_validator.py`
- [CVSS scoring](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/cvss_scorer.py): `cvss_scorer.py`
- [Report formats](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/sarif_export.py): `sarif_export.py`
- [SBOM generation](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/sbom.py): `sbom.py`

### Learning and knowledge

- [Pattern learner](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/agents/pattern_learner.py): `agents/pattern_learner.py`
- [Knowledge retrieval](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/knowledge_base/rag.py): `knowledge_base/rag.py`
- [Knowledge database](https://github.com/defiaudit0x/smart-contract-auditor/blob/main/knowledge_base/db.py): `knowledge_base/db.py`

### Other components

- **Auditor user**
- **LLM provider**

## Connections

- Auditor user → Web interface: submits code
- Auditor user → REST API: submits code
- Auditor user → CLI: runs audit
- REST API → Analysis dispatch: routes analysis (evidence: `api_routes.py`)
- Web interface → Analysis dispatch: dispatches analysis
- CLI → Audit service: runs audit (evidence: `main.py`)
- Audit service → Multi-model audit: runs multi-audit (evidence: `audit_service.py`)
- Audit service → Hierarchical audit: runs hierarchical (evidence: `audit_service.py`)
- Audit service → Diff audit: runs diff audit (evidence: `audit_service.py`)
- Analysis dispatch → LLM pipeline: dispatches audit (evidence: `orchestrator.py`)
- Analysis dispatch → Multi-model audit: dispatches mode (evidence: `orchestrator.py`)
- Analysis dispatch → Hierarchical audit: dispatches mode (evidence: `orchestrator.py`)
- Analysis dispatch → Static analysis: dispatches analysis (evidence: `orchestrator.py`)
- Analysis dispatch → Gas profiling: dispatches analysis (evidence: `orchestrator.py`)
- LLM pipeline → Parallel pre-scan: runs pre-scan (evidence: `agents/pipeline.py`)
- LLM pipeline → Finding validation: validates findings (evidence: `agents/pipeline.py`)
- LLM pipeline → Model clients: requests analysis (evidence: `agents/pipeline.py`)
- Model clients → LLM provider: sends prompts (evidence: `agents/llm_client.py`)
- Parallel pre-scan → Pattern learner: loads learned patterns (evidence: `agents/pre_scan.py`)
- Parallel pre-scan → SBOM generation: runs scan (evidence: `agents/pre_scan.py`)
- Finding validation → CVSS scoring: scores findings (evidence: `agents/validation.py`)
- Finding validation → Audit gate: applies gate
- LLM pipeline → Knowledge retrieval: retrieves context (evidence: `agents/pipeline.py`)
- Pattern learner → Model clients: mines candidates (evidence: `agents/pattern_learner.py`)
- Knowledge retrieval → Knowledge database: queries patterns (evidence: `knowledge_base/rag.py`)
- Pattern learner → Knowledge database: stores patterns
- Audit service → Report formats: exports reports
- Auditor user → Diff audit: compares versions
- Auditor user → Gas profiling: requests profiling
- Auditor user → SBOM generation: requests SBOM
- Auditor user → Report formats: requests SARIF
- Auditor user → LLM provider: configures provider
- LLM pipeline → Language analyzers: analyzes contracts (evidence: `agents/pipeline.py`)
