# jolin181/skill_tracker architecture

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

- Interactive diagram: https://gitdiagram.com/jolin181/skill_tracker
- Repository: https://github.com/jolin181/skill_tracker

## Overview

Skill Leveling Platform lets students enroll in skill tracks, prepare for AI-generated assessments, book exam slots, take timed exams, and use results to guide level progression and skill-gap analysis. Its FastAPI backend also supports account administration, invigilation logistics, and analytics; the React frontend exposes student and staff workflows. The graph emphasizes domain stages and the attempt/progression layer. Some feature modules are represented at directory level because their implementation was not excerpted; those links are shown only where documented or indexed.

Main entry points: [`app/main.py`](https://github.com/jolin181/skill_tracker/blob/main/app/main.py) (API router host), [`app/modules/attempts/service.py`](https://github.com/jolin181/skill_tracker/blob/main/app/modules/attempts/service.py) (Exam attempts), [`app/modules/slots/service.py`](https://github.com/jolin181/skill_tracker/blob/main/app/modules/slots/service.py) (Slot booking), [`app/modules/auth/service.py`](https://github.com/jolin181/skill_tracker/blob/main/app/modules/auth/service.py) (Accounts and auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_web["Role-based pages<br/>[App.tsx]"]
end

subgraph group_identity["Identity and tracks"]
  node_auth["Accounts and auth<br/>[service.py]"]
  node_users["User administration<br/>[service.py]"]
  node_domains["Tracks and levels<br/>[service.py]"]
end

subgraph group_assessment["Assessment lifecycle"]
  node_ai["Question generation"]
  node_exams["Exam definitions<br/>[service.py]"]
  node_attempts["Exam attempts<br/>[service.py]"]
end

subgraph group_operations["Exam operations"]
  node_slots["Slot booking<br/>[service.py]"]
  node_halls["Halls and allocation<br/>[service.py]"]
  node_hall_sheets["Hall sheets<br/>[service.py]"]
end

subgraph group_insights["Progress and insights"]
  node_progress["Eligibility and progression<br/>[service.py]"]
  node_analytics["Analytics summaries<br/>[service.py]"]
  node_notifications["Notifications"]
end

subgraph group_platform["Backend foundation"]
  node_api["API router host<br/>[main.py]"]
  node_database[("PostgreSQL data<br/>[database.py]")]
  node_security["JWT and security<br/>[security.py]"]
  node_audit["Audit logging<br/>[audit.py]"]
  node_jobs["Nightly refresh<br/>[scheduled_jobs.py]"]
end

node_student(("Student"))

node_student -->|"uses"| node_web
node_web -.->|"calls API"| node_api
node_api -->|"mounts routes"| node_auth
node_api -->|"mounts routes"| node_users
node_api -->|"mounts routes"| node_domains
node_api -->|"mounts routes"| node_exams
node_api -->|"mounts routes"| node_slots
node_api -->|"mounts routes"| node_attempts
node_api -->|"mounts routes"| node_progress
node_student -->|"enrolls in tracks"| node_domains
node_student -->|"books exams"| node_slots
node_slots -->|"checks eligibility"| node_progress
node_attempts -->|"reads booking context"| node_slots
node_attempts -->|"records results"| node_progress
node_attempts -->|"uses question service"| node_ai
node_attempts -->|"uses exam service"| node_exams
node_halls -->|"uses slot models"| node_slots
node_hall_sheets -->|"uses hall models"| node_halls
node_jobs -->|"runs refresh"| node_analytics
node_analytics -->|"stores summaries"| node_database
node_auth -->|"issues tokens"| node_security
node_auth -->|"records events"| node_audit
node_users -->|"records changes"| node_audit
node_api -->|"uses sessions"| node_database

click node_web "https://github.com/jolin181/skill_tracker/blob/main/frontend/src/App.tsx"
click node_auth "https://github.com/jolin181/skill_tracker/blob/main/app/modules/auth/service.py"
click node_users "https://github.com/jolin181/skill_tracker/blob/main/app/modules/users/service.py"
click node_domains "https://github.com/jolin181/skill_tracker/blob/main/app/modules/domains/service.py"
click node_ai "https://github.com/jolin181/skill_tracker/tree/main/app/modules/ai_engine"
click node_exams "https://github.com/jolin181/skill_tracker/blob/main/app/modules/exams/service.py"
click node_slots "https://github.com/jolin181/skill_tracker/blob/main/app/modules/slots/service.py"
click node_halls "https://github.com/jolin181/skill_tracker/blob/main/app/modules/allocation/service.py"
click node_hall_sheets "https://github.com/jolin181/skill_tracker/blob/main/app/modules/hall_sheets/service.py"
click node_attempts "https://github.com/jolin181/skill_tracker/blob/main/app/modules/attempts/service.py"
click node_progress "https://github.com/jolin181/skill_tracker/blob/main/app/modules/progress/service.py"
click node_analytics "https://github.com/jolin181/skill_tracker/blob/main/app/modules/analytics/service.py"
click node_notifications "https://github.com/jolin181/skill_tracker/tree/main/app/modules/notifications"
click node_api "https://github.com/jolin181/skill_tracker/blob/main/app/main.py"
click node_database "https://github.com/jolin181/skill_tracker/blob/main/app/core/database.py"
click node_security "https://github.com/jolin181/skill_tracker/blob/main/app/core/security.py"
click node_audit "https://github.com/jolin181/skill_tracker/blob/main/app/core/audit.py"
click node_jobs "https://github.com/jolin181/skill_tracker/blob/main/app/scheduled_jobs.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 toneBlue
class node_auth,node_users,node_domains toneAmber
class node_ai,node_exams,node_attempts toneMint
class node_slots,node_halls,node_hall_sheets toneRose
class node_progress,node_analytics,node_notifications,node_student toneIndigo
class node_api,node_database,node_security,node_audit,node_jobs toneTeal
```

## Components

### Web application

- [Role-based pages](https://github.com/jolin181/skill_tracker/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Identity and tracks

- [Accounts and auth](https://github.com/jolin181/skill_tracker/blob/main/app/modules/auth/service.py): `app/modules/auth/service.py`
- [User administration](https://github.com/jolin181/skill_tracker/blob/main/app/modules/users/service.py): `app/modules/users/service.py`
- [Tracks and levels](https://github.com/jolin181/skill_tracker/blob/main/app/modules/domains/service.py): `app/modules/domains/service.py`

### Assessment lifecycle

- [Question generation](https://github.com/jolin181/skill_tracker/tree/main/app/modules/ai_engine): `app/modules/ai_engine`
- [Exam definitions](https://github.com/jolin181/skill_tracker/blob/main/app/modules/exams/service.py): `app/modules/exams/service.py`
- [Exam attempts](https://github.com/jolin181/skill_tracker/blob/main/app/modules/attempts/service.py): `app/modules/attempts/service.py`

### Exam operations

- [Slot booking](https://github.com/jolin181/skill_tracker/blob/main/app/modules/slots/service.py): `app/modules/slots/service.py`
- [Halls and allocation](https://github.com/jolin181/skill_tracker/blob/main/app/modules/allocation/service.py): `app/modules/allocation/service.py`
- [Hall sheets](https://github.com/jolin181/skill_tracker/blob/main/app/modules/hall_sheets/service.py): `app/modules/hall_sheets/service.py`

### Progress and insights

- [Eligibility and progression](https://github.com/jolin181/skill_tracker/blob/main/app/modules/progress/service.py): `app/modules/progress/service.py`
- [Analytics summaries](https://github.com/jolin181/skill_tracker/blob/main/app/modules/analytics/service.py): `app/modules/analytics/service.py`
- [Notifications](https://github.com/jolin181/skill_tracker/tree/main/app/modules/notifications): `app/modules/notifications`

### Backend foundation

- [API router host](https://github.com/jolin181/skill_tracker/blob/main/app/main.py): `app/main.py`
- [PostgreSQL data](https://github.com/jolin181/skill_tracker/blob/main/app/core/database.py): `app/core/database.py`
- [JWT and security](https://github.com/jolin181/skill_tracker/blob/main/app/core/security.py): `app/core/security.py`
- [Audit logging](https://github.com/jolin181/skill_tracker/blob/main/app/core/audit.py): `app/core/audit.py`
- [Nightly refresh](https://github.com/jolin181/skill_tracker/blob/main/app/scheduled_jobs.py): `app/scheduled_jobs.py`

### Other components

- **Student**

## Connections

- Student → Role-based pages: uses (evidence: `README.md`)
- Role-based pages → API router host: calls API
- API router host → Accounts and auth: mounts routes (evidence: `app/main.py`)
- API router host → User administration: mounts routes (evidence: `app/main.py`)
- API router host → Tracks and levels: mounts routes (evidence: `app/main.py`)
- API router host → Exam definitions: mounts routes (evidence: `app/main.py`)
- API router host → Slot booking: mounts routes (evidence: `app/main.py`)
- API router host → Exam attempts: mounts routes (evidence: `app/main.py`)
- API router host → Eligibility and progression: mounts routes (evidence: `app/main.py`)
- Student → Tracks and levels: enrolls in tracks (evidence: `README.md`)
- Student → Slot booking: books exams (evidence: `README.md`)
- Slot booking → Eligibility and progression: checks eligibility (evidence: `app/modules/progress/service.py`)
- Exam attempts → Slot booking: reads booking context (evidence: `app/modules/attempts/service.py`)
- Exam attempts → Eligibility and progression: records results (evidence: `app/modules/progress/service.py`)
- Exam attempts → Question generation: uses question service (evidence: `app/modules/attempts/service.py`)
- Exam attempts → Exam definitions: uses exam service (evidence: `app/modules/attempts/service.py`)
- Halls and allocation → Slot booking: uses slot models (evidence: `app/modules/allocation/service.py`)
- Hall sheets → Halls and allocation: uses hall models (evidence: `app/modules/hall_sheets/service.py`)
- Nightly refresh → Analytics summaries: runs refresh (evidence: `app/scheduled_jobs.py`)
- Analytics summaries → PostgreSQL data: stores summaries (evidence: `app/modules/analytics/service.py`)
- Accounts and auth → JWT and security: issues tokens (evidence: `app/modules/auth/service.py`)
- Accounts and auth → Audit logging: records events (evidence: `app/modules/auth/service.py`)
- User administration → Audit logging: records changes (evidence: `app/modules/users/service.py`)
- API router host → PostgreSQL data: uses sessions (evidence: `app/main.py`)
