# shubbham-kumarr/intelligent-academic-test-system architecture

> Architecture diagram of the GitHub repository shubbham-kumarr/intelligent-academic-test-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubbham-kumarr/intelligent-academic-test-system
- Repository: https://github.com/shubbham-kumarr/intelligent-academic-test-system

## Overview

IATS is a source-grounded academic testing platform for students and educators. Users authenticate, provide or select learning material, take assessments, and review results; educators also manage students and use performance reporting. The repository documents adaptive tests, automated grading, analytics, and AI remediation, though the backend test controller and several related modules are absent from the supplied tree. Edges for those capabilities are therefore limited to documented API calls or marked unverified; sampled source confirms PDF ingestion and authentication details.

Main entry points: [`frontend/src/services/api.ts`](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/services/api.ts) (REST client), [`frontend/src/App.tsx`](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/App.tsx) (Route application), [`backend/app/v1/controllers/auth_controller.py`](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/v1/controllers/auth_controller.py) (Auth controller), [`frontend/src/context/AuthContext.tsx`](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/context/AuthContext.tsx) (Auth state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_app["Route application<br/>[App.tsx]"]
  node_home["Learning home<br/>[HomePage.tsx]"]
  node_authpage["Sign-in page<br/>[AuthPage.tsx]"]
  node_dashboard["Student dashboard<br/>[DashboardPage.tsx]"]
  node_tests["Assessment taking<br/>[TestsPage.tsx]"]
  node_admin["Student administration"]
  node_remediation["Concept remediation"]
end

subgraph group_identity["Identity and access"]
  node_authstate["Auth state<br/>[AuthContext.tsx]"]
  node_authapi["Authentication endpoints<br/>[auth_route.py]"]
  node_authcontroller["Auth controller<br/>[auth_controller.py]"]
end

subgraph group_learning["Learning services"]
  node_sourceapi["Source upload route<br/>[source_route.py]"]
  node_sourcecontroller["Source ingestion"]
  node_pdf["PDF extraction<br/>[pdf_service.py]"]
  node_agent["Academic agent<br/>[academic_agent.py]"]
  node_testservice["Test generation modes"]
  node_groq["Groq client<br/>[groq_client.py]"]
end

subgraph group_platform["API and persistence"]
  node_usermodel[("User records<br/>[user_model.py]")]
  node_userschema["User serialization<br/>[user_schema.py]"]
  node_adminschema["Admin serialization<br/>[admin_schema.py]"]
  node_api["REST client<br/>[api.ts]"]
end

node_student(("Student"))
node_educator(("Educator"))
node_groqservice{{"Groq API"}}
node_backendapi{{"Flask REST API"}}

node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_authpage
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_tests
node_app -->|"routes to"| node_admin
node_app -->|"provides auth"| node_authstate
node_student -.->|"uses"| node_home
node_student -.->|"signs in"| node_authpage
node_educator -.->|"manages learners"| node_admin
node_authpage -->|"authenticates through"| node_authstate
node_authstate -->|"requests profile"| node_backendapi
node_authstate -->|"calls login"| node_authapi
node_authapi -->|"dispatches to"| node_authcontroller
node_authcontroller -->|"reads and writes"| node_usermodel
node_authcontroller -->|"serializes with"| node_userschema
node_authcontroller -->|"serializes with"| node_adminschema
node_home -->|"requests learning data"| node_api
node_tests -->|"requests assessments"| node_api
node_dashboard -->|"requests metrics"| node_api
node_admin -->|"requests student data"| node_api
node_api -->|"calls REST endpoints"| node_backendapi
node_api -->|"uploads source"| node_sourceapi
node_sourceapi -->|"dispatches to"| node_sourcecontroller
node_sourcecontroller -->|"extracts PDF text"| node_pdf
node_api -.->|"requests test generation"| node_agent
node_agent -->|"uses test modes"| node_testservice
node_agent -->|"requests completions"| node_groq
node_groq -->|"sends completions"| node_groqservice
node_tests -->|"renders feedback"| node_remediation
node_remediation -->|"requests explanation"| node_api

click node_app "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/pages/HomePage.tsx"
click node_authpage "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/pages/AuthPage.tsx"
click node_dashboard "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_tests "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/pages/TestsPage.tsx"
click node_admin "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/pages/AdminStudentsPage.tsx"
click node_remediation "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/components/ConceptRemediationCard.tsx"
click node_authstate "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/context/AuthContext.tsx"
click node_authapi "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/v1/routes/auth_route.py"
click node_authcontroller "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/v1/controllers/auth_controller.py"
click node_usermodel "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/models/user_model.py"
click node_userschema "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/schemas/user_schema.py"
click node_adminschema "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/schemas/admin_schema.py"
click node_api "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/services/api.ts"
click node_sourceapi "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/v1/routes/source_route.py"
click node_sourcecontroller "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/v1/controllers/source_controller.py"
click node_pdf "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/services/pdf_service.py"
click node_agent "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/services/agent_service/academic_agent.py"
click node_testservice "https://github.com/shubbham-kumarr/intelligent-academic-test-system/tree/main/backend/app/services/test_service"
click node_groq "https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/services/agent_service/groq_client.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_app,node_home,node_authpage,node_dashboard,node_tests,node_admin,node_remediation toneBlue
class node_authstate,node_authapi,node_authcontroller toneAmber
class node_sourceapi,node_sourcecontroller,node_pdf,node_agent,node_testservice,node_groq,node_groqservice,node_backendapi toneMint
class node_usermodel,node_userschema,node_adminschema,node_api toneRose
class node_student,node_educator toneIndigo
```

## Components

### User experience

- [Route application](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Learning home](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/pages/HomePage.tsx): `frontend/src/pages/HomePage.tsx`
- [Sign-in page](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/pages/AuthPage.tsx): `frontend/src/pages/AuthPage.tsx`
- [Student dashboard](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Assessment taking](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/pages/TestsPage.tsx): `frontend/src/pages/TestsPage.tsx`
- [Student administration](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/pages/AdminStudentsPage.tsx): `frontend/src/pages/AdminStudentsPage.tsx`
- [Concept remediation](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/components/ConceptRemediationCard.tsx): `frontend/src/components/ConceptRemediationCard.tsx`

### Identity and access

- [Auth state](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Authentication endpoints](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/v1/routes/auth_route.py): `backend/app/v1/routes/auth_route.py`
- [Auth controller](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/v1/controllers/auth_controller.py): `backend/app/v1/controllers/auth_controller.py`

### Learning services

- [Source upload route](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/v1/routes/source_route.py): `backend/app/v1/routes/source_route.py`
- [Source ingestion](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/v1/controllers/source_controller.py): `backend/app/v1/controllers/source_controller.py`
- [PDF extraction](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/services/pdf_service.py): `backend/app/services/pdf_service.py`
- [Academic agent](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/services/agent_service/academic_agent.py): `backend/app/services/agent_service/academic_agent.py`
- [Test generation modes](https://github.com/shubbham-kumarr/intelligent-academic-test-system/tree/main/backend/app/services/test_service): `backend/app/services/test_service`
- [Groq client](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/services/agent_service/groq_client.py): `backend/app/services/agent_service/groq_client.py`

### API and persistence

- [User records](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/models/user_model.py): `backend/app/models/user_model.py`
- [User serialization](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/schemas/user_schema.py): `backend/app/schemas/user_schema.py`
- [Admin serialization](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/backend/app/schemas/admin_schema.py): `backend/app/schemas/admin_schema.py`
- [REST client](https://github.com/shubbham-kumarr/intelligent-academic-test-system/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Other components

- **Student**
- **Educator**
- **Groq API**
- **Flask REST API**

## Connections

- Route application → Learning home: routes to (evidence: `frontend/src/App.tsx`)
- Route application → Sign-in page: routes to (evidence: `frontend/src/App.tsx`)
- Route application → Student dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Route application → Assessment taking: routes to (evidence: `frontend/src/App.tsx`)
- Route application → Student administration: routes to (evidence: `frontend/src/App.tsx`)
- Route application → Auth state: provides auth (evidence: `frontend/src/App.tsx`)
- Student → Learning home: uses
- Student → Sign-in page: signs in
- Educator → Student administration: manages learners
- Sign-in page → Auth state: authenticates through (evidence: `frontend/src/pages/AuthPage.tsx`)
- Auth state → Flask REST API: requests profile (evidence: `frontend/src/context/AuthContext.tsx`)
- Auth state → Authentication endpoints: calls login (evidence: `frontend/src/context/AuthContext.tsx`)
- Authentication endpoints → Auth controller: dispatches to (evidence: `backend/app/v1/routes/auth_route.py`)
- Auth controller → User records: reads and writes (evidence: `backend/app/v1/controllers/auth_controller.py`)
- Auth controller → User serialization: serializes with (evidence: `backend/app/v1/controllers/auth_controller.py`)
- Auth controller → Admin serialization: serializes with (evidence: `backend/app/v1/controllers/auth_controller.py`)
- Learning home → REST client: requests learning data (evidence: `frontend/src/pages/HomePage.tsx`)
- Assessment taking → REST client: requests assessments (evidence: `frontend/src/pages/TestsPage.tsx`)
- Student dashboard → REST client: requests metrics (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Student administration → REST client: requests student data (evidence: `frontend/src/pages/AdminStudentsPage.tsx`)
- REST client → Flask REST API: calls REST endpoints (evidence: `frontend/src/services/api.ts`)
- REST client → Source upload route: uploads source (evidence: `frontend/src/services/api.ts`)
- Source upload route → Source ingestion: dispatches to (evidence: `backend/app/v1/routes/source_route.py`)
- Source ingestion → PDF extraction: extracts PDF text (evidence: `backend/app/v1/controllers/source_controller.py`)
- REST client → Academic agent: requests test generation
- Academic agent → Test generation modes: uses test modes (evidence: `backend/app/services/agent_service/academic_agent.py`)
- Academic agent → Groq client: requests completions (evidence: `backend/app/services/agent_service/academic_agent.py`)
- Groq client → Groq API: sends completions (evidence: `backend/app/services/agent_service/groq_client.py`)
- Assessment taking → Concept remediation: renders feedback (evidence: `frontend/src/pages/TestsPage.tsx`)
- Concept remediation → REST client: requests explanation (evidence: `frontend/src/services/api.ts`)
