# giakhangcode/sql-uit architecture

> Architecture diagram of the GitHub repository giakhangcode/sql-uit, 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/giakhangcode/sql-uit
- Repository: https://github.com/giakhangcode/sql-uit

## Overview

UIT-SQL is a SQL-learning platform for students, instructors, and administrators. Users enter through role-aware routes, authenticate, then practice SQL problems or work on assignments and contests; instructors manage problems, classes, and assessments, while administrators manage users and classes. The backend exposes these capabilities through FastAPI routers and persists domain data through SQLAlchemy. The graph preserves the documented frontend and backend feature areas; unsampled route implementations and most frontend-to-backend endpoint mappings are not asserted.

Main entry points: [`backend/app/database.py`](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/database.py) (Database session), [`backend/app/main.py`](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/models.py`](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/models.py) (Domain models), [`frontend/src/app/App.tsx`](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/app/App.tsx) (App routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["App routing<br/>[App.tsx]"]
  node_authui["Auth context<br/>[AuthContext.tsx]"]
  node_authservice["Auth service<br/>[authService.ts]"]
  node_storage["Browser storage<br/>[storage.ts]"]
  node_apiclient["API client<br/>[apiClient.ts]"]
end

subgraph group_learning["Student learning"]
  node_studentpages["Student pages"]
  node_workspace["SQL workspace<br/>[WorkspacePage.tsx]"]
  node_studentapi["Student API service<br/>[studentApi.ts]"]
end

subgraph group_instruction["Instructor tools"]
  node_teacherpages["Teacher pages"]
  node_builder["Assessment builder<br/>[BuilderPages.tsx]"]
  node_teacherservice["Teacher service<br/>[teacherService.ts]"]
end

subgraph group_administration["Administration"]
  node_adminpages["Admin pages<br/>[AdminPages.tsx]"]
  node_adminservice["Admin service<br/>[adminService.ts]"]
end

subgraph group_backend["API and domain"]
  node_api["FastAPI application<br/>[main.py]"]
  node_authrouter["Authentication<br/>[auth.py]"]
  node_problemrouter["Problems and grading<br/>[problems.py]"]
  node_assignrouter["Assignments and contests<br/>[assignments.py]"]
  node_studentassign["Student assignments"]
  node_submissionrouter["Submissions<br/>[submissions.py]"]
  node_airouter["AI assistance<br/>[ai.py]"]
  node_classrouter["Classes<br/>[classes.py]"]
  node_adminrouters["Admin operations"]
  node_models["Domain models<br/>[models.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_sandbox["SQL sandbox<br/>[sandbox.py]"]
  node_database["Database session<br/>[database.py]"]
  node_sqlstore[("SQL Server")]
end

node_learner(("User"))

node_learner -->|"uses"| node_app
node_app -->|"reads session"| node_authui
node_authui -->|"delegates to"| node_authservice
node_authservice -->|"sends requests"| node_apiclient
node_authservice -->|"persists session"| node_storage
node_apiclient -->|"reads token"| node_storage
node_app -->|"routes to"| node_studentpages
node_app -->|"routes to"| node_teacherpages
node_app -->|"routes to"| node_adminpages
node_studentpages -->|"loads data"| node_studentapi
node_workspace -->|"loads data"| node_studentapi
node_workspace -->|"saves drafts"| node_storage
node_workspace -->|"uses chat panel"| node_studentpages
node_builder -->|"manages assessments"| node_teacherservice
node_teacherpages -->|"loads data"| node_teacherservice
node_teacherservice -->|"sends requests"| node_apiclient
node_adminpages -->|"loads admin data"| node_adminservice
node_adminservice -->|"sends requests"| node_apiclient
node_api -->|"registers routes"| node_authrouter
node_api -->|"registers routes"| node_problemrouter
node_api -->|"registers routes"| node_assignrouter
node_api -->|"registers routes"| node_studentassign
node_api -->|"registers routes"| node_submissionrouter
node_api -->|"registers routes"| node_airouter
node_api -->|"registers routes"| node_classrouter
node_api -->|"registers routes"| node_adminrouters
node_api -->|"creates tables"| node_database
node_models -->|"uses base"| node_database
node_authrouter -->|"queries via"| node_database
node_authrouter -->|"reads and writes"| node_models
node_authrouter -->|"validates with"| node_schemas
node_problemrouter -->|"queries via"| node_database
node_problemrouter -->|"uses entities"| node_models
node_problemrouter -->|"evaluates SQL"| node_sandbox
node_assignrouter -->|"queries via"| node_database
node_assignrouter -->|"uses entities"| node_models
node_studentassign -->|"reuses logic"| node_assignrouter
node_studentassign -->|"queries via"| node_database
node_submissionrouter -->|"queries via"| node_database
node_submissionrouter -->|"uses entities"| node_models
node_airouter -->|"queries via"| node_database
node_airouter -->|"uses entities"| node_models
node_classrouter -.->|"queries via"| node_database
node_adminrouters -.->|"queries via"| node_database
node_database -->|"connects to"| node_sqlstore

click node_app "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/app/App.tsx"
click node_authui "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/context/AuthContext.tsx"
click node_authservice "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/authService.ts"
click node_storage "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/storage.ts"
click node_apiclient "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/apiClient.ts"
click node_studentpages "https://github.com/giakhangcode/sql-uit/tree/main/frontend/src/pages/student"
click node_workspace "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/pages/student/WorkspacePage.tsx"
click node_studentapi "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/studentApi.ts"
click node_teacherpages "https://github.com/giakhangcode/sql-uit/tree/main/frontend/src/pages/teacher"
click node_builder "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/pages/teacher/BuilderPages.tsx"
click node_teacherservice "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/teacherService.ts"
click node_adminpages "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/pages/admin/AdminPages.tsx"
click node_adminservice "https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/adminService.ts"
click node_api "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/main.py"
click node_authrouter "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/auth.py"
click node_problemrouter "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/problems.py"
click node_assignrouter "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/assignments.py"
click node_studentassign "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/student_assignments.py"
click node_submissionrouter "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/submissions.py"
click node_airouter "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/ai.py"
click node_classrouter "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/classes.py"
click node_adminrouters "https://github.com/giakhangcode/sql-uit/tree/main/backend/app/routers"
click node_models "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/models.py"
click node_schemas "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/schemas.py"
click node_sandbox "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/services/sandbox.py"
click node_database "https://github.com/giakhangcode/sql-uit/blob/main/backend/app/database.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_authui,node_authservice,node_storage,node_apiclient,node_learner toneBlue
class node_studentpages,node_workspace,node_studentapi toneAmber
class node_teacherpages,node_builder,node_teacherservice toneMint
class node_adminpages,node_adminservice toneRose
class node_api,node_authrouter,node_problemrouter,node_assignrouter,node_studentassign,node_submissionrouter,node_airouter,node_classrouter,node_adminrouters,node_models,node_schemas,node_sandbox,node_database,node_sqlstore toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Auth context](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Auth service](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`
- [Browser storage](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/storage.ts): `frontend/src/services/storage.ts`
- [API client](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`

### Student learning

- [Student pages](https://github.com/giakhangcode/sql-uit/tree/main/frontend/src/pages/student): `frontend/src/pages/student`
- [SQL workspace](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/pages/student/WorkspacePage.tsx): `frontend/src/pages/student/WorkspacePage.tsx`
- [Student API service](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/studentApi.ts): `frontend/src/services/studentApi.ts`

### Instructor tools

- [Teacher pages](https://github.com/giakhangcode/sql-uit/tree/main/frontend/src/pages/teacher): `frontend/src/pages/teacher`
- [Assessment builder](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/pages/teacher/BuilderPages.tsx): `frontend/src/pages/teacher/BuilderPages.tsx`
- [Teacher service](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/teacherService.ts): `frontend/src/services/teacherService.ts`

### Administration

- [Admin pages](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/pages/admin/AdminPages.tsx): `frontend/src/pages/admin/AdminPages.tsx`
- [Admin service](https://github.com/giakhangcode/sql-uit/blob/main/frontend/src/services/adminService.ts): `frontend/src/services/adminService.ts`

### API and domain

- [FastAPI application](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Problems and grading](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/problems.py): `backend/app/routers/problems.py`
- [Assignments and contests](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/assignments.py): `backend/app/routers/assignments.py`
- [Student assignments](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/student_assignments.py): `backend/app/routers/student_assignments.py`
- [Submissions](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/submissions.py): `backend/app/routers/submissions.py`
- [AI assistance](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/ai.py): `backend/app/routers/ai.py`
- [Classes](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/routers/classes.py): `backend/app/routers/classes.py`
- [Admin operations](https://github.com/giakhangcode/sql-uit/tree/main/backend/app/routers): `backend/app/routers`
- [Domain models](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/models.py): `backend/app/models.py`
- [API schemas](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [SQL sandbox](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/services/sandbox.py): `backend/app/services/sandbox.py`
- [Database session](https://github.com/giakhangcode/sql-uit/blob/main/backend/app/database.py): `backend/app/database.py`
- **SQL Server**

### Other components

- **User**

## Connections

- User → App routing: uses
- App routing → Auth context: reads session (evidence: `frontend/src/app/App.tsx`)
- Auth context → Auth service: delegates to (evidence: `frontend/src/context/AuthContext.tsx`)
- Auth service → API client: sends requests (evidence: `frontend/src/services/authService.ts`)
- Auth service → Browser storage: persists session (evidence: `frontend/src/services/authService.ts`)
- API client → Browser storage: reads token (evidence: `frontend/src/services/apiClient.ts`)
- App routing → Student pages: routes to (evidence: `frontend/src/app/App.tsx`)
- App routing → Teacher pages: routes to (evidence: `frontend/src/app/App.tsx`)
- App routing → Admin pages: routes to (evidence: `frontend/src/app/App.tsx`)
- Student pages → Student API service: loads data (evidence: `frontend/src/pages/student/ContestsPage.tsx`)
- SQL workspace → Student API service: loads data (evidence: `frontend/src/pages/student/WorkspacePage.tsx`)
- SQL workspace → Browser storage: saves drafts (evidence: `frontend/src/pages/student/WorkspacePage.tsx`)
- SQL workspace → Student pages: uses chat panel (evidence: `frontend/src/pages/student/WorkspacePage.tsx`)
- Assessment builder → Teacher service: manages assessments (evidence: `frontend/src/pages/teacher/BuilderPages.tsx`)
- Teacher pages → Teacher service: loads data (evidence: `frontend/src/pages/teacher/TeacherLandingPages.tsx`)
- Teacher service → API client: sends requests (evidence: `frontend/src/services/teacherService.ts`)
- Admin pages → Admin service: loads admin data (evidence: `frontend/src/pages/admin/AdminPages.tsx`)
- Admin service → API client: sends requests (evidence: `frontend/src/services/adminService.ts`)
- FastAPI application → Authentication: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Problems and grading: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Assignments and contests: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Student assignments: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Submissions: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → AI assistance: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Classes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Admin operations: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Database session: creates tables (evidence: `backend/app/main.py`)
- Domain models → Database session: uses base (evidence: `backend/app/models.py`)
- Authentication → Database session: queries via (evidence: `backend/app/routers/auth.py`)
- Authentication → Domain models: reads and writes (evidence: `backend/app/routers/auth.py`)
- Authentication → API schemas: validates with (evidence: `backend/app/routers/auth.py`)
- Problems and grading → Database session: queries via (evidence: `backend/app/routers/problems.py`)
- Problems and grading → Domain models: uses entities (evidence: `backend/app/routers/problems.py`)
- Problems and grading → SQL sandbox: evaluates SQL (evidence: `backend/app/routers/problems.py`)
- Assignments and contests → Database session: queries via (evidence: `backend/app/routers/assignments.py`)
- Assignments and contests → Domain models: uses entities (evidence: `backend/app/routers/assignments.py`)
- Student assignments → Assignments and contests: reuses logic (evidence: `backend/app/routers/student_assignments.py`)
- Student assignments → Database session: queries via (evidence: `backend/app/routers/student_assignments.py`)
- Submissions → Database session: queries via (evidence: `backend/app/routers/submissions.py`)
- Submissions → Domain models: uses entities (evidence: `backend/app/routers/submissions.py`)
- AI assistance → Database session: queries via (evidence: `backend/app/routers/ai.py`)
- AI assistance → Domain models: uses entities (evidence: `backend/app/routers/ai.py`)
- Classes → Database session: queries via
- Admin operations → Database session: queries via (evidence: `backend/app/routers/auth.py`)
- Database session → SQL Server: connects to (evidence: `backend/app/database.py`)
