# dhanush-10-1/pathforge-hackcodeio architecture

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

- Interactive diagram: https://gitdiagram.com/dhanush-10-1/pathforge-hackcodeio
- Repository: https://github.com/dhanush-10-1/pathforge-hackcodeio

## Overview

PathForge guides a candidate from role selection and resume parsing through diagnostic skill verification to an explainable, personalized learning pathway. The frontend calls the backend, which coordinates persistence and the ML service; the documented external quiz portal can return graded results to the backend. The README documents the major ML capabilities, but router and model excerpts are incomplete, so some internal wiring is not shown.

Main entry points: [`backend/app/main.py`](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/main.py) (Backend API), [`ml/app/main.py`](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/main.py) (ML API), [`backend/app/routers/quiz.py`](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/routers/quiz.py) (Quiz sessions), [`backend/app/services/ml_client.py`](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/services/ml_client.py) (ML HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_candidate_ui["Candidate experience"]
  node_landing["Landing<br/>[page.tsx]"]
  node_onboarding["Role and resume<br/>[page.tsx]"]
  node_quiz_ui["Quiz interface<br/>[page.tsx]"]
  node_pathway_ui["Pathway view<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_backend["Backend orchestration"]
  node_backend_api["Backend API<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_resume["Resume processing<br/>[resume.py]"]
  node_quiz["Quiz sessions<br/>[quiz.py]"]
  node_pathway["Pathway orchestration<br/>[pathway.py]"]
  node_ml_client["ML HTTP client<br/>[ml_client.py]"]
end

subgraph group_ml["ML capabilities"]
  node_ml_api["ML API<br/>[main.py]"]
  node_skills["Skill extraction<br/>[skills.py]"]
  node_skill_model["Skill extractor<br/>[skill_extractor.py]"]
  node_roles["Role mapping<br/>[roles.py]"]
  node_role_model["Role mapper<br/>[role_mapper.py]"]
  node_ml_quiz["Quiz generation and grading<br/>[quiz.py]"]
  node_quiz_model["Quiz generator<br/>[quiz_generator.py]"]
  node_ml_pathway["Pathway generation<br/>[pathway.py]"]
  node_adaptive["Adaptive engine<br/>[adaptive_engine.py]"]
end

subgraph group_state["Persistent state"]
  node_db_session["Database sessions<br/>[database.py]"]
  node_db_models["User and learning records<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
end

node_candidate(("Candidate"))
node_external_quiz["External quiz portal"]

node_candidate -->|"visits"| node_landing
node_landing -->|"starts onboarding"| node_onboarding
node_candidate -->|"selects role, submits resume"| node_onboarding
node_onboarding -->|"requests"| node_api_client
node_api_client -->|"HTTP requests"| node_backend_api
node_backend_api -->|"dispatches auth"| node_auth
node_backend_api -->|"dispatches resume"| node_resume
node_backend_api -->|"dispatches quiz"| node_quiz
node_backend_api -->|"dispatches pathway"| node_pathway
node_resume -->|"requests extraction"| node_ml_client
node_ml_client -->|"calls ML endpoints"| node_ml_api
node_ml_api -->|"dispatches skills"| node_skills
node_ml_api -->|"dispatches roles"| node_roles
node_ml_api -->|"dispatches quiz"| node_ml_quiz
node_ml_api -->|"dispatches pathway"| node_ml_pathway
node_skills -->|"extracts skills"| node_skill_model
node_roles -->|"maps role"| node_role_model
node_quiz -->|"requests quiz and grading"| node_ml_client
node_ml_quiz -->|"generates and grades"| node_quiz_model
node_quiz -.->|"provides session"| node_external_quiz
node_external_quiz -.->|"posts results"| node_quiz
node_candidate -->|"takes quiz"| node_quiz_ui
node_quiz_ui -->|"loads session"| node_api_client
node_quiz_ui -->|"starts or submits quiz"| node_backend_api
node_candidate -->|"views pathway"| node_pathway_ui
node_pathway_ui -->|"requests pathway"| node_backend_api
node_pathway -->|"requests pathway generation"| node_ml_client
node_ml_pathway -->|"generates adaptive path"| node_adaptive
node_auth -->|"reads and writes users"| node_db_session
node_db_session -->|"uses records"| node_db_models
node_db_session -->|"reads and writes"| node_postgres

click node_landing "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/frontend/app/page.tsx"
click node_onboarding "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/frontend/app/onboarding/page.tsx"
click node_quiz_ui "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/frontend/app/quiz/page.tsx"
click node_pathway_ui "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/frontend/app/pathway/page.tsx"
click node_api_client "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/frontend/lib/api.ts"
click node_backend_api "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/main.py"
click node_auth "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/routers/auth.py"
click node_resume "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/routers/resume.py"
click node_quiz "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/routers/quiz.py"
click node_pathway "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/routers/pathway.py"
click node_ml_client "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/services/ml_client.py"
click node_db_session "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/db/database.py"
click node_db_models "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/db/models.py"
click node_ml_api "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/main.py"
click node_skills "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/routers/skills.py"
click node_skill_model "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/models/skill_extractor.py"
click node_roles "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/routers/roles.py"
click node_role_model "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/models/role_mapper.py"
click node_ml_quiz "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/routers/quiz.py"
click node_quiz_model "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/models/quiz_generator.py"
click node_ml_pathway "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/routers/pathway.py"
click node_adaptive "https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/models/adaptive_engine.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_landing,node_onboarding,node_quiz_ui,node_pathway_ui,node_api_client toneBlue
class node_backend_api,node_auth,node_resume,node_quiz,node_pathway,node_ml_client toneAmber
class node_ml_api,node_skills,node_skill_model,node_roles,node_role_model,node_ml_quiz,node_quiz_model,node_ml_pathway,node_adaptive toneMint
class node_db_session,node_db_models,node_postgres toneRose
class node_candidate,node_external_quiz toneIndigo
```

## Components

### Candidate experience

- [Landing](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Role and resume](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/frontend/app/onboarding/page.tsx): `frontend/app/onboarding/page.tsx`
- [Quiz interface](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/frontend/app/quiz/page.tsx): `frontend/app/quiz/page.tsx`
- [Pathway view](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/frontend/app/pathway/page.tsx): `frontend/app/pathway/page.tsx`
- [API client](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Backend orchestration

- [Backend API](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Resume processing](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/routers/resume.py): `backend/app/routers/resume.py`
- [Quiz sessions](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/routers/quiz.py): `backend/app/routers/quiz.py`
- [Pathway orchestration](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/routers/pathway.py): `backend/app/routers/pathway.py`
- [ML HTTP client](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/services/ml_client.py): `backend/app/services/ml_client.py`

### ML capabilities

- [ML API](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/main.py): `ml/app/main.py`
- [Skill extraction](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/routers/skills.py): `ml/app/routers/skills.py`
- [Skill extractor](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/models/skill_extractor.py): `ml/app/models/skill_extractor.py`
- [Role mapping](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/routers/roles.py): `ml/app/routers/roles.py`
- [Role mapper](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/models/role_mapper.py): `ml/app/models/role_mapper.py`
- [Quiz generation and grading](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/routers/quiz.py): `ml/app/routers/quiz.py`
- [Quiz generator](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/models/quiz_generator.py): `ml/app/models/quiz_generator.py`
- [Pathway generation](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/routers/pathway.py): `ml/app/routers/pathway.py`
- [Adaptive engine](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/ml/app/models/adaptive_engine.py): `ml/app/models/adaptive_engine.py`

### Persistent state

- [Database sessions](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [User and learning records](https://github.com/dhanush-10-1/pathforge-hackcodeio/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- **PostgreSQL**

### Other components

- **Candidate**
- **External quiz portal**

## Connections

- Candidate → Landing: visits
- Landing → Role and resume: starts onboarding
- Candidate → Role and resume: selects role, submits resume
- Role and resume → API client: requests
- API client → Backend API: HTTP requests
- Backend API → Authentication: dispatches auth
- Backend API → Resume processing: dispatches resume
- Backend API → Quiz sessions: dispatches quiz
- Backend API → Pathway orchestration: dispatches pathway
- Resume processing → ML HTTP client: requests extraction
- ML HTTP client → ML API: calls ML endpoints
- ML API → Skill extraction: dispatches skills
- ML API → Role mapping: dispatches roles
- ML API → Quiz generation and grading: dispatches quiz
- ML API → Pathway generation: dispatches pathway
- Skill extraction → Skill extractor: extracts skills
- Role mapping → Role mapper: maps role
- Quiz sessions → ML HTTP client: requests quiz and grading
- Quiz generation and grading → Quiz generator: generates and grades
- Quiz sessions → External quiz portal: provides session
- External quiz portal → Quiz sessions: posts results
- Candidate → Quiz interface: takes quiz
- Quiz interface → API client: loads session
- Quiz interface → Backend API: starts or submits quiz
- Candidate → Pathway view: views pathway
- Pathway view → Backend API: requests pathway
- Pathway orchestration → ML HTTP client: requests pathway generation
- Pathway generation → Adaptive engine: generates adaptive path
- Authentication → Database sessions: reads and writes users
- Database sessions → User and learning records: uses records
- Database sessions → PostgreSQL: reads and writes