How akki2104/ai-code-audit-system works
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: graph.py Workflow Graph · main.py API Entry · security_auditor.py Security Audit · code_reviewer.py Code Review
Components 17
Frontend
Streamlit user interface and presentation layer
- Streamlit UI · User-facing app for uploads, repo URL input, and results display
frontend/streamlit_app.py
Backend
FastAPI entrypoint and application services
- API Entry · Backend entrypoint that exposes the audit service
main.py
Analysis Core
Agent workflow, parsing, models, and prompts
- Workflow Graph · LangGraph coordinator that sequences agents and branches on findings
app/agents/graph.py - Scanner · Initial repository scan and structure discovery
app/agents/scanner.py - Pattern Scan · Finds likely important files and code areas for deeper analysis
app/agents/pattern_scanner.py - Security Audit · Checks code for vulnerabilities and security issues
app/agents/security_auditor.py - Code Review · Detects maintainability and code-quality problems
app/agents/code_reviewer.py - Report Builder · Consolidates findings into final structured output
app/agents/report_generator.py - LLM Adapter · Swappable access layer for OpenAI or local Ollama/Mistral models
app/agents/llm.py - File Parser · Parses repository contents and extracts analyzable code segments
app/parsers/file_parser.py - Schemas · Structured findings, scores, and report objects shared across layers
app/models/schemas.py - Prompt Templates · Centralized prompts used by the analysis agents
app/prompts/templates.py
Support
Configuration, utilities, and deployment
- Config · Application settings and environment-driven configuration
app/config.py - Helpers · Common helper functions used across the backend
app/utils/helpers.py - Streamlit Config · Streamlit runtime and presentation settings
.streamlit/config.toml - Render Spec · Deployment configuration for the hosted backend
render.yaml
Sample Repo
Demo target repository used to exercise the audit pipeline
- Vulnerable App · Demo repository used to showcase the audit pipeline
sample_repos/vulnerable_app/app.py
Connections 22
- 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