# subratad27/adaptiq architecture

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

- Interactive diagram: https://gitdiagram.com/subratad27/adaptiq
- Repository: https://github.com/subratad27/adaptiq

## Overview

AdaptIQ is a student learning platform with teacher question-bank and quiz tools, adaptive or random practice, BKT mastery tracking, and teacher/research analytics. Students sign in, receive concept-targeted questions, submit answers, and review mastery and history; teachers manage learning content and inspect class or study results. The graph separates the React experience, API routing, learning logic, analytics, and persistence. Some endpoint-to-page wiring is not visible in the excerpts, so those links are omitted rather than inferred.

Main entry points: [`backend/app/main.py`](https://github.com/subratad27/adaptiq/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/models.py`](https://github.com/subratad27/adaptiq/blob/main/backend/app/models.py) (Domain models), [`backend/app/database.py`](https://github.com/subratad27/adaptiq/blob/main/backend/app/database.py) (SQLite database), [`frontend/src/main.jsx`](https://github.com/subratad27/adaptiq/blob/main/frontend/src/main.jsx) (App routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_web_router["App routes<br/>[main.jsx]"]
  node_login["Login<br/>[Login.jsx]"]
  node_student_quiz["Practice quiz<br/>[StudentQuiz.jsx]"]
  node_mastery_view["Mastery map<br/>[MasteryMap.jsx]"]
  node_history_view["Quiz history<br/>[QuizHistory.jsx]"]
  node_teacher_view["Teacher dashboard"]
  node_research_view["Research page<br/>[Research.jsx]"]
  node_api_client["API client<br/>[client.js]"]
end

subgraph group_api["API and access"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth_routes["Authentication<br/>[auth_router.py]"]
  node_question_routes["Question bank"]
  node_quiz_routes["Quiz publishing<br/>[quizzes_router.py]"]
  node_auth_logic["Token and passwords<br/>[auth.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_learning["Learning engine"]
  node_practice_routes["Practice endpoints<br/>[quiz_router.py]"]
  node_bkt["BKT engine<br/>[bkt.py]"]
  node_concept_routes["Concepts<br/>[concepts_router.py]"]
end

subgraph group_analytics["Analytics and research"]
  node_analytics_routes["Class analytics"]
  node_simulation["Learner simulation<br/>[simulation.py]"]
end

subgraph group_storage["Persistence"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("SQLite database<br/>[database.py]")]
  node_seed["Startup seed<br/>[seed.py]"]
end

node_student(("Student"))
node_teacher(("Teacher"))

node_student -->|"signs in"| node_login
node_teacher -->|"signs in"| node_login
node_web_router -->|"routes to"| node_login
node_web_router -->|"routes to"| node_student_quiz
node_web_router -->|"routes to"| node_mastery_view
node_web_router -->|"routes to"| node_history_view
node_web_router -->|"routes to"| node_teacher_view
node_web_router -->|"routes to"| node_research_view
node_login -->|"calls"| node_api_client
node_student_quiz -->|"calls"| node_api_client
node_mastery_view -->|"calls"| node_api_client
node_history_view -->|"calls"| node_api_client
node_teacher_view -->|"calls"| node_api_client
node_research_view -->|"calls"| node_api_client
node_api_app -->|"registers"| node_auth_routes
node_api_app -->|"registers"| node_question_routes
node_api_app -->|"registers"| node_quiz_routes
node_api_app -->|"registers"| node_practice_routes
node_api_app -->|"registers"| node_analytics_routes
node_api_app -->|"registers"| node_concept_routes
node_api_app -->|"runs at startup"| node_seed
node_api_app -->|"creates tables"| node_database
node_auth_routes -->|"uses"| node_auth_logic
node_auth_routes -->|"reads and writes"| node_database
node_auth_routes -->|"uses"| node_models
node_auth_routes -->|"validates with"| node_schemas
node_question_routes -->|"reads and writes"| node_database
node_question_routes -->|"uses"| node_models
node_question_routes -->|"validates with"| node_schemas
node_quiz_routes -->|"reads and writes"| node_database
node_quiz_routes -->|"uses"| node_models
node_quiz_routes -->|"validates with"| node_schemas
node_practice_routes -->|"reads and writes"| node_database
node_practice_routes -->|"uses"| node_models
node_practice_routes -->|"validates with"| node_schemas
node_practice_routes -->|"selects and updates"| node_bkt
node_concept_routes -->|"reads"| node_database
node_concept_routes -->|"uses"| node_models
node_analytics_routes -->|"reads"| node_database
node_analytics_routes -->|"uses"| node_models
node_analytics_routes -->|"runs"| node_simulation
node_simulation -->|"reads and writes"| node_database
node_simulation -->|"uses"| node_models
node_simulation -->|"uses"| node_bkt
node_seed -->|"populates"| node_models
node_models -->|"defines mapped tables"| node_database
node_student -->|"practices"| node_student_quiz
node_student -->|"reviews mastery"| node_mastery_view

click node_web_router "https://github.com/subratad27/adaptiq/blob/main/frontend/src/main.jsx"
click node_login "https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/Login.jsx"
click node_student_quiz "https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/StudentQuiz.jsx"
click node_mastery_view "https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/MasteryMap.jsx"
click node_history_view "https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/QuizHistory.jsx"
click node_teacher_view "https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/TeacherDashboard.jsx"
click node_research_view "https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/Research.jsx"
click node_api_client "https://github.com/subratad27/adaptiq/blob/main/frontend/src/api/client.js"
click node_api_app "https://github.com/subratad27/adaptiq/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/auth_router.py"
click node_question_routes "https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/questions_router.py"
click node_quiz_routes "https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/quizzes_router.py"
click node_practice_routes "https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/quiz_router.py"
click node_bkt "https://github.com/subratad27/adaptiq/blob/main/backend/app/bkt.py"
click node_concept_routes "https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/concepts_router.py"
click node_analytics_routes "https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/analytics_router.py"
click node_simulation "https://github.com/subratad27/adaptiq/blob/main/backend/app/simulation.py"
click node_models "https://github.com/subratad27/adaptiq/blob/main/backend/app/models.py"
click node_database "https://github.com/subratad27/adaptiq/blob/main/backend/app/database.py"
click node_seed "https://github.com/subratad27/adaptiq/blob/main/backend/app/seed.py"
click node_auth_logic "https://github.com/subratad27/adaptiq/blob/main/backend/app/auth.py"
click node_schemas "https://github.com/subratad27/adaptiq/blob/main/backend/app/schemas.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_router,node_login,node_student_quiz,node_mastery_view,node_history_view,node_teacher_view,node_research_view,node_api_client toneBlue
class node_api_app,node_auth_routes,node_question_routes,node_quiz_routes,node_auth_logic,node_schemas toneAmber
class node_practice_routes,node_bkt,node_concept_routes toneMint
class node_analytics_routes,node_simulation toneRose
class node_models,node_database,node_seed,node_student,node_teacher toneIndigo
```

## Components

### Web experience

- [App routes](https://github.com/subratad27/adaptiq/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Login](https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Practice quiz](https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/StudentQuiz.jsx): `frontend/src/pages/StudentQuiz.jsx`
- [Mastery map](https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/MasteryMap.jsx): `frontend/src/pages/MasteryMap.jsx`
- [Quiz history](https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/QuizHistory.jsx): `frontend/src/pages/QuizHistory.jsx`
- [Teacher dashboard](https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/TeacherDashboard.jsx): `frontend/src/pages/TeacherDashboard.jsx`
- [Research page](https://github.com/subratad27/adaptiq/blob/main/frontend/src/pages/Research.jsx): `frontend/src/pages/Research.jsx`
- [API client](https://github.com/subratad27/adaptiq/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### API and access

- [FastAPI app](https://github.com/subratad27/adaptiq/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/auth_router.py): `backend/app/routers/auth_router.py`
- [Question bank](https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/questions_router.py): `backend/app/routers/questions_router.py`
- [Quiz publishing](https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/quizzes_router.py): `backend/app/routers/quizzes_router.py`
- [Token and passwords](https://github.com/subratad27/adaptiq/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [API schemas](https://github.com/subratad27/adaptiq/blob/main/backend/app/schemas.py): `backend/app/schemas.py`

### Learning engine

- [Practice endpoints](https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/quiz_router.py): `backend/app/routers/quiz_router.py`
- [BKT engine](https://github.com/subratad27/adaptiq/blob/main/backend/app/bkt.py): `backend/app/bkt.py`
- [Concepts](https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/concepts_router.py): `backend/app/routers/concepts_router.py`

### Analytics and research

- [Class analytics](https://github.com/subratad27/adaptiq/blob/main/backend/app/routers/analytics_router.py): `backend/app/routers/analytics_router.py`
- [Learner simulation](https://github.com/subratad27/adaptiq/blob/main/backend/app/simulation.py): `backend/app/simulation.py`

### Persistence

- [Domain models](https://github.com/subratad27/adaptiq/blob/main/backend/app/models.py): `backend/app/models.py`
- [SQLite database](https://github.com/subratad27/adaptiq/blob/main/backend/app/database.py): `backend/app/database.py`
- [Startup seed](https://github.com/subratad27/adaptiq/blob/main/backend/app/seed.py): `backend/app/seed.py`

### Other components

- **Student**
- **Teacher**

## Connections

- Student → Login: signs in (evidence: `README.md`)
- Teacher → Login: signs in (evidence: `README.md`)
- App routes → Login: routes to (evidence: `frontend/src/main.jsx`)
- App routes → Practice quiz: routes to (evidence: `frontend/src/main.jsx`)
- App routes → Mastery map: routes to (evidence: `frontend/src/main.jsx`)
- App routes → Quiz history: routes to (evidence: `frontend/src/main.jsx`)
- App routes → Teacher dashboard: routes to (evidence: `frontend/src/main.jsx`)
- App routes → Research page: routes to (evidence: `frontend/src/main.jsx`)
- Login → API client: calls (evidence: `frontend/src/pages/Login.jsx`)
- Practice quiz → API client: calls (evidence: `frontend/src/pages/StudentQuiz.jsx`)
- Mastery map → API client: calls (evidence: `frontend/src/pages/MasteryMap.jsx`)
- Quiz history → API client: calls (evidence: `frontend/src/pages/QuizHistory.jsx`)
- Teacher dashboard → API client: calls (evidence: `frontend/src/pages/TeacherDashboard.jsx`)
- Research page → API client: calls (evidence: `frontend/src/pages/Research.jsx`)
- FastAPI app → Authentication: registers (evidence: `backend/app/main.py`)
- FastAPI app → Question bank: registers (evidence: `backend/app/main.py`)
- FastAPI app → Quiz publishing: registers (evidence: `backend/app/main.py`)
- FastAPI app → Practice endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI app → Class analytics: registers (evidence: `backend/app/main.py`)
- FastAPI app → Concepts: registers (evidence: `backend/app/main.py`)
- FastAPI app → Startup seed: runs at startup (evidence: `backend/app/main.py`)
- FastAPI app → SQLite database: creates tables (evidence: `backend/app/main.py`)
- Authentication → Token and passwords: uses (evidence: `backend/app/routers/auth_router.py`)
- Authentication → SQLite database: reads and writes (evidence: `backend/app/routers/auth_router.py`)
- Authentication → Domain models: uses (evidence: `backend/app/routers/auth_router.py`)
- Authentication → API schemas: validates with (evidence: `backend/app/routers/auth_router.py`)
- Question bank → SQLite database: reads and writes (evidence: `backend/app/routers/questions_router.py`)
- Question bank → Domain models: uses (evidence: `backend/app/routers/questions_router.py`)
- Question bank → API schemas: validates with (evidence: `backend/app/routers/questions_router.py`)
- Quiz publishing → SQLite database: reads and writes (evidence: `backend/app/routers/quizzes_router.py`)
- Quiz publishing → Domain models: uses (evidence: `backend/app/routers/quizzes_router.py`)
- Quiz publishing → API schemas: validates with (evidence: `backend/app/routers/quizzes_router.py`)
- Practice endpoints → SQLite database: reads and writes (evidence: `backend/app/routers/quiz_router.py`)
- Practice endpoints → Domain models: uses (evidence: `backend/app/routers/quiz_router.py`)
- Practice endpoints → API schemas: validates with (evidence: `backend/app/routers/quiz_router.py`)
- Practice endpoints → BKT engine: selects and updates (evidence: `backend/app/routers/quiz_router.py`)
- Concepts → SQLite database: reads (evidence: `backend/app/routers/concepts_router.py`)
- Concepts → Domain models: uses (evidence: `backend/app/routers/concepts_router.py`)
- Class analytics → SQLite database: reads (evidence: `backend/app/routers/analytics_router.py`)
- Class analytics → Domain models: uses (evidence: `backend/app/routers/analytics_router.py`)
- Class analytics → Learner simulation: runs (evidence: `backend/app/routers/analytics_router.py`)
- Learner simulation → SQLite database: reads and writes (evidence: `backend/app/simulation.py`)
- Learner simulation → Domain models: uses (evidence: `backend/app/simulation.py`)
- Learner simulation → BKT engine: uses (evidence: `backend/app/simulation.py`)
- Startup seed → Domain models: populates (evidence: `backend/app/seed.py`)
- Domain models → SQLite database: defines mapped tables (evidence: `backend/app/models.py`)
- Student → Practice quiz: practices (evidence: `README.md`)
- Student → Mastery map: reviews mastery (evidence: `README.md`)
