# iamhusnain-1214/codevision architecture

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

- Interactive diagram: https://gitdiagram.com/iamhusnain-1214/codevision
- Repository: https://github.com/iamhusnain-1214/codevision

## Overview

CodeVision is an algorithm visualizer and debugger. A user selects a built-in module or submits Python/C++ code; the backend traces execution, returns snapshots, and saves successful runs for replay in History. Fehm separately explains problems, diagnoses logic, and estimates complexity through an AI fallback chain. The UI renders traces with code, variables, playback, and structure-specific diagrams. The README documents six tracing modules, account features, admin capabilities, and integrations; unsampled module details are represented at subsystem level rather than inferred call-by-call.

Main entry points: [`frontend/src/api/client.js`](https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/api/client.js) (API client), [`backend/db.py`](https://github.com/iamhusnain-1214/codevision/blob/main/backend/db.py) (Application data), [`backend/routes/custom_routes.py`](https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/custom_routes.py) (Custom trace route), [`backend/ai_orchestrator.py`](https://github.com/iamhusnain-1214/codevision/blob/main/backend/ai_orchestrator.py) (AI orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App routes<br/>[App.jsx]"]
  node_moduleui["Module pages"]
  node_historyui["History replay<br/>[History.jsx]"]
  node_visuals["Trace visualizations"]
  node_api["API client<br/>[client.js]"]
end

subgraph group_trace["Tracing"]
  node_traceapi["Built-in trace routes<br/>[trace_routes.py]"]
  node_tracers["Built-in tracers<br/>[tracer_array.py]"]
  node_customapi["Custom trace route<br/>[custom_routes.py]"]
  node_pythontrace["Python tracer<br/>[tracer_custom.py]"]
  node_cpptrace["C++ tracer"]
end

subgraph group_accounts["Accounts and history"]
  node_authui["Session context<br/>[AuthContext.jsx]"]
  node_authapi["Auth routes<br/>[auth_routes.py]"]
  node_authlogic["Auth validation<br/>[auth.py]"]
  node_db[("Application data<br/>[db.py]")]
end

subgraph group_fehm["Fehm and analysis"]
  node_fehmui["Fehm interface<br/>[Fehm.jsx]"]
  node_fehmapi["Fehm routes<br/>[fehm_routes.py]"]
  node_orchestrator["AI orchestration<br/>[ai_orchestrator.py]"]
  node_cache[("AI cache<br/>[ai_cache.py]")]
  node_gemini["Gemini provider<br/>[gemini_service.py]"]
  node_groq["Groq provider<br/>[grok_service.py]"]
  node_complexity["Complexity analyzer"]
end

subgraph group_operations["Admin and health"]
  node_admin["Admin features<br/>[admin_routes.py]"]
  node_health["Health endpoint<br/>[app.py]"]
end

node_user(("Learner"))
node_supabase[("Supabase")]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_moduleui
node_moduleui -->|"requests traces"| node_api
node_api -->|"calls API"| node_traceapi
node_traceapi -->|"dispatches traces"| node_tracers
node_traceapi -->|"saves runs"| node_db
node_user -->|"submits code"| node_customapi
node_api -->|"calls API"| node_customapi
node_customapi -->|"runs Python"| node_pythontrace
node_customapi -->|"runs C++"| node_cpptrace
node_customapi -->|"logs and saves"| node_db
node_historyui -->|"loads history"| node_api
node_historyui -->|"renders replay"| node_visuals
node_authui -->|"requests session"| node_api
node_api -->|"calls API"| node_authapi
node_authapi -->|"delegates auth"| node_authlogic
node_authlogic -->|"reads profile"| node_db
node_authlogic -->|"authenticates"| node_supabase
node_db -->|"queries"| node_supabase
node_fehmui -->|"requests coaching"| node_api
node_api -->|"calls API"| node_fehmapi
node_fehmapi -->|"requests AI"| node_orchestrator
node_fehmapi -->|"fallback analysis"| node_complexity
node_orchestrator -->|"checks cache"| node_cache
node_orchestrator -->|"tries primary"| node_gemini
node_orchestrator -->|"falls back"| node_groq
node_user -->|"administers"| node_admin
node_admin -->|"manages records"| node_db
node_user -.->|"health checks"| node_health
node_health -->|"checks database"| node_db

click node_app "https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/App.jsx"
click node_moduleui "https://github.com/iamhusnain-1214/codevision/tree/main/frontend/src/pages/modules"
click node_historyui "https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/pages/History.jsx"
click node_visuals "https://github.com/iamhusnain-1214/codevision/tree/main/frontend/src/components"
click node_api "https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/api/client.js"
click node_traceapi "https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/trace_routes.py"
click node_tracers "https://github.com/iamhusnain-1214/codevision/blob/main/backend/tracer_array.py"
click node_customapi "https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/custom_routes.py"
click node_pythontrace "https://github.com/iamhusnain-1214/codevision/blob/main/backend/tracer_custom.py"
click node_cpptrace "https://github.com/iamhusnain-1214/codevision/blob/main/backend/tracer_custom_cpp.py"
click node_authui "https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/context/AuthContext.jsx"
click node_authapi "https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/auth_routes.py"
click node_authlogic "https://github.com/iamhusnain-1214/codevision/blob/main/backend/auth.py"
click node_db "https://github.com/iamhusnain-1214/codevision/blob/main/backend/db.py"
click node_fehmui "https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/pages/Fehm.jsx"
click node_fehmapi "https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/fehm_routes.py"
click node_orchestrator "https://github.com/iamhusnain-1214/codevision/blob/main/backend/ai_orchestrator.py"
click node_cache "https://github.com/iamhusnain-1214/codevision/blob/main/backend/ai_cache.py"
click node_gemini "https://github.com/iamhusnain-1214/codevision/blob/main/backend/gemini_service.py"
click node_groq "https://github.com/iamhusnain-1214/codevision/blob/main/backend/grok_service.py"
click node_complexity "https://github.com/iamhusnain-1214/codevision/blob/main/backend/complexity_analyzer.py"
click node_admin "https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/admin_routes.py"
click node_health "https://github.com/iamhusnain-1214/codevision/blob/main/backend/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_app,node_moduleui,node_historyui,node_visuals,node_api toneBlue
class node_traceapi,node_tracers,node_customapi,node_pythontrace,node_cpptrace,node_supabase toneAmber
class node_authui,node_authapi,node_authlogic,node_db toneMint
class node_fehmui,node_fehmapi,node_orchestrator,node_cache,node_gemini,node_groq,node_complexity toneRose
class node_admin,node_health,node_user toneIndigo
```

## Components

### Web experience

- [App routes](https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Module pages](https://github.com/iamhusnain-1214/codevision/tree/main/frontend/src/pages/modules): `frontend/src/pages/modules`
- [History replay](https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/pages/History.jsx): `frontend/src/pages/History.jsx`
- [Trace visualizations](https://github.com/iamhusnain-1214/codevision/tree/main/frontend/src/components): `frontend/src/components`
- [API client](https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Tracing

- [Built-in trace routes](https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/trace_routes.py): `backend/routes/trace_routes.py`
- [Built-in tracers](https://github.com/iamhusnain-1214/codevision/blob/main/backend/tracer_array.py): `backend/tracer_array.py`
- [Custom trace route](https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/custom_routes.py): `backend/routes/custom_routes.py`
- [Python tracer](https://github.com/iamhusnain-1214/codevision/blob/main/backend/tracer_custom.py): `backend/tracer_custom.py`
- [C++ tracer](https://github.com/iamhusnain-1214/codevision/blob/main/backend/tracer_custom_cpp.py): `backend/tracer_custom_cpp.py`

### Accounts and history

- [Session context](https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Auth routes](https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/auth_routes.py): `backend/routes/auth_routes.py`
- [Auth validation](https://github.com/iamhusnain-1214/codevision/blob/main/backend/auth.py): `backend/auth.py`
- [Application data](https://github.com/iamhusnain-1214/codevision/blob/main/backend/db.py): `backend/db.py`

### Fehm and analysis

- [Fehm interface](https://github.com/iamhusnain-1214/codevision/blob/main/frontend/src/pages/Fehm.jsx): `frontend/src/pages/Fehm.jsx`
- [Fehm routes](https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/fehm_routes.py): `backend/routes/fehm_routes.py`
- [AI orchestration](https://github.com/iamhusnain-1214/codevision/blob/main/backend/ai_orchestrator.py): `backend/ai_orchestrator.py`
- [AI cache](https://github.com/iamhusnain-1214/codevision/blob/main/backend/ai_cache.py): `backend/ai_cache.py`
- [Gemini provider](https://github.com/iamhusnain-1214/codevision/blob/main/backend/gemini_service.py): `backend/gemini_service.py`
- [Groq provider](https://github.com/iamhusnain-1214/codevision/blob/main/backend/grok_service.py): `backend/grok_service.py`
- [Complexity analyzer](https://github.com/iamhusnain-1214/codevision/blob/main/backend/complexity_analyzer.py): `backend/complexity_analyzer.py`

### Admin and health

- [Admin features](https://github.com/iamhusnain-1214/codevision/blob/main/backend/routes/admin_routes.py): `backend/routes/admin_routes.py`
- [Health endpoint](https://github.com/iamhusnain-1214/codevision/blob/main/backend/app.py): `backend/app.py`

### Other components

- **Learner**
- **Supabase**

## Connections

- Learner → App routes: uses (evidence: `frontend/src/App.jsx`)
- App routes → Module pages: routes to (evidence: `frontend/src/App.jsx`)
- Module pages → API client: requests traces (evidence: `frontend/src/pages/modules/ArrayModule.jsx`)
- API client → Built-in trace routes: calls API (evidence: `README.md`)
- Built-in trace routes → Built-in tracers: dispatches traces (evidence: `backend/routes/trace_routes.py`)
- Built-in trace routes → Application data: saves runs (evidence: `backend/routes/trace_routes.py`)
- Learner → Custom trace route: submits code (evidence: `README.md`)
- API client → Custom trace route: calls API (evidence: `README.md`)
- Custom trace route → Python tracer: runs Python (evidence: `backend/routes/custom_routes.py`)
- Custom trace route → C++ tracer: runs C++ (evidence: `backend/routes/custom_routes.py`)
- Custom trace route → Application data: logs and saves (evidence: `backend/routes/custom_routes.py`)
- History replay → API client: loads history (evidence: `frontend/src/pages/History.jsx`)
- History replay → Trace visualizations: renders replay (evidence: `frontend/src/pages/History.jsx`)
- Session context → API client: requests session (evidence: `frontend/src/context/AuthContext.jsx`)
- API client → Auth routes: calls API (evidence: `README.md`)
- Auth routes → Auth validation: delegates auth (evidence: `backend/routes/auth_routes.py`)
- Auth validation → Application data: reads profile (evidence: `backend/auth.py`)
- Auth validation → Supabase: authenticates (evidence: `backend/auth.py`)
- Application data → Supabase: queries (evidence: `backend/db.py`)
- Fehm interface → API client: requests coaching (evidence: `frontend/src/pages/Fehm.jsx`)
- API client → Fehm routes: calls API (evidence: `README.md`)
- Fehm routes → AI orchestration: requests AI (evidence: `backend/routes/fehm_routes.py`)
- Fehm routes → Complexity analyzer: fallback analysis (evidence: `backend/routes/fehm_routes.py`)
- AI orchestration → AI cache: checks cache (evidence: `backend/ai_orchestrator.py`)
- AI orchestration → Gemini provider: tries primary (evidence: `backend/ai_orchestrator.py`)
- AI orchestration → Groq provider: falls back (evidence: `backend/ai_orchestrator.py`)
- Learner → Admin features: administers (evidence: `README.md`)
- Admin features → Application data: manages records (evidence: `backend/routes/admin_routes.py`)
- Learner → Health endpoint: health checks (evidence: `README.md`)
- Health endpoint → Application data: checks database (evidence: `backend/app.py`)
