# dleungdl/eduops-system architecture

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

- Interactive diagram: https://gitdiagram.com/dleungdl/eduops-system
- Repository: https://github.com/dleungdl/eduops-system

## Overview

EduOps is a single-organization education-operations backend for student–tutor pairings, groups, monthly roster approval, lessons, attendance, billing, and staff pay. The main workflow is manager enrollment and matching, roster preparation and tutor/manager approval, then lesson generation and operational recording. The graph also includes authentication, organization settings, groups, and staff enrollment/payroll as distinct capabilities. Router registration and selected calls are evidenced by the excerpts and SOURCE INDEX; unsampled router internals are represented without inferred call chains.

Main entry points: [`backend/app/main.py`](https://github.com/dleungdl/eduops-system/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/models.py`](https://github.com/dleungdl/eduops-system/blob/main/backend/app/models.py) (Education records), [`backend/app/database.py`](https://github.com/dleungdl/eduops-system/blob/main/backend/app/database.py) (Database sessions), [`backend/app/routers/auth.py`](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/auth.py) (Login and identity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interface and API"]
  node_browser["Browser UI<br/>[index.html]"]
  node_api["FastAPI application<br/>[main.py]"]
end

subgraph group_identity["Identity and settings"]
  node_auth["Login and identity<br/>[auth.py]"]
  node_access["Token access control<br/>[deps.py]"]
  node_security["JWT and passwords<br/>[security.py]"]
  node_organization["Organization settings<br/>[meta.py]"]
  node_org_defaults["Labels and defaults<br/>[org.py]"]
end

subgraph group_operations["Enrollment and scheduling"]
  node_records["Student and tutor records<br/>[crud.py]"]
  node_enrollment["Enrollment matching<br/>[enroll.py]"]
  node_staff_enrollment["Staff enrollment<br/>[staff_enroll.py]"]
  node_groups["Group management<br/>[groups.py]"]
  node_rosters["Monthly roster approval<br/>[rosters.py]"]
  node_scheduling["Conflict and capacity rules<br/>[scheduling.py]"]
end

subgraph group_delivery["Lessons and finance"]
  node_lessons["Lesson generation and changes<br/>[lessons.py]"]
  node_attendance["Attendance tracking<br/>[attendance.py]"]
  node_payments["Student payments<br/>[payments.py]"]
  node_payroll["Staff salary<br/>[salary.py]"]
end

subgraph group_persistence["Data layer"]
  node_models["Education records<br/>[models.py]"]
  node_salary_models["Salary records<br/>[models_salary.py]"]
  node_preference_models["Student preferences"]
  node_subject_models["Tutor subjects"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_database["Database sessions<br/>[database.py]"]
  node_postgres[("PostgreSQL")]
end

node_staff(("Operations staff"))

node_staff -->|"uses"| node_browser
node_browser -->|"calls API"| node_api
node_api -->|"registers route"| node_auth
node_api -->|"registers route"| node_organization
node_api -->|"registers route"| node_records
node_api -->|"registers route"| node_enrollment
node_api -->|"registers route"| node_staff_enrollment
node_api -->|"registers route"| node_groups
node_api -->|"registers route"| node_rosters
node_api -->|"registers route"| node_lessons
node_api -->|"registers route"| node_attendance
node_api -->|"registers route"| node_payments
node_api -->|"registers route"| node_payroll
node_auth -->|"verifies password"| node_security
node_auth -->|"loads current user"| node_access
node_access -->|"decodes token"| node_security
node_organization -->|"uses defaults"| node_org_defaults
node_enrollment -->|"checks availability"| node_scheduling
node_rosters -->|"checks conflicts"| node_scheduling
node_lessons -->|"checks schedules"| node_scheduling
node_enrollment -->|"stores preferences"| node_preference_models
node_records -->|"manages subjects"| node_subject_models
node_rosters -->|"validates responses"| node_schemas
node_lessons -->|"validates responses"| node_schemas
node_records -->|"queries records"| node_models
node_enrollment -->|"creates pairings"| node_models
node_staff_enrollment -->|"uses salary records"| node_salary_models
node_payroll -->|"queries salaries"| node_salary_models
node_attendance -->|"records attendance"| node_models
node_payments -->|"records payments"| node_models
node_groups -->|"manages groups"| node_models
node_rosters -->|"stores rosters"| node_models
node_lessons -->|"stores lessons"| node_models
node_auth -->|"queries users"| node_models
node_models -->|"uses base"| node_database
node_salary_models -->|"uses base"| node_database
node_preference_models -->|"uses base"| node_database
node_subject_models -->|"uses base"| node_database
node_database -->|"connects"| node_postgres

click node_browser "https://github.com/dleungdl/eduops-system/blob/main/backend/static/index.html"
click node_api "https://github.com/dleungdl/eduops-system/blob/main/backend/app/main.py"
click node_auth "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/auth.py"
click node_access "https://github.com/dleungdl/eduops-system/blob/main/backend/app/deps.py"
click node_security "https://github.com/dleungdl/eduops-system/blob/main/backend/app/security.py"
click node_organization "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/meta.py"
click node_org_defaults "https://github.com/dleungdl/eduops-system/blob/main/backend/app/org.py"
click node_records "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/crud.py"
click node_enrollment "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/enroll.py"
click node_staff_enrollment "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/staff_enroll.py"
click node_groups "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/groups.py"
click node_rosters "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/rosters.py"
click node_scheduling "https://github.com/dleungdl/eduops-system/blob/main/backend/app/scheduling.py"
click node_lessons "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/lessons.py"
click node_attendance "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/attendance.py"
click node_payments "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/payments.py"
click node_payroll "https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/salary.py"
click node_models "https://github.com/dleungdl/eduops-system/blob/main/backend/app/models.py"
click node_salary_models "https://github.com/dleungdl/eduops-system/blob/main/backend/app/models_salary.py"
click node_preference_models "https://github.com/dleungdl/eduops-system/blob/main/backend/app/models_student_pref.py"
click node_subject_models "https://github.com/dleungdl/eduops-system/blob/main/backend/app/models_tutor_subjects.py"
click node_schemas "https://github.com/dleungdl/eduops-system/blob/main/backend/app/schemas.py"
click node_database "https://github.com/dleungdl/eduops-system/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_browser,node_api toneBlue
class node_auth,node_access,node_security,node_organization,node_org_defaults toneAmber
class node_records,node_enrollment,node_staff_enrollment,node_groups,node_rosters,node_scheduling toneMint
class node_lessons,node_attendance,node_payments,node_payroll toneRose
class node_models,node_salary_models,node_preference_models,node_subject_models,node_schemas,node_database,node_postgres,node_staff toneIndigo
```

## Components

### User interface and API

- [Browser UI](https://github.com/dleungdl/eduops-system/blob/main/backend/static/index.html): `backend/static/index.html`
- [FastAPI application](https://github.com/dleungdl/eduops-system/blob/main/backend/app/main.py): `backend/app/main.py`

### Identity and settings

- [Login and identity](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Token access control](https://github.com/dleungdl/eduops-system/blob/main/backend/app/deps.py): `backend/app/deps.py`
- [JWT and passwords](https://github.com/dleungdl/eduops-system/blob/main/backend/app/security.py): `backend/app/security.py`
- [Organization settings](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/meta.py): `backend/app/routers/meta.py`
- [Labels and defaults](https://github.com/dleungdl/eduops-system/blob/main/backend/app/org.py): `backend/app/org.py`

### Enrollment and scheduling

- [Student and tutor records](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/crud.py): `backend/app/routers/crud.py`
- [Enrollment matching](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/enroll.py): `backend/app/routers/enroll.py`
- [Staff enrollment](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/staff_enroll.py): `backend/app/routers/staff_enroll.py`
- [Group management](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/groups.py): `backend/app/routers/groups.py`
- [Monthly roster approval](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/rosters.py): `backend/app/routers/rosters.py`
- [Conflict and capacity rules](https://github.com/dleungdl/eduops-system/blob/main/backend/app/scheduling.py): `backend/app/scheduling.py`

### Lessons and finance

- [Lesson generation and changes](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/lessons.py): `backend/app/routers/lessons.py`
- [Attendance tracking](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/attendance.py): `backend/app/routers/attendance.py`
- [Student payments](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/payments.py): `backend/app/routers/payments.py`
- [Staff salary](https://github.com/dleungdl/eduops-system/blob/main/backend/app/routers/salary.py): `backend/app/routers/salary.py`

### Data layer

- [Education records](https://github.com/dleungdl/eduops-system/blob/main/backend/app/models.py): `backend/app/models.py`
- [Salary records](https://github.com/dleungdl/eduops-system/blob/main/backend/app/models_salary.py): `backend/app/models_salary.py`
- [Student preferences](https://github.com/dleungdl/eduops-system/blob/main/backend/app/models_student_pref.py): `backend/app/models_student_pref.py`
- [Tutor subjects](https://github.com/dleungdl/eduops-system/blob/main/backend/app/models_tutor_subjects.py): `backend/app/models_tutor_subjects.py`
- [API schemas](https://github.com/dleungdl/eduops-system/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Database sessions](https://github.com/dleungdl/eduops-system/blob/main/backend/app/database.py): `backend/app/database.py`
- **PostgreSQL**

### Other components

- **Operations staff**

## Connections

- Operations staff → Browser UI: uses (evidence: `README.md`)
- Browser UI → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Login and identity: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Organization settings: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Student and tutor records: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Enrollment matching: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Staff enrollment: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Group management: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Monthly roster approval: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Lesson generation and changes: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Attendance tracking: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Student payments: registers route (evidence: `backend/app/main.py`)
- FastAPI application → Staff salary: registers route (evidence: `backend/app/main.py`)
- Login and identity → JWT and passwords: verifies password (evidence: `backend/app/routers/auth.py`)
- Login and identity → Token access control: loads current user (evidence: `backend/app/routers/auth.py`)
- Token access control → JWT and passwords: decodes token (evidence: `backend/app/deps.py`)
- Organization settings → Labels and defaults: uses defaults (evidence: `backend/app/routers/meta.py`)
- Enrollment matching → Conflict and capacity rules: checks availability (evidence: `backend/app/routers/enroll.py`)
- Monthly roster approval → Conflict and capacity rules: checks conflicts (evidence: `backend/app/routers/rosters.py`)
- Lesson generation and changes → Conflict and capacity rules: checks schedules (evidence: `backend/app/routers/lessons.py`)
- Enrollment matching → Student preferences: stores preferences (evidence: `backend/app/routers/enroll.py`)
- Student and tutor records → Tutor subjects: manages subjects (evidence: `backend/app/routers/crud.py`)
- Monthly roster approval → API schemas: validates responses (evidence: `backend/app/routers/rosters.py`)
- Lesson generation and changes → API schemas: validates responses (evidence: `backend/app/routers/lessons.py`)
- Student and tutor records → Education records: queries records (evidence: `backend/app/routers/crud.py`)
- Enrollment matching → Education records: creates pairings (evidence: `backend/app/routers/enroll.py`)
- Staff enrollment → Salary records: uses salary records (evidence: `backend/app/routers/staff_enroll.py`)
- Staff salary → Salary records: queries salaries (evidence: `backend/app/routers/salary.py`)
- Attendance tracking → Education records: records attendance (evidence: `backend/app/routers/attendance.py`)
- Student payments → Education records: records payments (evidence: `backend/app/routers/payments.py`)
- Group management → Education records: manages groups (evidence: `backend/app/routers/groups.py`)
- Monthly roster approval → Education records: stores rosters (evidence: `backend/app/routers/rosters.py`)
- Lesson generation and changes → Education records: stores lessons (evidence: `backend/app/routers/lessons.py`)
- Login and identity → Education records: queries users (evidence: `backend/app/routers/auth.py`)
- Education records → Database sessions: uses base (evidence: `backend/app/models.py`)
- Salary records → Database sessions: uses base (evidence: `backend/app/models_salary.py`)
- Student preferences → Database sessions: uses base (evidence: `backend/app/models_student_pref.py`)
- Tutor subjects → Database sessions: uses base (evidence: `backend/app/models_tutor_subjects.py`)
- Database sessions → PostgreSQL: connects (evidence: `backend/app/database.py`)
