# akki2104/ai-code-audit-system architecture

> Architecture diagram of the GitHub repository akki2104/ai-code-audit-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akki2104/ai-code-audit-system
- Repository: https://github.com/akki2104/ai-code-audit-system

## Overview

This repository is a Python-based, two-tier code audit system: a FastAPI backend orchestrates AI analysis, and a Streamlit frontend presents the results to the user.

1. **User entry points**
   - The system accepts either a ZIP upload or a GitHub repository URL, as described in the README.
   - The UI lives in `frontend/streamlit_app.py`.
   - The backend entry point is `main.py`, which likely exposes the API used by the Streamlit app.

2. **Core orchestration boundary**
   - The main analysis pipeline is implemented under `app/agents/`.
   - `app/agents/graph.py` is the central workflow coordinator, using LangGraph to run agents in sequence and trigger conditional re-analysis.
   - This is the main architectural “spine” of the system.

3. **Agent pipeline**
   - The workflow follows a staged analysis flow:
     - `scanner.py` / `pattern_scanner.py` gather file structure and identify likely important code areas.
     - `security_auditor.py` checks for vulnerabilities.
     - `code_reviewer.py` checks code quality and maintainability issues.
     - `report_generator.py` consolidates findings into the final output.
   - This separation is important: scanning, security analysis, quality review, and reporting are distinct concerns.

4. **Conditional deep re-audit**
   - The README describes a branch in the graph when critical findings exceed a threshold.
   - That means the architecture is not just linear; it has a decision point that can re-run focused analysis on high-risk files.

5. **Shared data model**
   - `app/models/schemas.py` defines the structured objects passed between agents and returned to the UI.
   - This is the contract boundary for findings, severity, health score, file-level results, and summary output.

6. **Code parsing and repository inspection**
   - `app/parsers/file_parser.py` handles source ingestion and likely AST-based parsing, which is called out in the README.
   - This is where raw repository contents become analyzable code segments, dependency hints, and file metadata.

7. **LLM abstraction layer**
   - `app/agents/llm.py` isolates model access from the rest of the pipeline.
   - The repo supports both local Ollama/Mistral and OpenAI, so the architecture treats the model provider as a swappable backend rather than embedding provider logic in each agent.

8. **Prompting layer**
   - `app/prompts/templates.py` centralizes the prompt templates used by the agents.
   - This separates analysis policy from execution logic and makes the behavior of each agent easier to tune.

9. **Configuration and environment**
   - `app/config.py`, `.env.example`, and `requirements.txt` define runtime configuration and dependencies.
   - `.streamlit/config.toml` controls the Streamlit app behavior.
   - `render.yaml` indicates the backend is deployable on Render, so deployment is part of the repo’s operational design.

10. **Utilities and helpers**
   - `app/utils/helpers.py` contains supporting functions used across agents and parsing/reporting code.
   - This is the shared utility boundary, keeping non-domain logic out of the agent modules.

11. **Demo/sample input**
   - `sample_repos/vulnerable_app/` is an intentionally vulnerable sample repository used to demonstrate the scanner and audit pipeline.
   - It is not part of the application runtime itself, but it is useful for understanding the expected input shape and output behavior.

12. **End-to-end data flow**
   - Repository contents enter through the UI, are parsed and scanned, pass through security and quality agents, may trigger re-audit, and finally get aggregated into a report.
   - The final output is displayed in Streamlit and can be exported as JSON, which makes the reporting layer the external-facing boundary of the analysis engine.

Main entry points: [`app/agents/graph.py`](https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/graph.py) (Workflow Graph), [`main.py`](https://github.com/akki2104/ai-code-audit-system/blob/main/main.py) (API Entry), [`app/agents/security_auditor.py`](https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/security_auditor.py) (Security Audit), [`app/agents/code_reviewer.py`](https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/code_reviewer.py) (Code Review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_frontend["Frontend"]
  node_n_ui["Streamlit UI<br/>frontend app<br/>[streamlit_app.py]"]
end

subgraph group_g_backend["Backend"]
  node_n_api["API Entry<br/>FastAPI app<br/>[main.py]"]
end

subgraph group_g_core["Analysis Core"]
  node_n_graph{{"Workflow Graph<br/>orchestrator<br/>[graph.py]"}}
  node_n_scanner["Scanner<br/>[scanner.py]"]
  node_n_pattern["Pattern Scan<br/>signal extractor<br/>[pattern_scanner.py]"]
  node_n_sec["Security Audit<br/>risk analysis"]
  node_n_review["Code Review<br/>quality analysis<br/>[code_reviewer.py]"]
  node_n_report["Report Builder<br/>report synthesis"]
  node_n_llm["LLM Adapter<br/>model gateway<br/>[llm.py]"]
  node_n_parser["File Parser<br/>source ingestion<br/>[file_parser.py]"]
  node_n_models["Schemas<br/>data contract<br/>[schemas.py]"]
  node_n_prompts["Prompt Templates<br/>prompt library<br/>[templates.py]"]
end

subgraph group_g_support["Support"]
  node_n_config["Config<br/>[config.py]"]
  node_n_utils["Helpers<br/>shared utilities<br/>[helpers.py]"]
  node_n_streamlit_cfg["Streamlit Config<br/>ui config<br/>[config.toml]"]
  node_n_render["Render Spec<br/>deployment config<br/>[render.yaml]"]
end

subgraph group_g_sample["Sample Repo"]
  node_n_sample["Vulnerable App<br/>sample target<br/>[app.py]"]
end

node_n_ui -->|"submit repo"| node_n_api
node_n_api -->|"start audit"| node_n_graph
node_n_graph -->|"ingest source"| node_n_parser
node_n_parser -->|"scan inputs"| node_n_scanner
node_n_scanner -->|"rank files"| node_n_pattern
node_n_pattern -->|"security pass"| node_n_sec
node_n_pattern -->|"quality pass"| node_n_review
node_n_sec -->|"findings"| node_n_models
node_n_review -->|"findings"| node_n_models
node_n_graph -.->|"deep re-audit"| node_n_sec
node_n_graph -.->|"deep re-review"| node_n_review
node_n_sec -->|"model calls"| node_n_llm
node_n_review -->|"model calls"| node_n_llm
node_n_graph -->|"prompting"| node_n_prompts
node_n_graph -->|"compile report"| node_n_report
node_n_report -->|"structured output"| node_n_models
node_n_ui -->|"display results"| node_n_models
node_n_api -->|"runtime settings"| node_n_config
node_n_ui -->|"ui runtime"| node_n_streamlit_cfg
node_n_api -->|"deploy"| node_n_render
node_n_graph -->|"shared helpers"| node_n_utils
node_n_sample -.->|"demo input"| node_n_parser

click node_n_ui "https://github.com/akki2104/ai-code-audit-system/blob/main/frontend/streamlit_app.py"
click node_n_api "https://github.com/akki2104/ai-code-audit-system/blob/main/main.py"
click node_n_graph "https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/graph.py"
click node_n_scanner "https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/scanner.py"
click node_n_pattern "https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/pattern_scanner.py"
click node_n_sec "https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/security_auditor.py"
click node_n_review "https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/code_reviewer.py"
click node_n_report "https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/report_generator.py"
click node_n_llm "https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/llm.py"
click node_n_parser "https://github.com/akki2104/ai-code-audit-system/blob/main/app/parsers/file_parser.py"
click node_n_models "https://github.com/akki2104/ai-code-audit-system/blob/main/app/models/schemas.py"
click node_n_prompts "https://github.com/akki2104/ai-code-audit-system/blob/main/app/prompts/templates.py"
click node_n_config "https://github.com/akki2104/ai-code-audit-system/blob/main/app/config.py"
click node_n_utils "https://github.com/akki2104/ai-code-audit-system/blob/main/app/utils/helpers.py"
click node_n_streamlit_cfg "https://github.com/akki2104/ai-code-audit-system/blob/main/.streamlit/config.toml"
click node_n_render "https://github.com/akki2104/ai-code-audit-system/blob/main/render.yaml"
click node_n_sample "https://github.com/akki2104/ai-code-audit-system/blob/main/sample_repos/vulnerable_app/app.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_n_ui toneBlue
class node_n_api toneAmber
class node_n_graph,node_n_scanner,node_n_pattern,node_n_sec,node_n_review,node_n_report,node_n_llm,node_n_parser,node_n_models,node_n_prompts toneMint
class node_n_config,node_n_utils,node_n_streamlit_cfg,node_n_render toneRose
class node_n_sample toneIndigo
```

## Components

### Frontend

Streamlit user interface and presentation layer

- [Streamlit UI](https://github.com/akki2104/ai-code-audit-system/blob/main/frontend/streamlit_app.py): frontend app · User-facing app for uploads, repo URL input, and results display · `frontend/streamlit_app.py`

### Backend

FastAPI entrypoint and application services

- [API Entry](https://github.com/akki2104/ai-code-audit-system/blob/main/main.py): FastAPI app · Backend entrypoint that exposes the audit service · `main.py`

### Analysis Core

Agent workflow, parsing, models, and prompts

- [Workflow Graph](https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/graph.py): orchestrator · LangGraph coordinator that sequences agents and branches on findings · `app/agents/graph.py`
- [Scanner](https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/scanner.py): repo scanner · Initial repository scan and structure discovery · `app/agents/scanner.py`
- [Pattern Scan](https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/pattern_scanner.py): signal extractor · Finds likely important files and code areas for deeper analysis · `app/agents/pattern_scanner.py`
- [Security Audit](https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/security_auditor.py): risk analysis · Checks code for vulnerabilities and security issues · `app/agents/security_auditor.py`
- [Code Review](https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/code_reviewer.py): quality analysis · Detects maintainability and code-quality problems · `app/agents/code_reviewer.py`
- [Report Builder](https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/report_generator.py): report synthesis · Consolidates findings into final structured output · `app/agents/report_generator.py`
- [LLM Adapter](https://github.com/akki2104/ai-code-audit-system/blob/main/app/agents/llm.py): model gateway · Swappable access layer for OpenAI or local Ollama/Mistral models · `app/agents/llm.py`
- [File Parser](https://github.com/akki2104/ai-code-audit-system/blob/main/app/parsers/file_parser.py): source ingestion · Parses repository contents and extracts analyzable code segments · `app/parsers/file_parser.py`
- [Schemas](https://github.com/akki2104/ai-code-audit-system/blob/main/app/models/schemas.py): data contract · Structured findings, scores, and report objects shared across layers · `app/models/schemas.py`
- [Prompt Templates](https://github.com/akki2104/ai-code-audit-system/blob/main/app/prompts/templates.py): prompt library · Centralized prompts used by the analysis agents · `app/prompts/templates.py`

### Support

Configuration, utilities, and deployment

- [Config](https://github.com/akki2104/ai-code-audit-system/blob/main/app/config.py): runtime config · Application settings and environment-driven configuration · `app/config.py`
- [Helpers](https://github.com/akki2104/ai-code-audit-system/blob/main/app/utils/helpers.py): shared utilities · Common helper functions used across the backend · `app/utils/helpers.py`
- [Streamlit Config](https://github.com/akki2104/ai-code-audit-system/blob/main/.streamlit/config.toml): ui config · Streamlit runtime and presentation settings · `.streamlit/config.toml`
- [Render Spec](https://github.com/akki2104/ai-code-audit-system/blob/main/render.yaml): deployment config · Deployment configuration for the hosted backend · `render.yaml`

### Sample Repo

Demo target repository used to exercise the audit pipeline

- [Vulnerable App](https://github.com/akki2104/ai-code-audit-system/blob/main/sample_repos/vulnerable_app/app.py): sample target · Demo repository used to showcase the audit pipeline · `sample_repos/vulnerable_app/app.py`

## Connections

- Streamlit UI → API Entry: submit repo · Frontend sends upload or GitHub repository request to backend
- API Entry → Workflow Graph: start audit · Backend hands the repository to the workflow coordinator
- Workflow Graph → File Parser: ingest source · Workflow begins by parsing repository files and metadata
- File Parser → Scanner: scan inputs · Parsed repository data feeds initial scanning
- Scanner → Pattern Scan: rank files · Scanner identifies high-signal files for deeper analysis
- Pattern Scan → Security Audit: security pass · Likely important areas are reviewed for vulnerabilities
- Pattern Scan → Code Review: quality pass · Likely important areas are reviewed for maintainability issues
- Security Audit → Schemas: findings · Security results are normalized into shared schemas
- Code Review → Schemas: findings · Review results are normalized into shared schemas
- Workflow Graph → Security Audit: deep re-audit · Critical findings can trigger focused re-analysis of risky files
- Workflow Graph → Code Review: deep re-review · Workflow can re-run review on files flagged as high risk
- Security Audit → LLM Adapter: model calls · Security agent uses the shared model adapter
- Code Review → LLM Adapter: model calls · Review agent uses the shared model adapter
- Workflow Graph → Prompt Templates: prompting · Workflow relies on centralized templates for agent instructions
- Workflow Graph → Report Builder: compile report · Final findings are consolidated into the output report
- Report Builder → Schemas: structured output · Report generator emits the final structured schema
- Streamlit UI → Schemas: display results · Frontend renders the structured audit output
- API Entry → Config: runtime settings · Backend loads environment and application configuration
- Streamlit UI → Streamlit Config: ui runtime · Streamlit app uses its own configuration file
- API Entry → Render Spec: deploy · Deployment specification for hosting the backend
- Workflow Graph → Helpers: shared helpers · Workflow and agents reuse common helper functions
- Vulnerable App → File Parser: demo input · Sample repository shows the expected ingestion target
