# albiehao/ischool architecture

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

- Interactive diagram: https://gitdiagram.com/albiehao/ischool
- Repository: https://github.com/albiehao/ischool
- Video tour (about a minute): https://gitdiagram.com/albiehao/ischool/video

## Overview

iSchool is a self-hosted learning platform spanning a Vue web client, FastAPI service, and native iOS study timer. Learners organize courses and chapters, consume video, and record progress; daily tasks, focus sessions, schedules, review, notes, vocabulary, plans, and analytics support the broader study workflow. Media sources are normalized to unified paths across local, WebDAV/AList, and course plugins. The sampled code confirms application routing, local-storage management, course-group UI calls, gaze tracking, and iOS API requests; other domain links are shown only at subsystem level based on the README and tree.

Main entry points: [`backend/app/api/v1`](https://github.com/albiehao/ischool/tree/main/backend/app/api/v1) (API routes), [`backend/app/models`](https://github.com/albiehao/ischool/tree/main/backend/app/models) (Domain records), [`backend/app/api/v1/tasks.py`](https://github.com/albiehao/ischool/blob/main/backend/app/api/v1/tasks.py) (Study planning), [`backend/app/main.py`](https://github.com/albiehao/ischool/blob/main/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Learning clients"]
  node_webapp["Web application<br/>[App.vue]"]
  node_webviews["Learning pages"]
  node_webapis["Web API clients"]
  node_iosapp["iOS timer<br/>[RootView.swift]"]
  node_iosclient["iOS API client<br/>[APIClient.swift]"]
end

subgraph group_api["API boundary"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_routes["API routes"]
end

subgraph group_learning["Learning domains"]
  node_courses["Courses and progress<br/>[courses.py]"]
  node_study["Study planning<br/>[tasks.py]"]
  node_studyextras["Study extras<br/>[study_extras.py]"]
  node_analytics["Learning analytics"]
end

subgraph group_media["Media sources"]
  node_media["Playback and scanning"]
  node_storage["Unified storage<br/>[storage_service.py]"]
  node_webdav["WebDAV sources<br/>[webdav_service.py]"]
  node_plugins["Course plugins"]
end

subgraph group_platform["Platform services"]
  node_auth["Identity and access<br/>[auth.py]"]
  node_services["Domain services"]
  node_models["Domain records"]
  node_database[("Database<br/>[database.py]")]
end

node_learner(("Learner"))
node_external(("Media platforms"))

node_learner -->|"uses"| node_webapp
node_webapp -->|"renders"| node_webviews
node_webviews -->|"requests"| node_webapis
node_webapis -->|"HTTP calls"| node_fastapi
node_learner -->|"uses"| node_iosapp
node_iosapp -->|"requests data"| node_iosclient
node_iosclient -->|"HTTP calls"| node_fastapi
node_fastapi -->|"mounts routes"| node_routes
node_routes -->|"checks access"| node_auth
node_routes -->|"dispatches"| node_courses
node_routes -->|"dispatches"| node_study
node_routes -->|"dispatches"| node_studyextras
node_routes -->|"dispatches"| node_media
node_routes -->|"manages sources"| node_storage
node_routes -->|"manages mounts"| node_webdav
node_routes -->|"manages plugins"| node_plugins
node_routes -->|"dispatches"| node_services
node_services -->|"reads and writes"| node_models
node_courses -->|"reads and writes"| node_models
node_study -->|"reads and writes"| node_models
node_studyextras -->|"reads and writes"| node_models
node_analytics -->|"reads records"| node_models
node_models -->|"persists in"| node_database
node_storage -->|"queries sources"| node_models
node_webdav -.->|"mounts from"| node_external
node_plugins -.->|"integrates platforms"| node_external
node_media -->|"resolves paths"| node_storage
node_study -->|"summarizes activity"| node_analytics

click node_webapp "https://github.com/albiehao/ischool/blob/main/frontend/src/App.vue"
click node_webviews "https://github.com/albiehao/ischool/tree/main/frontend/src/views"
click node_webapis "https://github.com/albiehao/ischool/tree/main/frontend/src/api"
click node_iosapp "https://github.com/albiehao/ischool/blob/main/ios/iSchoolTimer/RootView.swift"
click node_iosclient "https://github.com/albiehao/ischool/blob/main/ios/iSchoolTimer/APIClient.swift"
click node_fastapi "https://github.com/albiehao/ischool/blob/main/backend/app/main.py"
click node_routes "https://github.com/albiehao/ischool/tree/main/backend/app/api/v1"
click node_courses "https://github.com/albiehao/ischool/blob/main/backend/app/api/v1/courses.py"
click node_study "https://github.com/albiehao/ischool/blob/main/backend/app/api/v1/tasks.py"
click node_studyextras "https://github.com/albiehao/ischool/blob/main/backend/app/api/v1/study_extras.py"
click node_analytics "https://github.com/albiehao/ischool/blob/main/backend/app/services/learning_analytics_service.py"
click node_media "https://github.com/albiehao/ischool/tree/main/backend/app/services"
click node_storage "https://github.com/albiehao/ischool/blob/main/backend/app/services/storage_service.py"
click node_webdav "https://github.com/albiehao/ischool/blob/main/backend/app/services/webdav_service.py"
click node_plugins "https://github.com/albiehao/ischool/tree/main/backend/app/plugins"
click node_auth "https://github.com/albiehao/ischool/blob/main/backend/app/core/auth.py"
click node_services "https://github.com/albiehao/ischool/tree/main/backend/app/services"
click node_models "https://github.com/albiehao/ischool/tree/main/backend/app/models"
click node_database "https://github.com/albiehao/ischool/blob/main/backend/app/core/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_webapp,node_webviews,node_webapis,node_iosapp,node_iosclient toneBlue
class node_fastapi,node_routes toneAmber
class node_courses,node_study,node_studyextras,node_analytics toneMint
class node_media,node_storage,node_webdav,node_plugins toneRose
class node_auth,node_services,node_models,node_database,node_learner,node_external toneIndigo
```

## Components

### Learning clients

- [Web application](https://github.com/albiehao/ischool/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Learning pages](https://github.com/albiehao/ischool/tree/main/frontend/src/views): `frontend/src/views`
- [Web API clients](https://github.com/albiehao/ischool/tree/main/frontend/src/api): `frontend/src/api`
- [iOS timer](https://github.com/albiehao/ischool/blob/main/ios/iSchoolTimer/RootView.swift): `ios/iSchoolTimer/RootView.swift`
- [iOS API client](https://github.com/albiehao/ischool/blob/main/ios/iSchoolTimer/APIClient.swift): `ios/iSchoolTimer/APIClient.swift`

### API boundary

- [FastAPI app](https://github.com/albiehao/ischool/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/albiehao/ischool/tree/main/backend/app/api/v1): `backend/app/api/v1`

### Learning domains

- [Courses and progress](https://github.com/albiehao/ischool/blob/main/backend/app/api/v1/courses.py): `backend/app/api/v1/courses.py`
- [Study planning](https://github.com/albiehao/ischool/blob/main/backend/app/api/v1/tasks.py): `backend/app/api/v1/tasks.py`
- [Study extras](https://github.com/albiehao/ischool/blob/main/backend/app/api/v1/study_extras.py): `backend/app/api/v1/study_extras.py`
- [Learning analytics](https://github.com/albiehao/ischool/blob/main/backend/app/services/learning_analytics_service.py): `backend/app/services/learning_analytics_service.py`

### Media sources

- [Playback and scanning](https://github.com/albiehao/ischool/tree/main/backend/app/services): `backend/app/services`
- [Unified storage](https://github.com/albiehao/ischool/blob/main/backend/app/services/storage_service.py): `backend/app/services/storage_service.py`
- [WebDAV sources](https://github.com/albiehao/ischool/blob/main/backend/app/services/webdav_service.py): `backend/app/services/webdav_service.py`
- [Course plugins](https://github.com/albiehao/ischool/tree/main/backend/app/plugins): `backend/app/plugins`

### Platform services

- [Identity and access](https://github.com/albiehao/ischool/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`
- [Domain services](https://github.com/albiehao/ischool/tree/main/backend/app/services): `backend/app/services`
- [Domain records](https://github.com/albiehao/ischool/tree/main/backend/app/models): `backend/app/models`
- [Database](https://github.com/albiehao/ischool/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Learner**
- **Media platforms**

## Connections

- Learner → Web application: uses
- Web application → Learning pages: renders
- Learning pages → Web API clients: requests
- Web API clients → FastAPI app: HTTP calls
- Learner → iOS timer: uses
- iOS timer → iOS API client: requests data
- iOS API client → FastAPI app: HTTP calls
- FastAPI app → API routes: mounts routes
- API routes → Identity and access: checks access
- API routes → Courses and progress: dispatches
- API routes → Study planning: dispatches
- API routes → Study extras: dispatches
- API routes → Playback and scanning: dispatches
- API routes → Unified storage: manages sources
- API routes → WebDAV sources: manages mounts
- API routes → Course plugins: manages plugins
- API routes → Domain services: dispatches
- Domain services → Domain records: reads and writes
- Courses and progress → Domain records: reads and writes
- Study planning → Domain records: reads and writes
- Study extras → Domain records: reads and writes
- Learning analytics → Domain records: reads records
- Domain records → Database: persists in
- Unified storage → Domain records: queries sources
- WebDAV sources → Media platforms: mounts from
- Course plugins → Media platforms: integrates platforms
- Playback and scanning → Unified storage: resolves paths
- Study planning → Learning analytics: summarizes activity