# dhanushaadhikesh12-spec/career_forge_ai architecture

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

- Interactive diagram: https://gitdiagram.com/dhanushaadhikesh12-spec/career_forge_ai
- Repository: https://github.com/dhanushaadhikesh12-spec/career_forge_ai

## Overview

CareerForge AI is a placement-readiness platform for students and trainers. Students register, learn and practice aptitude topics, take adaptive or proctored tests, and submit code; trainers manage cohorts, review analytics, and ask a grounded AI assistant about authorized student data. The backend combines REST routes, adaptive aptitude, coding evaluation, ML analytics, and AI services over PostgreSQL. README documents capabilities whose route-level wiring was not sampled; those links are shown as documented or left unverified rather than inferred from module names.

Main entry points: [`backend/app/db/database.py`](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/db/database.py) (PostgreSQL data), [`frontend/src/App.tsx`](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/App.tsx) (Role-based app), [`backend/app/ml/feature_engineering.py`](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/ml/feature_engineering.py) (Readiness features), [`backend/app/services/adaptive_engine.py`](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/adaptive_engine.py) (Adaptive aptitude engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Student and trainer experience"]
  node_webapp["Role-based app<br/>[App.tsx]"]
  node_authui["Sign-in UI<br/>[AuthContext.tsx]"]
  node_studentui["Student learning UI"]
  node_trainerui["Trainer workspace"]
  node_apiclient["REST client<br/>[api.ts]"]
end

subgraph group_api["API and learning workflows"]
  node_application["FastAPI application<br/>[main.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_studentroutes["Student learning routes<br/>[student.py]"]
  node_codingroutes["Coding assessment routes<br/>[coding.py]"]
  node_proctorroutes["Proctoring routes<br/>[proctoring.py]"]
  node_trainerroutes["Trainer routes<br/>[trainer.py]"]
  node_adaptive["Adaptive aptitude engine<br/>[adaptive_engine.py]"]
  node_codingjudge["Code evaluation client<br/>[judge0.py]"]
  node_questionbank["Question and curriculum bank<br/>[curriculum.py]"]
end

subgraph group_intelligence["Analytics and AI"]
  node_featureengineering["Readiness features"]
  node_readiness["Readiness prediction<br/>[readiness_model.py]"]
  node_mlanalytics["Cohort and integrity ML"]
  node_assistant["Trainer AI assistant<br/>[assistant.py]"]
  node_aitools["Grounded data tools<br/>[tools.py]"]
  node_aiprovider["Ollama provider<br/>[provider.py]"]
end

subgraph group_persistence["Platform data"]
  node_database[("PostgreSQL data<br/>[database.py]")]
  node_domainmodels["Learning and account models<br/>[content.py]"]
  node_codingmodels["Coding submission models<br/>[coding.py]"]
  node_usermodels["User and cohort models<br/>[user.py]"]
end

node_students(("Students"))
node_trainers(("Trainers"))
node_judge0["Judge0 sandbox"]
node_ollama["Ollama Gemma"]

node_students -->|"use"| node_webapp
node_trainers -->|"use"| node_webapp
node_webapp -->|"provides routes"| node_authui
node_webapp -->|"routes students"| node_studentui
node_webapp -->|"routes trainers"| node_trainerui
node_authui -.->|"requests"| node_apiclient
node_studentui -.->|"requests"| node_apiclient
node_trainerui -.->|"requests"| node_apiclient
node_apiclient -->|"REST requests"| node_application
node_application -->|"initializes"| node_database
node_application -->|"registers routes"| node_authroutes
node_authroutes -->|"reads and writes"| node_database
node_studentroutes -.->|"uses"| node_adaptive
node_adaptive -->|"reads progress and questions"| node_domainmodels
node_adaptive -->|"updates progress"| node_usermodels
node_adaptive -.->|"selects from"| node_questionbank
node_codingroutes -->|"evaluates submissions"| node_codingjudge
node_codingjudge -->|"submits code"| node_judge0
node_codingroutes -.->|"stores submissions"| node_codingmodels
node_proctorroutes -.->|"records events"| node_database
node_trainerroutes -.->|"requests analytics"| node_featureengineering
node_featureengineering -->|"extracts profile data"| node_usermodels
node_featureengineering -->|"extracts topic progress"| node_domainmodels
node_featureengineering -->|"extracts coding data"| node_codingmodels
node_readiness -->|"uses features"| node_featureengineering
node_trainerroutes -.->|"serves analytics"| node_mlanalytics
node_trainerroutes -.->|"serves readiness"| node_readiness
node_assistant -->|"grounds answers"| node_aitools
node_assistant -->|"generates responses"| node_aiprovider
node_aiprovider -->|"calls local model"| node_ollama
node_aitools -->|"queries cohort data"| node_usermodels
node_aitools -->|"queries predictions"| node_readiness
node_trainerui -.->|"chat requests"| node_assistant
node_database -->|"maps tables"| node_domainmodels
node_database -->|"maps tables"| node_codingmodels
node_database -->|"maps tables"| node_usermodels

click node_webapp "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_studentui "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/pages/student/TestSessionPage.tsx"
click node_trainerui "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/pages/trainer/TrainerAIAssistantPage.tsx"
click node_apiclient "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/services/api.ts"
click node_application "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/main.py"
click node_authroutes "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/api/routes/auth.py"
click node_studentroutes "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/api/routes/student.py"
click node_codingroutes "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/api/routes/coding.py"
click node_proctorroutes "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/api/routes/proctoring.py"
click node_trainerroutes "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/api/routes/trainer.py"
click node_adaptive "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/adaptive_engine.py"
click node_codingjudge "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/judge0.py"
click node_questionbank "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/data/curriculum.py"
click node_featureengineering "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/ml/feature_engineering.py"
click node_readiness "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/ml/readiness_model.py"
click node_mlanalytics "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/tree/main/backend/app/ml"
click node_assistant "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/ai/assistant.py"
click node_aitools "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/ai/tools.py"
click node_aiprovider "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/ai/provider.py"
click node_database "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/db/database.py"
click node_domainmodels "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/models/content.py"
click node_codingmodels "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/models/coding.py"
click node_usermodels "https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/models/user.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_authui,node_studentui,node_trainerui,node_apiclient toneBlue
class node_application,node_authroutes,node_studentroutes,node_codingroutes,node_proctorroutes,node_trainerroutes,node_adaptive,node_codingjudge,node_questionbank toneAmber
class node_featureengineering,node_readiness,node_mlanalytics,node_assistant,node_aitools,node_aiprovider toneMint
class node_database,node_domainmodels,node_codingmodels,node_usermodels toneRose
class node_students,node_trainers,node_judge0,node_ollama toneIndigo
```

## Components

### Student and trainer experience

- [Role-based app](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in UI](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`
- [Student learning UI](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/pages/student/TestSessionPage.tsx): `frontend/src/pages/student/TestSessionPage.tsx`
- [Trainer workspace](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/pages/trainer/TrainerAIAssistantPage.tsx): `frontend/src/pages/trainer/TrainerAIAssistantPage.tsx`
- [REST client](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API and learning workflows

- [FastAPI application](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/api/routes/auth.py): `backend/app/api/routes/auth.py`
- [Student learning routes](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/api/routes/student.py): `backend/app/api/routes/student.py`
- [Coding assessment routes](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/api/routes/coding.py): `backend/app/api/routes/coding.py`
- [Proctoring routes](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/api/routes/proctoring.py): `backend/app/api/routes/proctoring.py`
- [Trainer routes](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/api/routes/trainer.py): `backend/app/api/routes/trainer.py`
- [Adaptive aptitude engine](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/adaptive_engine.py): `backend/app/services/adaptive_engine.py`
- [Code evaluation client](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/judge0.py): `backend/app/services/judge0.py`
- [Question and curriculum bank](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/data/curriculum.py): `backend/app/data/curriculum.py`

### Analytics and AI

- [Readiness features](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/ml/feature_engineering.py): `backend/app/ml/feature_engineering.py`
- [Readiness prediction](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/ml/readiness_model.py): `backend/app/ml/readiness_model.py`
- [Cohort and integrity ML](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/tree/main/backend/app/ml): `backend/app/ml`
- [Trainer AI assistant](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/ai/assistant.py): `backend/app/services/ai/assistant.py`
- [Grounded data tools](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/ai/tools.py): `backend/app/services/ai/tools.py`
- [Ollama provider](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/services/ai/provider.py): `backend/app/services/ai/provider.py`

### Platform data

- [PostgreSQL data](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Learning and account models](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/models/content.py): `backend/app/models/content.py`
- [Coding submission models](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/models/coding.py): `backend/app/models/coding.py`
- [User and cohort models](https://github.com/dhanushaadhikesh12-spec/career_forge_ai/blob/main/backend/app/models/user.py): `backend/app/models/user.py`

### Other components

- **Students**
- **Trainers**
- **Judge0 sandbox**
- **Ollama Gemma**

## Connections

- Students → Role-based app: use
- Trainers → Role-based app: use
- Role-based app → Sign-in UI: provides routes (evidence: `frontend/src/App.tsx`)
- Role-based app → Student learning UI: routes students (evidence: `frontend/src/App.tsx`)
- Role-based app → Trainer workspace: routes trainers (evidence: `frontend/src/App.tsx`)
- Sign-in UI → REST client: requests
- Student learning UI → REST client: requests
- Trainer workspace → REST client: requests
- REST client → FastAPI application: REST requests
- FastAPI application → PostgreSQL data: initializes (evidence: `backend/app/main.py`)
- FastAPI application → Authentication routes: registers routes
- Authentication routes → PostgreSQL data: reads and writes (evidence: `backend/app/api/routes/auth.py`)
- Student learning routes → Adaptive aptitude engine: uses
- Adaptive aptitude engine → Learning and account models: reads progress and questions (evidence: `backend/app/services/adaptive_engine.py`)
- Adaptive aptitude engine → User and cohort models: updates progress (evidence: `backend/app/services/adaptive_engine.py`)
- Adaptive aptitude engine → Question and curriculum bank: selects from
- Coding assessment routes → Code evaluation client: evaluates submissions
- Code evaluation client → Judge0 sandbox: submits code
- Coding assessment routes → Coding submission models: stores submissions
- Proctoring routes → PostgreSQL data: records events (evidence: `backend/app/api/routes/proctoring.py`)
- Trainer routes → Readiness features: requests analytics
- Readiness features → User and cohort models: extracts profile data (evidence: `backend/app/ml/feature_engineering.py`)
- Readiness features → Learning and account models: extracts topic progress (evidence: `backend/app/ml/feature_engineering.py`)
- Readiness features → Coding submission models: extracts coding data (evidence: `backend/app/ml/feature_engineering.py`)
- Readiness prediction → Readiness features: uses features (evidence: `backend/app/ml/readiness_model.py`)
- Trainer routes → Cohort and integrity ML: serves analytics
- Trainer routes → Readiness prediction: serves readiness
- Trainer AI assistant → Grounded data tools: grounds answers
- Trainer AI assistant → Ollama provider: generates responses
- Ollama provider → Ollama Gemma: calls local model
- Grounded data tools → User and cohort models: queries cohort data (evidence: `backend/app/services/ai/tools.py`)
- Grounded data tools → Readiness prediction: queries predictions (evidence: `backend/app/services/ai/tools.py`)
- Trainer workspace → Trainer AI assistant: chat requests
- PostgreSQL data → Learning and account models: maps tables (evidence: `backend/app/db/database.py`)
- PostgreSQL data → Coding submission models: maps tables (evidence: `backend/app/db/database.py`)
- PostgreSQL data → User and cohort models: maps tables (evidence: `backend/app/db/database.py`)
