# 25ghost/superteacher architecture

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

- Interactive diagram: https://gitdiagram.com/25ghost/superteacher
- Repository: https://github.com/25ghost/superteacher

## Overview

SuperTeacher API is a FastAPI backend whose documented core is student registration, catalog selection, and enrollment; it also supports authentication and broader tutoring/learning features. A typical request enters through the versioned API, is authenticated where required, runs through a domain service, and uses repositories and SQLAlchemy models for persisted state. The README documents account, session, and recovery behavior; the source index and excerpts support selected learning flows. Many tutoring, classroom, and administration endpoints are present in the tree but were not sampled, so their internal connections are not inferred.

Main entry points: [`app/core/database.py`](https://github.com/25ghost/superteacher/blob/main/app/core/database.py) (SQL database), [`app/services/auth_service.py`](https://github.com/25ghost/superteacher/blob/main/app/services/auth_service.py) (Accounts and sessions), [`app/api/v1/router.py`](https://github.com/25ghost/superteacher/blob/main/app/api/v1/router.py) (Versioned API router), [`app/services/learning_enrollment_service.py`](https://github.com/25ghost/superteacher/blob/main/app/services/learning_enrollment_service.py) (Learning enrollment rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_router["Versioned API router<br/>[router.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_auth_guard["Identity and role guards"]
end

subgraph group_registration["Registration and catalog"]
  node_registration_routes["Registration endpoints<br/>[registrations.py]"]
  node_catalog_routes["Catalog endpoints<br/>[catalog.py]"]
  node_student_service["Student profiles<br/>[student_service.py]"]
  node_registration_service["Enrollment workflow"]
  node_reference_data["Education catalog data"]
  node_student_model["Student profile model<br/>[student.py]"]
  node_profile_schema["Student profile schema<br/>[student_profile.py]"]
  node_program_version["Program version model<br/>[program_version.py]"]
end

subgraph group_learning["Tutoring and learning"]
  node_learning_routes["Learning enrollment API"]
  node_learning_service["Learning enrollment rules"]
  node_context_service["Learning context resolution"]
  node_learning_repo["Learning enrollment storage"]
  node_offering_service["Teaching offerings"]
  node_content["Learning content and books"]
  node_classroom["Live classroom<br/>[classroom_ws.py]"]
  node_teacher_verification["Teacher verification"]
end

subgraph group_authdata["Authentication state"]
  node_auth_service["Accounts and sessions<br/>[auth_service.py]"]
  node_auth_session_repo["Session repository"]
  node_auth_event_repo["Audit events"]
  node_user_model["User identity model<br/>[user.py]"]
end

subgraph group_platform["Shared platform"]
  node_database[("SQL database<br/>[database.py]")]
  node_config["Runtime configuration<br/>[config.py]"]
  node_security["Token security<br/>[security.py]"]
  node_enums["Domain states<br/>[enums.py]"]
  node_tags["API tags<br/>[tags.py]"]
  node_logging["Application logging<br/>[logging.py]"]
  node_time_mixin["Timestamp fields<br/>[time_mixin.py]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_router
node_router -->|"routes to"| node_auth_routes
node_router -->|"routes to"| node_registration_routes
node_router -->|"routes to"| node_catalog_routes
node_router -->|"routes to"| node_learning_routes
node_auth_routes -->|"calls"| node_auth_service
node_auth_routes -->|"uses guards"| node_auth_guard
node_auth_service -->|"manages sessions"| node_auth_session_repo
node_auth_service -->|"records events"| node_auth_event_repo
node_auth_service -->|"uses identity"| node_user_model
node_auth_service -->|"loads profile"| node_student_model
node_auth_service -->|"creates tokens"| node_security
node_auth_guard -->|"decodes tokens"| node_security
node_auth_guard -->|"checks session"| node_auth_session_repo
node_registration_routes -.->|"uses profiles"| node_student_service
node_registration_routes -.->|"runs registration"| node_registration_service
node_catalog_routes -.->|"serves catalog"| node_reference_data
node_student_service -->|"manages profile"| node_student_model
node_student_service -->|"builds responses"| node_profile_schema
node_registration_service -.->|"persists enrollment"| node_database
node_learning_routes -->|"calls"| node_learning_service
node_learning_service -->|"creates enrollment"| node_learning_repo
node_learning_service -->|"resolves context"| node_context_service
node_learning_service -->|"checks offering"| node_offering_service
node_learning_repo -.->|"reads and writes"| node_database
node_context_service -->|"validates version"| node_program_version
node_auth_guard -->|"loads account"| node_user_model
node_auth_session_repo -.->|"stores sessions"| node_database
node_auth_event_repo -.->|"stores audit"| node_database
node_database -->|"reads settings"| node_config
node_user_model -->|"maps table"| node_database
node_student_model -->|"maps table"| node_database
node_program_version -->|"maps table"| node_database
node_learning_service -->|"uses states"| node_enums

click node_router "https://github.com/25ghost/superteacher/blob/main/app/api/v1/router.py"
click node_auth_routes "https://github.com/25ghost/superteacher/blob/main/app/api/v1/endpoints/auth.py"
click node_auth_guard "https://github.com/25ghost/superteacher/blob/main/app/core/auth_dependencies.py"
click node_registration_routes "https://github.com/25ghost/superteacher/blob/main/app/api/v1/endpoints/registrations.py"
click node_catalog_routes "https://github.com/25ghost/superteacher/blob/main/app/api/v1/endpoints/catalog.py"
click node_student_service "https://github.com/25ghost/superteacher/blob/main/app/services/student_service.py"
click node_registration_service "https://github.com/25ghost/superteacher/blob/main/app/services/registration_service.py"
click node_reference_data "https://github.com/25ghost/superteacher/tree/main/app/data"
click node_auth_service "https://github.com/25ghost/superteacher/blob/main/app/services/auth_service.py"
click node_auth_session_repo "https://github.com/25ghost/superteacher/blob/main/app/repositories/auth_session_repository.py"
click node_auth_event_repo "https://github.com/25ghost/superteacher/blob/main/app/repositories/auth_event_repository.py"
click node_user_model "https://github.com/25ghost/superteacher/blob/main/app/models/user.py"
click node_student_model "https://github.com/25ghost/superteacher/blob/main/app/models/student.py"
click node_profile_schema "https://github.com/25ghost/superteacher/blob/main/app/schemas/student_profile.py"
click node_learning_routes "https://github.com/25ghost/superteacher/blob/main/app/api/v1/endpoints/learning_enrollments.py"
click node_learning_service "https://github.com/25ghost/superteacher/blob/main/app/services/learning_enrollment_service.py"
click node_context_service "https://github.com/25ghost/superteacher/blob/main/app/services/learning_context_service.py"
click node_learning_repo "https://github.com/25ghost/superteacher/blob/main/app/repositories/learning_enrollment_repository.py"
click node_offering_service "https://github.com/25ghost/superteacher/blob/main/app/services/teaching_offering_service.py"
click node_content "https://github.com/25ghost/superteacher/blob/main/app/services/student_content_service.py"
click node_classroom "https://github.com/25ghost/superteacher/blob/main/app/api/v1/endpoints/classroom_ws.py"
click node_teacher_verification "https://github.com/25ghost/superteacher/blob/main/app/services/teacher_verification_service.py"
click node_database "https://github.com/25ghost/superteacher/blob/main/app/core/database.py"
click node_config "https://github.com/25ghost/superteacher/blob/main/app/core/config.py"
click node_security "https://github.com/25ghost/superteacher/blob/main/app/core/security.py"
click node_enums "https://github.com/25ghost/superteacher/blob/main/app/models/enums.py"
click node_program_version "https://github.com/25ghost/superteacher/blob/main/app/models/program_version.py"
click node_tags "https://github.com/25ghost/superteacher/blob/main/app/api/v1/tags.py"
click node_logging "https://github.com/25ghost/superteacher/blob/main/app/core/logging.py"
click node_time_mixin "https://github.com/25ghost/superteacher/blob/main/app/core/time_mixin.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_router,node_auth_routes,node_auth_guard,node_client toneBlue
class node_registration_routes,node_catalog_routes,node_student_service,node_registration_service,node_reference_data,node_student_model,node_profile_schema,node_program_version toneAmber
class node_learning_routes,node_learning_service,node_context_service,node_learning_repo,node_offering_service,node_content,node_classroom,node_teacher_verification toneMint
class node_auth_service,node_auth_session_repo,node_auth_event_repo,node_user_model toneRose
class node_database,node_config,node_security,node_enums,node_tags,node_logging,node_time_mixin toneIndigo
```

## Components

### API and identity

- [Versioned API router](https://github.com/25ghost/superteacher/blob/main/app/api/v1/router.py): `app/api/v1/router.py`
- [Authentication routes](https://github.com/25ghost/superteacher/blob/main/app/api/v1/endpoints/auth.py): `app/api/v1/endpoints/auth.py`
- [Identity and role guards](https://github.com/25ghost/superteacher/blob/main/app/core/auth_dependencies.py): `app/core/auth_dependencies.py`

### Registration and catalog

- [Registration endpoints](https://github.com/25ghost/superteacher/blob/main/app/api/v1/endpoints/registrations.py): `app/api/v1/endpoints/registrations.py`
- [Catalog endpoints](https://github.com/25ghost/superteacher/blob/main/app/api/v1/endpoints/catalog.py): `app/api/v1/endpoints/catalog.py`
- [Student profiles](https://github.com/25ghost/superteacher/blob/main/app/services/student_service.py): `app/services/student_service.py`
- [Enrollment workflow](https://github.com/25ghost/superteacher/blob/main/app/services/registration_service.py): `app/services/registration_service.py`
- [Education catalog data](https://github.com/25ghost/superteacher/tree/main/app/data): `app/data`
- [Student profile model](https://github.com/25ghost/superteacher/blob/main/app/models/student.py): `app/models/student.py`
- [Student profile schema](https://github.com/25ghost/superteacher/blob/main/app/schemas/student_profile.py): `app/schemas/student_profile.py`
- [Program version model](https://github.com/25ghost/superteacher/blob/main/app/models/program_version.py): `app/models/program_version.py`

### Tutoring and learning

- [Learning enrollment API](https://github.com/25ghost/superteacher/blob/main/app/api/v1/endpoints/learning_enrollments.py): `app/api/v1/endpoints/learning_enrollments.py`
- [Learning enrollment rules](https://github.com/25ghost/superteacher/blob/main/app/services/learning_enrollment_service.py): `app/services/learning_enrollment_service.py`
- [Learning context resolution](https://github.com/25ghost/superteacher/blob/main/app/services/learning_context_service.py): `app/services/learning_context_service.py`
- [Learning enrollment storage](https://github.com/25ghost/superteacher/blob/main/app/repositories/learning_enrollment_repository.py): `app/repositories/learning_enrollment_repository.py`
- [Teaching offerings](https://github.com/25ghost/superteacher/blob/main/app/services/teaching_offering_service.py): `app/services/teaching_offering_service.py`
- [Learning content and books](https://github.com/25ghost/superteacher/blob/main/app/services/student_content_service.py): `app/services/student_content_service.py`
- [Live classroom](https://github.com/25ghost/superteacher/blob/main/app/api/v1/endpoints/classroom_ws.py): `app/api/v1/endpoints/classroom_ws.py`
- [Teacher verification](https://github.com/25ghost/superteacher/blob/main/app/services/teacher_verification_service.py): `app/services/teacher_verification_service.py`

### Authentication state

- [Accounts and sessions](https://github.com/25ghost/superteacher/blob/main/app/services/auth_service.py): `app/services/auth_service.py`
- [Session repository](https://github.com/25ghost/superteacher/blob/main/app/repositories/auth_session_repository.py): `app/repositories/auth_session_repository.py`
- [Audit events](https://github.com/25ghost/superteacher/blob/main/app/repositories/auth_event_repository.py): `app/repositories/auth_event_repository.py`
- [User identity model](https://github.com/25ghost/superteacher/blob/main/app/models/user.py): `app/models/user.py`

### Shared platform

- [SQL database](https://github.com/25ghost/superteacher/blob/main/app/core/database.py): `app/core/database.py`
- [Runtime configuration](https://github.com/25ghost/superteacher/blob/main/app/core/config.py): `app/core/config.py`
- [Token security](https://github.com/25ghost/superteacher/blob/main/app/core/security.py): `app/core/security.py`
- [Domain states](https://github.com/25ghost/superteacher/blob/main/app/models/enums.py): `app/models/enums.py`
- [API tags](https://github.com/25ghost/superteacher/blob/main/app/api/v1/tags.py): `app/api/v1/tags.py`
- [Application logging](https://github.com/25ghost/superteacher/blob/main/app/core/logging.py): `app/core/logging.py`
- [Timestamp fields](https://github.com/25ghost/superteacher/blob/main/app/core/time_mixin.py): `app/core/time_mixin.py`

### Other components

- **API client**

## Connections

- API client → Versioned API router: sends requests (evidence: `app/api/v1/router.py`)
- Versioned API router → Authentication routes: routes to (evidence: `app/api/v1/router.py`)
- Versioned API router → Registration endpoints: routes to (evidence: `app/api/v1/router.py`)
- Versioned API router → Catalog endpoints: routes to (evidence: `app/api/v1/router.py`)
- Versioned API router → Learning enrollment API: routes to (evidence: `app/api/v1/router.py`)
- Authentication routes → Accounts and sessions: calls (evidence: `app/api/v1/endpoints/auth.py`)
- Authentication routes → Identity and role guards: uses guards (evidence: `app/api/v1/endpoints/auth.py`)
- Accounts and sessions → Session repository: manages sessions (evidence: `app/services/auth_service.py`)
- Accounts and sessions → Audit events: records events (evidence: `app/services/auth_service.py`)
- Accounts and sessions → User identity model: uses identity (evidence: `app/services/auth_service.py`)
- Accounts and sessions → Student profile model: loads profile (evidence: `app/services/auth_service.py`)
- Accounts and sessions → Token security: creates tokens (evidence: `app/services/auth_service.py`)
- Identity and role guards → Token security: decodes tokens (evidence: `app/core/auth_dependencies.py`)
- Identity and role guards → Session repository: checks session (evidence: `app/core/auth_dependencies.py`)
- Registration endpoints → Student profiles: uses profiles
- Registration endpoints → Enrollment workflow: runs registration
- Catalog endpoints → Education catalog data: serves catalog
- Student profiles → Student profile model: manages profile (evidence: `app/services/student_service.py`)
- Student profiles → Student profile schema: builds responses (evidence: `app/services/student_service.py`)
- Enrollment workflow → SQL database: persists enrollment
- Learning enrollment API → Learning enrollment rules: calls (evidence: `app/api/v1/endpoints/learning_enrollments.py`)
- Learning enrollment rules → Learning enrollment storage: creates enrollment (evidence: `app/services/learning_enrollment_service.py`)
- Learning enrollment rules → Learning context resolution: resolves context (evidence: `app/services/learning_enrollment_service.py`)
- Learning enrollment rules → Teaching offerings: checks offering (evidence: `app/services/learning_enrollment_service.py`)
- Learning enrollment storage → SQL database: reads and writes
- Learning context resolution → Program version model: validates version (evidence: `app/services/learning_context_service.py`)
- Identity and role guards → User identity model: loads account (evidence: `app/core/auth_dependencies.py`)
- Session repository → SQL database: stores sessions
- Audit events → SQL database: stores audit
- SQL database → Runtime configuration: reads settings (evidence: `app/core/database.py`)
- User identity model → SQL database: maps table (evidence: `app/models/user.py`)
- Student profile model → SQL database: maps table (evidence: `app/models/student.py`)
- Program version model → SQL database: maps table (evidence: `app/models/program_version.py`)
- Learning enrollment rules → Domain states: uses states (evidence: `app/services/learning_enrollment_service.py`)
