# y23-hte-project-119/skillsense architecture

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

- Interactive diagram: https://gitdiagram.com/y23-hte-project-119/skillsense
- Repository: https://github.com/y23-hte-project-119/skillsense

## Overview

SkillSense is an adaptive learning and assessment platform. A learner browses skills and their topic hierarchy, takes a generated or existing assessment, receives scored results and subtopic gap analysis, then can use remediation and targeted retests to build mastery. The graph also includes skill administration, learning materials, and mastery tracking. Backend route wiring and assessment behavior are excerpted; other feature branches are retained from the README and file tree, with uncertain internal links left unasserted.

Main entry points: [`backend/app/main.py`](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/main.py) (FastAPI server), [`frontend/src/App.jsx`](https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/App.jsx) (React application), [`frontend/src/services/api.js`](https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/services/api.js) (API client), [`backend/app/routes/assessments.py`](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/assessments.py) (Assessment routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_frontend["React application<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_skill_ui["Skill browsing<br/>[SkillDetails.jsx]"]
  node_assessment_ui["Assessment taking<br/>[Assessment.jsx]"]
  node_results_ui["Results and gaps"]
  node_gap_ui["Gap analysis"]
  node_dashboard["Skill dashboard<br/>[Dashboard.jsx]"]
end

subgraph group_api["REST API"]
  node_server["FastAPI server<br/>[main.py]"]
  node_catalog_routes["Skill catalog routes<br/>[skills.py]"]
  node_topic_routes["Topic routes<br/>[topics.py]"]
  node_subtopic_routes["Subtopic routes<br/>[subtopics.py]"]
  node_material_routes["Learning material routes"]
  node_question_routes["Question routes<br/>[questions.py]"]
  node_assessment_routes["Assessment routes<br/>[assessments.py]"]
  node_diagnosis_routes["Diagnosis routes<br/>[gap_analysis.py]"]
  node_remediation_routes["Remediation routes<br/>[remediation.py]"]
  node_retest_routes["Retest and mastery routes<br/>[retest_mastery.py]"]
end

subgraph group_learning["Assessment services"]
  node_generator["AI question generation<br/>[ai_generator.py]"]
  node_diagnosis["Gap diagnosis<br/>[gap_diagnosis.py]"]
  node_explainer["Weakness explanations"]
  node_mastery["Mastery and retests<br/>[mastery_engine.py]"]
end

subgraph group_data["Learning data"]
  node_db_session["Database sessions<br/>[database.py]"]
  node_learning_models[("Learning domain models")]
  node_schemas["API schemas"]
end

node_learner(("Learner"))
node_mysql[("MySQL")]
node_gemini{{"Google Gemini API"}}

node_learner -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_skill_ui
node_frontend -->|"routes to"| node_assessment_ui
node_frontend -->|"routes to"| node_results_ui
node_frontend -->|"routes to"| node_gap_ui
node_frontend -->|"routes to"| node_dashboard
node_skill_ui -->|"requests data"| node_api_client
node_assessment_ui -->|"submits answers"| node_api_client
node_gap_ui -->|"requests analysis"| node_api_client
node_dashboard -->|"requests skills"| node_api_client
node_api_client -->|"calls REST API"| node_server
node_server -->|"registers"| node_catalog_routes
node_server -->|"registers"| node_topic_routes
node_server -->|"registers"| node_subtopic_routes
node_server -->|"registers"| node_material_routes
node_server -->|"registers"| node_question_routes
node_server -->|"registers"| node_assessment_routes
node_server -->|"registers"| node_diagnosis_routes
node_server -->|"registers"| node_remediation_routes
node_server -->|"registers"| node_retest_routes
node_assessment_routes -->|"gets sessions"| node_db_session
node_assessment_routes -->|"reads and writes"| node_learning_models
node_question_routes -->|"generates questions"| node_generator
node_generator -.->|"requests generation"| node_gemini
node_diagnosis_routes -.->|"evaluates gaps"| node_diagnosis
node_remediation_routes -.->|"requests explanations"| node_explainer
node_retest_routes -.->|"handles retests"| node_mastery
node_mastery -->|"evaluates gaps"| node_diagnosis
node_mastery -->|"generates retest questions"| node_generator
node_db_session -->|"creates tables"| node_learning_models
node_db_session -->|"connects to"| node_mysql
node_assessment_routes -->|"validates and responds"| node_schemas
node_diagnosis -->|"reads assessment data"| node_learning_models

click node_frontend "https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/services/api.js"
click node_skill_ui "https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/pages/SkillDetails.jsx"
click node_assessment_ui "https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/pages/Assessment.jsx"
click node_results_ui "https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/pages/AssessmentResults.jsx"
click node_gap_ui "https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/pages/SkillGapAnalysis.jsx"
click node_dashboard "https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/pages/Dashboard.jsx"
click node_server "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/main.py"
click node_catalog_routes "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/skills.py"
click node_topic_routes "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/topics.py"
click node_subtopic_routes "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/subtopics.py"
click node_material_routes "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/learning_materials.py"
click node_question_routes "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/questions.py"
click node_assessment_routes "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/assessments.py"
click node_diagnosis_routes "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/gap_analysis.py"
click node_remediation_routes "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/remediation.py"
click node_retest_routes "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/retest_mastery.py"
click node_generator "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/services/ai_generator.py"
click node_diagnosis "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/services/gap_diagnosis.py"
click node_explainer "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/services/weakness_explainer.py"
click node_mastery "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/services/mastery_engine.py"
click node_db_session "https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/db/database.py"
click node_learning_models "https://github.com/y23-hte-project-119/skillsense/tree/main/backend/app/db/models"
click node_schemas "https://github.com/y23-hte-project-119/skillsense/tree/main/backend/app/db/schemas"

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_frontend,node_api_client,node_skill_ui,node_assessment_ui,node_results_ui,node_gap_ui,node_dashboard toneBlue
class node_server,node_catalog_routes,node_topic_routes,node_subtopic_routes,node_material_routes,node_question_routes,node_assessment_routes,node_diagnosis_routes,node_remediation_routes,node_retest_routes,node_mysql toneAmber
class node_generator,node_diagnosis,node_explainer,node_mastery,node_gemini toneMint
class node_db_session,node_learning_models,node_schemas toneRose
class node_learner toneIndigo
```

## Components

### Learner experience

- [React application](https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Skill browsing](https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/pages/SkillDetails.jsx): `frontend/src/pages/SkillDetails.jsx`
- [Assessment taking](https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/pages/Assessment.jsx): `frontend/src/pages/Assessment.jsx`
- [Results and gaps](https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/pages/AssessmentResults.jsx): `frontend/src/pages/AssessmentResults.jsx`
- [Gap analysis](https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/pages/SkillGapAnalysis.jsx): `frontend/src/pages/SkillGapAnalysis.jsx`
- [Skill dashboard](https://github.com/y23-hte-project-119/skillsense/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`

### REST API

- [FastAPI server](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/main.py): `backend/app/main.py`
- [Skill catalog routes](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/skills.py): `backend/app/routes/skills.py`
- [Topic routes](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/topics.py): `backend/app/routes/topics.py`
- [Subtopic routes](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/subtopics.py): `backend/app/routes/subtopics.py`
- [Learning material routes](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/learning_materials.py): `backend/app/routes/learning_materials.py`
- [Question routes](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/questions.py): `backend/app/routes/questions.py`
- [Assessment routes](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/assessments.py): `backend/app/routes/assessments.py`
- [Diagnosis routes](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/gap_analysis.py): `backend/app/routes/gap_analysis.py`
- [Remediation routes](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/remediation.py): `backend/app/routes/remediation.py`
- [Retest and mastery routes](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/routes/retest_mastery.py): `backend/app/routes/retest_mastery.py`

### Assessment services

- [AI question generation](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/services/ai_generator.py): `backend/app/services/ai_generator.py`
- [Gap diagnosis](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/services/gap_diagnosis.py): `backend/app/services/gap_diagnosis.py`
- [Weakness explanations](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/services/weakness_explainer.py): `backend/app/services/weakness_explainer.py`
- [Mastery and retests](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/services/mastery_engine.py): `backend/app/services/mastery_engine.py`

### Learning data

- [Database sessions](https://github.com/y23-hte-project-119/skillsense/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Learning domain models](https://github.com/y23-hte-project-119/skillsense/tree/main/backend/app/db/models): `backend/app/db/models`
- [API schemas](https://github.com/y23-hte-project-119/skillsense/tree/main/backend/app/db/schemas): `backend/app/db/schemas`

### Other components

- **Learner**
- **MySQL**
- **Google Gemini API**

## Connections

- Learner → React application: uses
- React application → Skill browsing: routes to (evidence: `frontend/src/App.jsx`)
- React application → Assessment taking: routes to (evidence: `frontend/src/App.jsx`)
- React application → Results and gaps: routes to (evidence: `frontend/src/App.jsx`)
- React application → Gap analysis: routes to (evidence: `frontend/src/App.jsx`)
- React application → Skill dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Skill browsing → API client: requests data (evidence: `frontend/src/pages/SkillDetails.jsx`)
- Assessment taking → API client: submits answers (evidence: `frontend/src/pages/Assessment.jsx`)
- Gap analysis → API client: requests analysis (evidence: `frontend/src/pages/SkillGapAnalysis.jsx`)
- Skill dashboard → API client: requests skills (evidence: `frontend/src/pages/Dashboard.jsx`)
- API client → FastAPI server: calls REST API
- FastAPI server → Skill catalog routes: registers (evidence: `backend/app/main.py`)
- FastAPI server → Topic routes: registers (evidence: `backend/app/main.py`)
- FastAPI server → Subtopic routes: registers (evidence: `backend/app/main.py`)
- FastAPI server → Learning material routes: registers (evidence: `backend/app/main.py`)
- FastAPI server → Question routes: registers (evidence: `backend/app/main.py`)
- FastAPI server → Assessment routes: registers (evidence: `backend/app/main.py`)
- FastAPI server → Diagnosis routes: registers (evidence: `backend/app/main.py`)
- FastAPI server → Remediation routes: registers (evidence: `backend/app/main.py`)
- FastAPI server → Retest and mastery routes: registers (evidence: `backend/app/main.py`)
- Assessment routes → Database sessions: gets sessions (evidence: `backend/app/routes/assessments.py`)
- Assessment routes → Learning domain models: reads and writes (evidence: `backend/app/routes/assessments.py`)
- Question routes → AI question generation: generates questions (evidence: `backend/app/routes/questions.py`)
- AI question generation → Google Gemini API: requests generation
- Diagnosis routes → Gap diagnosis: evaluates gaps
- Remediation routes → Weakness explanations: requests explanations
- Retest and mastery routes → Mastery and retests: handles retests
- Mastery and retests → Gap diagnosis: evaluates gaps (evidence: `backend/app/services/mastery_engine.py`)
- Mastery and retests → AI question generation: generates retest questions (evidence: `backend/app/services/mastery_engine.py`)
- Database sessions → Learning domain models: creates tables (evidence: `backend/app/db/database.py`)
- Database sessions → MySQL: connects to
- Assessment routes → API schemas: validates and responds (evidence: `backend/app/routes/assessments.py`)
- Gap diagnosis → Learning domain models: reads assessment data (evidence: `backend/app/services/gap_diagnosis.py`)
