# jay4ignite/studyforge-ai architecture

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

- Interactive diagram: https://gitdiagram.com/jay4ignite/studyforge-ai
- Repository: https://github.com/jay4ignite/studyforge-ai

## Overview

StudyForge AI combines a React preparation workspace with a FastAPI backend. The main user journey is authenticated study and interview preparation: practice and coding tasks build performance history, AI interview sessions produce feedback and reports, and analytics/adaptive plans guide next steps. Separate capabilities support resume/ATS analysis, job discovery, and external coding-profile aggregation. The graph reflects documented features and visible wiring; several routes and integrations are represented at their exact directories because their implementation was not sampled.

Main entry points: [`backend/app/api/router.py`](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/router.py) (REST API), [`frontend/src/app/AppRoutes.tsx`](https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/app/AppRoutes.tsx) (App routes), [`backend/app/api/routes/interview.py`](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/interview.py) (Interview workflow), [`frontend/src/lib/axios.ts`](https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/lib/axios.ts) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_web["React application<br/>[main.tsx]"]
  node_routes["App routes<br/>[AppRoutes.tsx]"]
  node_authstate["Auth state<br/>[AuthProvider.tsx]"]
  node_practiceui["Practice loop<br/>[PracticeLoop.tsx]"]
  node_interviewui["Interview rooms"]
  node_codingui["Coding interview"]
  node_httpclient["HTTP client<br/>[axios.ts]"]
  node_wsclient["WebSocket client<br/>[WebSocketClient.ts]"]
end

subgraph group_api["API and identity"]
  node_api["REST API<br/>[router.py]"]
  node_wsroute["Interview socket route<br/>[interview_ws.py]"]
  node_auth["Authentication<br/>[deps.py]"]
end

subgraph group_learning["Learning and interviews"]
  node_interview["Interview workflow<br/>[interview.py]"]
  node_engine["AI interview engine"]
  node_telemetry["Voice and vision analysis"]
  node_practice["Practice and adaptive learning"]
  node_analytics["Progress analytics<br/>[analytics.py]"]
  node_roadmap["Learning roadmaps<br/>[roadmap.py]"]
  node_coding["Coding practice<br/>[leetcode.py]"]
end

subgraph group_career["Career intelligence"]
  node_resume["Resume parsing<br/>[resume_parser.py]"]
  node_ats["ATS analysis<br/>[ats_engine.py]"]
  node_storage["Resume object storage<br/>[r2_service.py]"]
  node_jobs["Job discovery<br/>[jsearch_service.py]"]
  node_profiles["Coding profile aggregation"]
end

subgraph group_platform["Runtime services"]
  node_ai["NVIDIA NIM"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_settings["Runtime configuration<br/>[config.py]"]
end

node_candidate(("Candidate"))

node_candidate -->|"uses"| node_web
node_web -->|"renders"| node_routes
node_routes -->|"provides auth"| node_authstate
node_routes -->|"routes to"| node_practiceui
node_routes -->|"routes to"| node_interviewui
node_routes -->|"routes to"| node_codingui
node_authstate -->|"fetches user"| node_httpclient
node_practiceui -->|"requests data"| node_httpclient
node_interviewui -->|"requests data"| node_httpclient
node_interviewui -->|"uses hook"| node_wsclient
node_wsclient -->|"connects to"| node_wsroute
node_httpclient -.->|"calls API"| node_api
node_api -->|"uses dependencies"| node_auth
node_api -->|"routes requests"| node_interview
node_api -->|"routes requests"| node_practice
node_api -->|"routes requests"| node_analytics
node_api -->|"routes requests"| node_roadmap
node_api -->|"routes requests"| node_coding
node_api -->|"routes requests"| node_ats
node_api -->|"routes requests"| node_jobs
node_api -->|"routes requests"| node_profiles
node_interview -->|"calls"| node_engine
node_interview -->|"uses parser"| node_resume
node_interview -->|"uses analysis"| node_telemetry
node_engine -->|"sends prompts"| node_ai
node_ats -->|"requests recommendations"| node_engine
node_ats -.->|"analyzes parsed resume"| node_resume
node_profiles -.->|"persists profiles"| node_database
node_jobs -->|"reads settings"| node_settings
node_api -.->|"uses sessions"| node_database
node_wsroute -.->|"streams interview"| node_engine
node_wsroute -.->|"authenticates socket"| node_auth
node_resume -.->|"stores uploads"| node_storage
node_practice -.->|"feeds progress"| node_analytics
node_analytics -.->|"informs plans"| node_roadmap

click node_web "https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/main.tsx"
click node_routes "https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/app/AppRoutes.tsx"
click node_authstate "https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/app/AuthProvider.tsx"
click node_practiceui "https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/features/practice/PracticeLoop.tsx"
click node_interviewui "https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/features/interviews/LiveInterviewRoom.tsx"
click node_codingui "https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/features/interviews/CodingInterviewRoom.tsx"
click node_httpclient "https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/lib/axios.ts"
click node_wsclient "https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/services/websocket/WebSocketClient.ts"
click node_api "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/router.py"
click node_wsroute "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/interview_ws.py"
click node_auth "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/deps.py"
click node_interview "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/interview.py"
click node_engine "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/ai_interview_engine.py"
click node_telemetry "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/voice_vision_analyzer.py"
click node_practice "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/practice_service.py"
click node_analytics "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/analytics.py"
click node_roadmap "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/roadmap.py"
click node_coding "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/leetcode.py"
click node_resume "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/resume_parser.py"
click node_ats "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/ats_engine.py"
click node_storage "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/r2_service.py"
click node_jobs "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/jobs/jsearch_service.py"
click node_profiles "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/coding_profile/aggregator_service.py"
click node_ai "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/ai_interview_engine.py"
click node_database "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/db/database.py"
click node_settings "https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/core/config.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_routes,node_authstate,node_practiceui,node_interviewui,node_codingui,node_httpclient,node_wsclient toneBlue
class node_api,node_wsroute,node_auth toneAmber
class node_interview,node_engine,node_telemetry,node_practice,node_analytics,node_roadmap,node_coding toneMint
class node_resume,node_ats,node_storage,node_jobs,node_profiles toneRose
class node_ai,node_database,node_settings,node_candidate toneIndigo
```

## Components

### Web application

- [React application](https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [App routes](https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/app/AppRoutes.tsx): `frontend/src/app/AppRoutes.tsx`
- [Auth state](https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/app/AuthProvider.tsx): `frontend/src/app/AuthProvider.tsx`
- [Practice loop](https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/features/practice/PracticeLoop.tsx): `frontend/src/features/practice/PracticeLoop.tsx`
- [Interview rooms](https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/features/interviews/LiveInterviewRoom.tsx): `frontend/src/features/interviews/LiveInterviewRoom.tsx`
- [Coding interview](https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/features/interviews/CodingInterviewRoom.tsx): `frontend/src/features/interviews/CodingInterviewRoom.tsx`
- [HTTP client](https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/lib/axios.ts): `frontend/src/lib/axios.ts`
- [WebSocket client](https://github.com/jay4ignite/studyforge-ai/blob/main/frontend/src/services/websocket/WebSocketClient.ts): `frontend/src/services/websocket/WebSocketClient.ts`

### API and identity

- [REST API](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Interview socket route](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/interview_ws.py): `backend/app/api/routes/interview_ws.py`
- [Authentication](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`

### Learning and interviews

- [Interview workflow](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/interview.py): `backend/app/api/routes/interview.py`
- [AI interview engine](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/ai_interview_engine.py): `backend/app/services/ai_interview_engine.py`
- [Voice and vision analysis](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/voice_vision_analyzer.py): `backend/app/services/voice_vision_analyzer.py`
- [Practice and adaptive learning](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/practice_service.py): `backend/app/services/practice_service.py`
- [Progress analytics](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/analytics.py): `backend/app/api/routes/analytics.py`
- [Learning roadmaps](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/roadmap.py): `backend/app/api/routes/roadmap.py`
- [Coding practice](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/api/routes/leetcode.py): `backend/app/api/routes/leetcode.py`

### Career intelligence

- [Resume parsing](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/resume_parser.py): `backend/app/services/resume_parser.py`
- [ATS analysis](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/ats_engine.py): `backend/app/services/ats_engine.py`
- [Resume object storage](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/r2_service.py): `backend/app/services/r2_service.py`
- [Job discovery](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/jobs/jsearch_service.py): `backend/app/services/jobs/jsearch_service.py`
- [Coding profile aggregation](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/coding_profile/aggregator_service.py): `backend/app/services/coding_profile/aggregator_service.py`

### Runtime services

- [NVIDIA NIM](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/services/ai_interview_engine.py): `backend/app/services/ai_interview_engine.py`
- [PostgreSQL](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Runtime configuration](https://github.com/jay4ignite/studyforge-ai/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Other components

- **Candidate**

## Connections

- Candidate → React application: uses (evidence: `frontend/src/main.tsx`)
- React application → App routes: renders (evidence: `frontend/src/main.tsx`)
- App routes → Auth state: provides auth (evidence: `frontend/src/app/AppRoutes.tsx`)
- App routes → Practice loop: routes to (evidence: `frontend/src/app/AppRoutes.tsx`)
- App routes → Interview rooms: routes to (evidence: `frontend/src/app/AppRoutes.tsx`)
- App routes → Coding interview: routes to (evidence: `frontend/src/app/AppRoutes.tsx`)
- Auth state → HTTP client: fetches user (evidence: `frontend/src/app/AuthProvider.tsx`)
- Practice loop → HTTP client: requests data (evidence: `frontend/src/features/practice/PracticeLoop.tsx`)
- Interview rooms → HTTP client: requests data (evidence: `frontend/src/features/interviews/LiveInterviewRoom.tsx`)
- Interview rooms → WebSocket client: uses hook (evidence: `frontend/src/features/interviews/LiveInterviewRoom.tsx`)
- WebSocket client → Interview socket route: connects to
- HTTP client → REST API: calls API
- REST API → Authentication: uses dependencies
- REST API → Interview workflow: routes requests (evidence: `backend/app/api/router.py`)
- REST API → Practice and adaptive learning: routes requests (evidence: `backend/app/api/router.py`)
- REST API → Progress analytics: routes requests (evidence: `backend/app/api/router.py`)
- REST API → Learning roadmaps: routes requests (evidence: `backend/app/api/router.py`)
- REST API → Coding practice: routes requests (evidence: `backend/app/api/router.py`)
- REST API → ATS analysis: routes requests (evidence: `backend/app/api/router.py`)
- REST API → Job discovery: routes requests (evidence: `backend/app/api/router.py`)
- REST API → Coding profile aggregation: routes requests (evidence: `backend/app/api/router.py`)
- Interview workflow → AI interview engine: calls (evidence: `backend/app/api/routes/interview.py`)
- Interview workflow → Resume parsing: uses parser (evidence: `backend/app/api/routes/interview.py`)
- Interview workflow → Voice and vision analysis: uses analysis (evidence: `backend/app/api/routes/interview.py`)
- AI interview engine → NVIDIA NIM: sends prompts (evidence: `backend/app/services/ai_interview_engine.py`)
- ATS analysis → AI interview engine: requests recommendations (evidence: `backend/app/services/ats_engine.py`)
- ATS analysis → Resume parsing: analyzes parsed resume
- Coding profile aggregation → PostgreSQL: persists profiles
- Job discovery → Runtime configuration: reads settings (evidence: `backend/app/services/jobs/jsearch_service.py`)
- REST API → PostgreSQL: uses sessions
- Interview socket route → AI interview engine: streams interview
- Interview socket route → Authentication: authenticates socket
- Resume parsing → Resume object storage: stores uploads
- Practice and adaptive learning → Progress analytics: feeds progress
- Progress analytics → Learning roadmaps: informs plans