# bunty5600/codelens architecture

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

- Interactive diagram: https://gitdiagram.com/bunty5600/codelens
- Repository: https://github.com/bunty5600/codelens

## Overview

CodeLens AI accepts pasted Python, ZIP projects, and GitHub repositories, then returns static metrics, risk estimates, quality insights, and reports. The React application submits requests to FastAPI; the API coordinates analysis, prediction, persistence, and retrieval. ZIP and GitHub processing have distinct project-level paths, while smell, debt, AI, quality-gate, and PDF features form additional insight branches. The README documents those capabilities, but excerpts do not show every route’s wiring; links for those branches reflect documented API responsibilities. The detailed metric-module call sequence is not fully sampled.

Main entry points: [`api/main.py`](https://github.com/bunty5600/codelens/blob/main/api/main.py) (FastAPI routes), [`analyzer/analyzer.py`](https://github.com/bunty5600/codelens/blob/main/analyzer/analyzer.py) (Analysis orchestrator), [`frontend/src/App.jsx`](https://github.com/bunty5600/codelens/blob/main/frontend/src/App.jsx) (React application), [`services/github_service.py`](https://github.com/bunty5600/codelens/blob/main/services/github_service.py) (Repository analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_webapp["React application<br/>[App.jsx]"]
  node_webclient["API client<br/>[api.js]"]
  node_authctx["Auth context<br/>[AuthContext.jsx]"]
  node_uploadui["Upload and GitHub<br/>[Upload.jsx]"]
  node_resultsui["Results and history<br/>[Results.jsx]"]
end

subgraph group_backend["API and identity"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_clerk["Clerk identity<br/>[clerk_auth.py]"]
end

subgraph group_analysis["Code analysis"]
  node_analyzer["Analysis orchestrator<br/>[analyzer.py]"]
  node_parser["Python AST parser<br/>[ast_parser.py]"]
  node_metrics["Metric extractors"]
  node_zipflow["ZIP analysis"]
  node_githubflow["Repository analysis<br/>[github_service.py]"]
end

subgraph group_insights["Quality insights"]
  node_predictor["Defect prediction<br/>[predictor.py]"]
  node_smells["Code smells<br/>[smell_service.py]"]
  node_debt["Technical debt<br/>[debt_service.py]"]
  node_ai["AI recommendations<br/>[ai_service.py]"]
  node_gate["Quality gate"]
  node_report["PDF report<br/>[report_service.py]"]
end

subgraph group_state["Persistence and integrations"]
  node_database[("Analysis database<br/>[database.py]")]
  node_github["GitHub repository"]
  node_groq["Groq API"]
end

node_developer(("Developer"))

node_developer -->|"uses"| node_webapp
node_webapp -->|"reads session"| node_authctx
node_webapp -->|"offers submission"| node_uploadui
node_webapp -->|"shows results"| node_resultsui
node_uploadui -->|"submits code"| node_webclient
node_resultsui -->|"requests results"| node_webclient
node_webclient -->|"HTTP requests"| node_api
node_authctx -->|"uses identity"| node_clerk
node_api -->|"validates session"| node_clerk
node_api -->|"analyzes pasted code"| node_analyzer
node_api -->|"analyzes ZIP"| node_zipflow
node_api -->|"analyzes repository"| node_githubflow
node_githubflow -->|"clones repository"| node_github
node_analyzer -->|"parses source"| node_parser
node_analyzer -->|"extracts metrics"| node_metrics
node_zipflow -->|"analyzes Python files"| node_analyzer
node_githubflow -->|"analyzes Python files"| node_analyzer
node_api -->|"predicts defect risk"| node_predictor
node_api -->|"detects smells"| node_smells
node_api -->|"scores debt"| node_debt
node_api -->|"requests recommendations"| node_ai
node_ai -->|"requests completions"| node_groq
node_api -->|"evaluates thresholds"| node_gate
node_api -->|"generates PDF"| node_report
node_api -->|"stores analyses"| node_database
node_api -->|"reads history"| node_database
node_api -->|"returns results"| node_resultsui

click node_webapp "https://github.com/bunty5600/codelens/blob/main/frontend/src/App.jsx"
click node_webclient "https://github.com/bunty5600/codelens/blob/main/frontend/src/services/api.js"
click node_authctx "https://github.com/bunty5600/codelens/blob/main/frontend/src/context/AuthContext.jsx"
click node_uploadui "https://github.com/bunty5600/codelens/blob/main/frontend/src/pages/Upload.jsx"
click node_resultsui "https://github.com/bunty5600/codelens/blob/main/frontend/src/pages/Results.jsx"
click node_api "https://github.com/bunty5600/codelens/blob/main/api/main.py"
click node_clerk "https://github.com/bunty5600/codelens/blob/main/api/clerk_auth.py"
click node_analyzer "https://github.com/bunty5600/codelens/blob/main/analyzer/analyzer.py"
click node_parser "https://github.com/bunty5600/codelens/blob/main/analyzer/ast_parser.py"
click node_metrics "https://github.com/bunty5600/codelens/blob/main/analyzer/complexity_metrics.py"
click node_zipflow "https://github.com/bunty5600/codelens/blob/main/services/analysis_service.py"
click node_githubflow "https://github.com/bunty5600/codelens/blob/main/services/github_service.py"
click node_predictor "https://github.com/bunty5600/codelens/blob/main/ml/predictor.py"
click node_smells "https://github.com/bunty5600/codelens/blob/main/services/smell_service.py"
click node_debt "https://github.com/bunty5600/codelens/blob/main/services/debt_service.py"
click node_ai "https://github.com/bunty5600/codelens/blob/main/services/ai_service.py"
click node_gate "https://github.com/bunty5600/codelens/blob/main/services/quality_gate_service.py"
click node_report "https://github.com/bunty5600/codelens/blob/main/services/report_service.py"
click node_database "https://github.com/bunty5600/codelens/blob/main/api/database.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_webapp,node_webclient,node_authctx,node_uploadui,node_resultsui toneBlue
class node_api,node_clerk toneAmber
class node_analyzer,node_parser,node_metrics,node_zipflow,node_githubflow toneMint
class node_predictor,node_smells,node_debt,node_ai,node_gate,node_report toneRose
class node_database,node_github,node_groq,node_developer toneIndigo
```

## Components

### Web application

- [React application](https://github.com/bunty5600/codelens/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/bunty5600/codelens/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Auth context](https://github.com/bunty5600/codelens/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Upload and GitHub](https://github.com/bunty5600/codelens/blob/main/frontend/src/pages/Upload.jsx): `frontend/src/pages/Upload.jsx`
- [Results and history](https://github.com/bunty5600/codelens/blob/main/frontend/src/pages/Results.jsx): `frontend/src/pages/Results.jsx`

### API and identity

- [FastAPI routes](https://github.com/bunty5600/codelens/blob/main/api/main.py): `api/main.py`
- [Clerk identity](https://github.com/bunty5600/codelens/blob/main/api/clerk_auth.py): `api/clerk_auth.py`

### Code analysis

- [Analysis orchestrator](https://github.com/bunty5600/codelens/blob/main/analyzer/analyzer.py): `analyzer/analyzer.py`
- [Python AST parser](https://github.com/bunty5600/codelens/blob/main/analyzer/ast_parser.py): `analyzer/ast_parser.py`
- [Metric extractors](https://github.com/bunty5600/codelens/blob/main/analyzer/complexity_metrics.py): `analyzer/complexity_metrics.py`
- [ZIP analysis](https://github.com/bunty5600/codelens/blob/main/services/analysis_service.py): `services/analysis_service.py`
- [Repository analysis](https://github.com/bunty5600/codelens/blob/main/services/github_service.py): `services/github_service.py`

### Quality insights

- [Defect prediction](https://github.com/bunty5600/codelens/blob/main/ml/predictor.py): `ml/predictor.py`
- [Code smells](https://github.com/bunty5600/codelens/blob/main/services/smell_service.py): `services/smell_service.py`
- [Technical debt](https://github.com/bunty5600/codelens/blob/main/services/debt_service.py): `services/debt_service.py`
- [AI recommendations](https://github.com/bunty5600/codelens/blob/main/services/ai_service.py): `services/ai_service.py`
- [Quality gate](https://github.com/bunty5600/codelens/blob/main/services/quality_gate_service.py): `services/quality_gate_service.py`
- [PDF report](https://github.com/bunty5600/codelens/blob/main/services/report_service.py): `services/report_service.py`

### Persistence and integrations

- [Analysis database](https://github.com/bunty5600/codelens/blob/main/api/database.py): `api/database.py`
- **GitHub repository**
- **Groq API**

### Other components

- **Developer**

## Connections

- Developer → React application: uses
- React application → Auth context: reads session
- React application → Upload and GitHub: offers submission
- React application → Results and history: shows results
- Upload and GitHub → API client: submits code
- Results and history → API client: requests results
- API client → FastAPI routes: HTTP requests
- Auth context → Clerk identity: uses identity
- FastAPI routes → Clerk identity: validates session
- FastAPI routes → Analysis orchestrator: analyzes pasted code
- FastAPI routes → ZIP analysis: analyzes ZIP
- FastAPI routes → Repository analysis: analyzes repository
- Repository analysis → GitHub repository: clones repository
- Analysis orchestrator → Python AST parser: parses source
- Analysis orchestrator → Metric extractors: extracts metrics
- ZIP analysis → Analysis orchestrator: analyzes Python files
- Repository analysis → Analysis orchestrator: analyzes Python files
- FastAPI routes → Defect prediction: predicts defect risk
- FastAPI routes → Code smells: detects smells
- FastAPI routes → Technical debt: scores debt
- FastAPI routes → AI recommendations: requests recommendations
- AI recommendations → Groq API: requests completions
- FastAPI routes → Quality gate: evaluates thresholds
- FastAPI routes → PDF report: generates PDF
- FastAPI routes → Analysis database: stores analyses
- FastAPI routes → Analysis database: reads history
- FastAPI routes → Results and history: returns results