# timwonderer/classroom-token-hub architecture

> Architecture diagram of the GitHub repository timwonderer/classroom-token-hub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timwonderer/classroom-token-hub
- Repository: https://github.com/timwonderer/classroom-token-hub
- Video tour (about a minute): https://gitdiagram.com/timwonderer/classroom-token-hub/video

## Overview

Classroom Token Hub is a multi-tenant classroom management platform built around a simulated token economy. Teachers configure classes and features, then manage attendance, payroll, store purchases, rent, insurance, and student issues; students use a portal to participate, transact, and request help. Ledger effects begin pending and scheduled settlement admits them to immutable posted history. The graph reflects documented product stages and major capabilities; several route-to-domain links are inferred from the product description because the sampled route and feature source was incomplete.

Main entry points: [`app/routes/admin.py`](https://github.com/timwonderer/classroom-token-hub/blob/main/app/routes/admin.py) (Teacher portal), [`app/routes/student.py`](https://github.com/timwonderer/classroom-token-hub/blob/main/app/routes/student.py) (Student portal), [`app/services/ledger_command_service.py`](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/ledger_command_service.py) (Ledger services), [`app/services/obligations_service.py`](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/obligations_service.py) (Rent obligations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["User surfaces"]
  node_teacher_ui["Teacher portal<br/>[admin.py]"]
  node_student_ui["Student portal<br/>[student.py]"]
  node_admin_ui["Admin portal<br/>[system_admin.py]"]
end

subgraph group_domain["Classroom operations"]
  node_class_setup["Class configuration"]
  node_attendance["Attendance"]
  node_payroll["Payroll"]
  node_store["Classroom store<br/>[store_service.py]"]
  node_obligations["Rent obligations"]
  node_insurance["Insurance"]
  node_recovery["Account recovery"]
  node_issues["Issue handling<br/>[issue_service.py]"]
end

subgraph group_economy["Economic services"]
  node_engine["Economic engine<br/>[economic_engine.py]"]
  node_ledger["Ledger services"]
  node_interpretation["Cycle interpretation<br/>[read_service.py]"]
end

subgraph group_platform["Platform runtime"]
  node_database[("PostgreSQL state<br/>[models.py]")]
  node_scheduler["Scheduled jobs<br/>[scheduled_tasks.py]"]
end

node_teacher(("Teacher"))
node_student(("Student"))
node_admin(("System admin"))

node_teacher -->|"uses"| node_teacher_ui
node_student -->|"uses"| node_student_ui
node_admin -->|"uses"| node_admin_ui
node_teacher_ui -->|"configures"| node_class_setup
node_teacher_ui -->|"manages"| node_attendance
node_teacher_ui -->|"runs"| node_payroll
node_teacher_ui -->|"manages"| node_store
node_teacher_ui -->|"reconciles"| node_obligations
node_teacher_ui -->|"manages"| node_insurance
node_student_ui -->|"records"| node_attendance
node_student_ui -->|"purchases"| node_store
node_student_ui -->|"views"| node_obligations
node_student_ui -->|"claims"| node_insurance
node_student_ui -->|"requests"| node_recovery
node_student_ui -->|"reports"| node_issues
node_class_setup -->|"evolves policy"| node_engine
node_engine -->|"reads and versions"| node_database
node_attendance -->|"records sessions"| node_database
node_payroll -->|"posts pay"| node_ledger
node_store -->|"records purchases"| node_ledger
node_obligations -->|"records dues"| node_ledger
node_insurance -->|"checks premiums"| node_obligations
node_ledger -->|"writes pending entries"| node_database
node_scheduler -->|"settles entries"| node_ledger
node_scheduler -->|"runs cycles"| node_payroll
node_scheduler -->|"reconciles rent"| node_obligations
node_interpretation -->|"reads history"| node_ledger
node_interpretation -->|"corroborates events"| node_payroll
node_interpretation -->|"reads cycle facts"| node_database
node_admin_ui -->|"reviews accounts"| node_database

click node_teacher_ui "https://github.com/timwonderer/classroom-token-hub/blob/main/app/routes/admin.py"
click node_student_ui "https://github.com/timwonderer/classroom-token-hub/blob/main/app/routes/student.py"
click node_admin_ui "https://github.com/timwonderer/classroom-token-hub/blob/main/app/routes/system_admin.py"
click node_class_setup "https://github.com/timwonderer/classroom-token-hub/tree/main/app/feats/class_configuration"
click node_attendance "https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/attendance_service.py"
click node_payroll "https://github.com/timwonderer/classroom-token-hub/tree/main/app/services/payroll"
click node_store "https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/store_service.py"
click node_obligations "https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/obligations_service.py"
click node_insurance "https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/insurance_claim_service.py"
click node_recovery "https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/recovery_service.py"
click node_issues "https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/issue_service.py"
click node_engine "https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/economic_engine.py"
click node_ledger "https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/ledger_command_service.py"
click node_interpretation "https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/interpretation/read_service.py"
click node_database "https://github.com/timwonderer/classroom-token-hub/blob/main/app/models.py"
click node_scheduler "https://github.com/timwonderer/classroom-token-hub/blob/main/app/scheduled_tasks.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_teacher_ui,node_student_ui,node_admin_ui toneBlue
class node_class_setup,node_attendance,node_payroll,node_store,node_obligations,node_insurance,node_recovery,node_issues toneAmber
class node_engine,node_ledger,node_interpretation toneMint
class node_database,node_scheduler toneRose
class node_teacher,node_student,node_admin toneIndigo
```

## Components

### User surfaces

- [Teacher portal](https://github.com/timwonderer/classroom-token-hub/blob/main/app/routes/admin.py): `app/routes/admin.py`
- [Student portal](https://github.com/timwonderer/classroom-token-hub/blob/main/app/routes/student.py): `app/routes/student.py`
- [Admin portal](https://github.com/timwonderer/classroom-token-hub/blob/main/app/routes/system_admin.py): `app/routes/system_admin.py`

### Classroom operations

- [Class configuration](https://github.com/timwonderer/classroom-token-hub/tree/main/app/feats/class_configuration): `app/feats/class_configuration`
- [Attendance](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/attendance_service.py): `app/services/attendance_service.py`
- [Payroll](https://github.com/timwonderer/classroom-token-hub/tree/main/app/services/payroll): `app/services/payroll`
- [Classroom store](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/store_service.py): `app/services/store_service.py`
- [Rent obligations](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/obligations_service.py): `app/services/obligations_service.py`
- [Insurance](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/insurance_claim_service.py): `app/services/insurance_claim_service.py`
- [Account recovery](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/recovery_service.py): `app/services/recovery_service.py`
- [Issue handling](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/issue_service.py): `app/services/issue_service.py`

### Economic services

- [Economic engine](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/economic_engine.py): `app/services/economic_engine.py`
- [Ledger services](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/ledger_command_service.py): `app/services/ledger_command_service.py`
- [Cycle interpretation](https://github.com/timwonderer/classroom-token-hub/blob/main/app/services/interpretation/read_service.py): `app/services/interpretation/read_service.py`

### Platform runtime

- [PostgreSQL state](https://github.com/timwonderer/classroom-token-hub/blob/main/app/models.py): `app/models.py`
- [Scheduled jobs](https://github.com/timwonderer/classroom-token-hub/blob/main/app/scheduled_tasks.py): `app/scheduled_tasks.py`

### Other components

- **Teacher**
- **Student**
- **System admin**

## Connections

- Teacher → Teacher portal: uses
- Student → Student portal: uses
- System admin → Admin portal: uses
- Teacher portal → Class configuration: configures
- Teacher portal → Attendance: manages
- Teacher portal → Payroll: runs
- Teacher portal → Classroom store: manages
- Teacher portal → Rent obligations: reconciles
- Teacher portal → Insurance: manages
- Student portal → Attendance: records
- Student portal → Classroom store: purchases
- Student portal → Rent obligations: views
- Student portal → Insurance: claims
- Student portal → Account recovery: requests
- Student portal → Issue handling: reports
- Class configuration → Economic engine: evolves policy
- Economic engine → PostgreSQL state: reads and versions
- Attendance → PostgreSQL state: records sessions
- Payroll → Ledger services: posts pay
- Classroom store → Ledger services: records purchases
- Rent obligations → Ledger services: records dues
- Insurance → Rent obligations: checks premiums
- Ledger services → PostgreSQL state: writes pending entries
- Scheduled jobs → Ledger services: settles entries
- Scheduled jobs → Payroll: runs cycles
- Scheduled jobs → Rent obligations: reconciles rent
- Cycle interpretation → Ledger services: reads history
- Cycle interpretation → Payroll: corroborates events
- Cycle interpretation → PostgreSQL state: reads cycle facts
- Admin portal → PostgreSQL state: reviews accounts