# h4r4k1ri/math-tutor-platform architecture

> Architecture diagram of the GitHub repository h4r4k1ri/math-tutor-platform, 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/h4r4k1ri/math-tutor-platform
- Repository: https://github.com/h4r4k1ri/math-tutor-platform

## Overview

Math Tutor Platform is a teacher–student education product. Users enter through the React application, authenticate, and use domain pages for assignments, feedback, lessons, materials, groups, and other teaching workflows; the frontend API client connects those workflows to a FastAPI backend. Backend routers expose the domain services, which persist domain records in PostgreSQL, while chat also supports real-time Socket.IO messaging. The README documents file uploads and teacher review of student solutions. Some feature modules were not sampled, so their internal call paths are not asserted.

Main entry points: [`backend/app/main.py`](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/main.py) (FastAPI entry), [`backend/app/shared/db.py`](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/shared/db.py) (PostgreSQL), [`backend/app/chat/socket.py`](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/chat/socket.py) (Realtime chat), [`frontend/src/App.tsx`](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/frontend/src/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_webapp["React application<br/>[App.tsx]"]
  node_authui["Auth context<br/>[AuthContext.tsx]"]
  node_apiclient["API client<br/>[client.ts]"]
  node_featurepages["Domain pages"]
  node_socketclient["Realtime client<br/>[socket.ts]"]
end

subgraph group_learning["Learning workflow"]
  node_assignments["Assignments<br/>[service.py]"]
  node_reviews["Solution review<br/>[service.py]"]
  node_lessons["Lessons<br/>[service.py]"]
  node_materials["Learning materials<br/>[service.py]"]
  node_uploads["File uploads<br/>[uploads.py]"]
  node_students["Student progress<br/>[service.py]"]
end

subgraph group_community["People and communication"]
  node_groups["Groups<br/>[service.py]"]
  node_tutoring["Tutoring requests<br/>[service.py]"]
  node_chatservice["Chat service<br/>[service.py]"]
  node_socketbackend["Realtime chat<br/>[socket.py]"]
end

subgraph group_platform["Platform services"]
  node_auth["Authentication<br/>[service.py]"]
  node_api["FastAPI entry<br/>[main.py]"]
  node_payments["Payments<br/>[service.py]"]
  node_notifications["Reminders and email"]
end

subgraph group_persistence["Persistence"]
  node_database[("PostgreSQL<br/>[db.py]")]
end

node_user(("Teacher / student"))

node_user -->|"uses"| node_webapp
node_webapp -->|"provides auth"| node_authui
node_authui -->|"requests identity"| node_apiclient
node_authui -->|"connects after login"| node_socketclient
node_webapp -->|"routes to"| node_featurepages
node_featurepages -->|"requests materials"| node_apiclient
node_apiclient -->|"HTTP requests"| node_api
node_api -->|"registers router"| node_auth
node_api -->|"registers router"| node_assignments
node_api -->|"registers router"| node_reviews
node_api -->|"registers router"| node_lessons
node_api -->|"registers router"| node_materials
node_api -->|"registers router"| node_groups
node_api -->|"registers router"| node_tutoring
node_api -->|"registers router"| node_chatservice
node_api -->|"registers router"| node_payments
node_api -->|"registers router"| node_students
node_api -->|"registers uploads"| node_uploads
node_api -->|"mounts socket app"| node_socketbackend
node_socketclient -->|"Socket.IO events"| node_socketbackend
node_materials -->|"emits updates"| node_socketbackend
node_chatservice -->|"emits chat events"| node_socketbackend
node_auth -->|"uses user model"| node_database
node_assignments -->|"uses models"| node_database
node_reviews -->|"uses models"| node_database
node_lessons -->|"uses models"| node_database
node_materials -->|"uses models"| node_database
node_students -->|"queries domain data"| node_database
node_groups -->|"uses domain models"| node_database
node_chatservice -->|"uses chat models"| node_database
node_socketbackend -->|"reads and writes"| node_database
node_payments -->|"uses payment model"| node_database

click node_webapp "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/frontend/src/context/AuthContext.tsx"
click node_apiclient "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/frontend/src/api/client.ts"
click node_featurepages "https://github.com/h4r4k1ri/math-tutor-platform/tree/main/frontend/src/pages"
click node_auth "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/auth/service.py"
click node_api "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/main.py"
click node_assignments "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/assignments/service.py"
click node_reviews "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/reviews/service.py"
click node_lessons "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/lessons/service.py"
click node_materials "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/materials/service.py"
click node_uploads "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/api/uploads.py"
click node_students "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/students/service.py"
click node_groups "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/groups/service.py"
click node_tutoring "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/tutoring_requests/service.py"
click node_chatservice "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/chat/service.py"
click node_socketbackend "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/chat/socket.py"
click node_socketclient "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/frontend/src/socket.ts"
click node_payments "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/payments/service.py"
click node_notifications "https://github.com/h4r4k1ri/math-tutor-platform/tree/main/backend/app/notifications"
click node_database "https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/shared/db.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_webapp,node_authui,node_apiclient,node_featurepages,node_socketclient toneBlue
class node_assignments,node_reviews,node_lessons,node_materials,node_uploads,node_students toneAmber
class node_groups,node_tutoring,node_chatservice,node_socketbackend toneMint
class node_auth,node_api,node_payments,node_notifications toneRose
class node_database,node_user toneIndigo
```

## Components

### Web application

- [React application](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [API client](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Domain pages](https://github.com/h4r4k1ri/math-tutor-platform/tree/main/frontend/src/pages): `frontend/src/pages`
- [Realtime client](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/frontend/src/socket.ts): `frontend/src/socket.ts`

### Learning workflow

- [Assignments](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/assignments/service.py): `backend/app/assignments/service.py`
- [Solution review](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/reviews/service.py): `backend/app/reviews/service.py`
- [Lessons](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/lessons/service.py): `backend/app/lessons/service.py`
- [Learning materials](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/materials/service.py): `backend/app/materials/service.py`
- [File uploads](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/api/uploads.py): `backend/app/api/uploads.py`
- [Student progress](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/students/service.py): `backend/app/students/service.py`

### People and communication

- [Groups](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/groups/service.py): `backend/app/groups/service.py`
- [Tutoring requests](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/tutoring_requests/service.py): `backend/app/tutoring_requests/service.py`
- [Chat service](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/chat/service.py): `backend/app/chat/service.py`
- [Realtime chat](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/chat/socket.py): `backend/app/chat/socket.py`

### Platform services

- [Authentication](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/auth/service.py): `backend/app/auth/service.py`
- [FastAPI entry](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/main.py): `backend/app/main.py`
- [Payments](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/payments/service.py): `backend/app/payments/service.py`
- [Reminders and email](https://github.com/h4r4k1ri/math-tutor-platform/tree/main/backend/app/notifications): `backend/app/notifications`

### Persistence

- [PostgreSQL](https://github.com/h4r4k1ri/math-tutor-platform/blob/main/backend/app/shared/db.py): `backend/app/shared/db.py`

### Other components

- **Teacher / student**

## Connections

- Teacher / student → React application: uses
- React application → Auth context: provides auth (evidence: `frontend/src/App.tsx`)
- Auth context → API client: requests identity (evidence: `frontend/src/context/AuthContext.tsx`)
- Auth context → Realtime client: connects after login (evidence: `frontend/src/context/AuthContext.tsx`)
- React application → Domain pages: routes to (evidence: `frontend/src/App.tsx`)
- Domain pages → API client: requests materials (evidence: `frontend/src/pages/MaterialsPage.tsx`)
- API client → FastAPI entry: HTTP requests (evidence: `frontend/src/api/client.ts`)
- FastAPI entry → Authentication: registers router (evidence: `backend/app/main.py`)
- FastAPI entry → Assignments: registers router (evidence: `backend/app/main.py`)
- FastAPI entry → Solution review: registers router (evidence: `backend/app/main.py`)
- FastAPI entry → Lessons: registers router (evidence: `backend/app/main.py`)
- FastAPI entry → Learning materials: registers router (evidence: `backend/app/main.py`)
- FastAPI entry → Groups: registers router (evidence: `backend/app/main.py`)
- FastAPI entry → Tutoring requests: registers router (evidence: `backend/app/main.py`)
- FastAPI entry → Chat service: registers router (evidence: `backend/app/main.py`)
- FastAPI entry → Payments: registers router (evidence: `backend/app/main.py`)
- FastAPI entry → Student progress: registers router (evidence: `backend/app/main.py`)
- FastAPI entry → File uploads: registers uploads (evidence: `backend/app/main.py`)
- FastAPI entry → Realtime chat: mounts socket app (evidence: `backend/app/main.py`)
- Realtime client → Realtime chat: Socket.IO events
- Learning materials → Realtime chat: emits updates (evidence: `backend/app/materials/service.py`)
- Chat service → Realtime chat: emits chat events (evidence: `backend/app/chat/service.py`)
- Authentication → PostgreSQL: uses user model
- Assignments → PostgreSQL: uses models
- Solution review → PostgreSQL: uses models
- Lessons → PostgreSQL: uses models
- Learning materials → PostgreSQL: uses models (evidence: `backend/app/materials/service.py`)
- Student progress → PostgreSQL: queries domain data (evidence: `backend/app/students/service.py`)
- Groups → PostgreSQL: uses domain models (evidence: `backend/app/groups/service.py`)
- Chat service → PostgreSQL: uses chat models (evidence: `backend/app/chat/service.py`)
- Realtime chat → PostgreSQL: reads and writes (evidence: `backend/app/chat/socket.py`)
- Payments → PostgreSQL: uses payment model (evidence: `backend/app/payments/service.py`)
