# kirsh1/ustc-timetable architecture

> Architecture diagram of the GitHub repository kirsh1/ustc-timetable, 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/kirsh1/ustc-timetable
- Repository: https://github.com/kirsh1/ustc-timetable
- Video tour (about a minute): https://gitdiagram.com/kirsh1/ustc-timetable/video

## Overview

USTC Timetable is an Android app for importing a student’s school timetable and browsing it locally, with manual schedule items, semester/profile management, and sync. Its principal path is school sign-in, session capture, portal retrieval and parsing, normalized timetable data, then local persistence and weekly display. The README also documents appearance customization and background/manual sync. Source excerpts show the sync engine, session handling, repositories, and database; some UI and import wiring is represented only at the documented subsystem level, so uncertain links are omitted.

Main entry points: [`app/src/main/java/com/ustc/timetable/sync/SyncEngine.kt`](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/sync/SyncEngine.kt) (Sync engine), [`app/src/main/java/com/ustc/timetable/semester/ImportFlowViewModel.kt`](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/semester/ImportFlowViewModel.kt) (Semester import), [`app/src/main/java/com/ustc/timetable/school/ustc/auth/UstcSessionManager.kt`](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/auth/UstcSessionManager.kt) (Session manager), [`app/src/main/java/com/ustc/timetable/school/ustc/portal/UstcHttpPortalSource.kt`](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/portal/UstcHttpPortalSource.kt) (Portal source)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_main["Main activity<br/>[MainActivity.kt]"]
  node_root["App navigation<br/>[AppRoot.kt]"]
  node_firstlaunch["First launch"]
  node_timetableui["Weekly timetable<br/>[TimetableScreen.kt]"]
  node_layout["Timetable layout"]
  node_manualui["Manual item editor"]
end

subgraph group_portal["Portal access"]
  node_login["WebView sign-in"]
  node_completion["Login completion"]
  node_session["Session manager"]
  node_sessionstore["Encrypted session store<br/>[SessionStore.kt]"]
  node_portalclient["Portal source"]
  node_parsers["Portal parsers"]
  node_normalizer["Snapshot normalizer"]
end

subgraph group_schedule["Schedule data"]
  node_importflow["Semester import"]
  node_repositories["Schedule repositories"]
  node_profiles["Schedule profiles"]
  node_database[("Local timetable database")]
end

subgraph group_sync["Synchronization"]
  node_syncengine["Sync engine<br/>[SyncEngine.kt]"]
  node_manualsync["Manual sync"]
  node_worker["Weekly sync worker"]
end

subgraph group_preferences["Preferences"]
  node_settings["App settings"]
  node_appearance["Theme and wallpaper<br/>[Appearance.kt]"]
end

node_student(("Student"))
node_keystore["Android Keystore"]
node_school{{"USTC portal"}}

node_student -->|"opens app"| node_main
node_main -->|"hosts navigation"| node_root
node_root -->|"shows onboarding"| node_firstlaunch
node_root -->|"shows schedule"| node_timetableui
node_student -->|"starts import"| node_firstlaunch
node_firstlaunch -->|"launches sign-in"| node_login
node_login -->|"signals login"| node_completion
node_completion -->|"captures session"| node_session
node_session -->|"verifies access"| node_portalclient
node_session -->|"saves session"| node_sessionstore
node_sessionstore -->|"encrypts with"| node_keystore
node_session -->|"probes portal"| node_school
node_importflow -->|"fetches pages"| node_portalclient
node_portalclient -->|"requests pages"| node_school
node_syncengine -->|"fetches pages"| node_portalclient
node_syncengine -->|"parses pages"| node_parsers
node_syncengine -->|"normalizes snapshot"| node_normalizer
node_syncengine -->|"applies snapshot"| node_database
node_importflow -->|"parses import"| node_parsers
node_importflow -->|"normalizes import"| node_normalizer
node_importflow -->|"saves semester"| node_repositories
node_manualsync -->|"runs sync"| node_syncengine
node_worker -->|"runs sync"| node_syncengine
node_timetableui -->|"observes schedule"| node_repositories
node_timetableui -->|"renders grid"| node_layout
node_manualui -->|"edits manual items"| node_repositories
node_repositories -->|"reads and writes"| node_database
node_profiles -->|"reads and writes"| node_database
node_settings -->|"edits profiles"| node_profiles
node_settings -->|"configures appearance"| node_appearance
node_main -->|"applies theme"| node_appearance

click node_main "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/MainActivity.kt"
click node_root "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/timetable/ui/AppRoot.kt"
click node_firstlaunch "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/timetable/ui/FirstLaunchViewModel.kt"
click node_timetableui "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/timetable/ui/TimetableScreen.kt"
click node_layout "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/timetable/layout/WeeklyTimetableGrid.kt"
click node_manualui "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/manual/ManualItemEditorViewModel.kt"
click node_login "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/auth/WebViewLoginActivity.kt"
click node_completion "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/auth/LoginCompletionCoordinator.kt"
click node_session "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/auth/UstcSessionManager.kt"
click node_sessionstore "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/auth/SessionStore.kt"
click node_portalclient "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/portal/UstcHttpPortalSource.kt"
click node_parsers "https://github.com/kirsh1/ustc-timetable/tree/main/app/src/main/java/com/ustc/timetable/school/ustc/parser"
click node_normalizer "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/parser/UstcSnapshotNormalizer.kt"
click node_importflow "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/semester/ImportFlowViewModel.kt"
click node_syncengine "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/sync/SyncEngine.kt"
click node_manualsync "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/sync/ManualSyncController.kt"
click node_worker "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/sync/WeeklySyncWorker.kt"
click node_repositories "https://github.com/kirsh1/ustc-timetable/tree/main/app/src/main/java/com/ustc/timetable/timetable/data"
click node_profiles "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/scheduleprofile/ScheduleProfileRepository.kt"
click node_database "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/timetable/data/db/TimetableDatabase.kt"
click node_settings "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/settings/SettingsViewModel.kt"
click node_appearance "https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/appearance/Appearance.kt"

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_main,node_root,node_firstlaunch,node_timetableui,node_layout,node_manualui toneBlue
class node_login,node_completion,node_session,node_sessionstore,node_portalclient,node_parsers,node_normalizer toneAmber
class node_importflow,node_repositories,node_profiles,node_database toneMint
class node_syncengine,node_manualsync,node_worker toneRose
class node_settings,node_appearance,node_student,node_keystore,node_school toneIndigo
```

## Components

### App experience

- [Main activity](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/MainActivity.kt): `app/src/main/java/com/ustc/timetable/MainActivity.kt`
- [App navigation](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/timetable/ui/AppRoot.kt): `app/src/main/java/com/ustc/timetable/timetable/ui/AppRoot.kt`
- [First launch](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/timetable/ui/FirstLaunchViewModel.kt): `app/src/main/java/com/ustc/timetable/timetable/ui/FirstLaunchViewModel.kt`
- [Weekly timetable](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/timetable/ui/TimetableScreen.kt): `app/src/main/java/com/ustc/timetable/timetable/ui/TimetableScreen.kt`
- [Timetable layout](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/timetable/layout/WeeklyTimetableGrid.kt): `app/src/main/java/com/ustc/timetable/timetable/layout/WeeklyTimetableGrid.kt`
- [Manual item editor](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/manual/ManualItemEditorViewModel.kt): `app/src/main/java/com/ustc/timetable/manual/ManualItemEditorViewModel.kt`

### Portal access

- [WebView sign-in](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/auth/WebViewLoginActivity.kt): `app/src/main/java/com/ustc/timetable/school/ustc/auth/WebViewLoginActivity.kt`
- [Login completion](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/auth/LoginCompletionCoordinator.kt): `app/src/main/java/com/ustc/timetable/school/ustc/auth/LoginCompletionCoordinator.kt`
- [Session manager](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/auth/UstcSessionManager.kt): `app/src/main/java/com/ustc/timetable/school/ustc/auth/UstcSessionManager.kt`
- [Encrypted session store](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/auth/SessionStore.kt): `app/src/main/java/com/ustc/timetable/school/ustc/auth/SessionStore.kt`
- [Portal source](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/portal/UstcHttpPortalSource.kt): `app/src/main/java/com/ustc/timetable/school/ustc/portal/UstcHttpPortalSource.kt`
- [Portal parsers](https://github.com/kirsh1/ustc-timetable/tree/main/app/src/main/java/com/ustc/timetable/school/ustc/parser): `app/src/main/java/com/ustc/timetable/school/ustc/parser`
- [Snapshot normalizer](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/school/ustc/parser/UstcSnapshotNormalizer.kt): `app/src/main/java/com/ustc/timetable/school/ustc/parser/UstcSnapshotNormalizer.kt`

### Schedule data

- [Semester import](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/semester/ImportFlowViewModel.kt): `app/src/main/java/com/ustc/timetable/semester/ImportFlowViewModel.kt`
- [Schedule repositories](https://github.com/kirsh1/ustc-timetable/tree/main/app/src/main/java/com/ustc/timetable/timetable/data): `app/src/main/java/com/ustc/timetable/timetable/data`
- [Schedule profiles](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/scheduleprofile/ScheduleProfileRepository.kt): `app/src/main/java/com/ustc/timetable/scheduleprofile/ScheduleProfileRepository.kt`
- [Local timetable database](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/timetable/data/db/TimetableDatabase.kt): `app/src/main/java/com/ustc/timetable/timetable/data/db/TimetableDatabase.kt`

### Synchronization

- [Sync engine](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/sync/SyncEngine.kt): `app/src/main/java/com/ustc/timetable/sync/SyncEngine.kt`
- [Manual sync](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/sync/ManualSyncController.kt): `app/src/main/java/com/ustc/timetable/sync/ManualSyncController.kt`
- [Weekly sync worker](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/sync/WeeklySyncWorker.kt): `app/src/main/java/com/ustc/timetable/sync/WeeklySyncWorker.kt`

### Preferences

- [App settings](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/settings/SettingsViewModel.kt): `app/src/main/java/com/ustc/timetable/settings/SettingsViewModel.kt`
- [Theme and wallpaper](https://github.com/kirsh1/ustc-timetable/blob/main/app/src/main/java/com/ustc/timetable/appearance/Appearance.kt): `app/src/main/java/com/ustc/timetable/appearance/Appearance.kt`

### Other components

- **Student**
- **Android Keystore**
- **USTC portal**

## Connections

- Student → Main activity: opens app
- Main activity → App navigation: hosts navigation
- App navigation → First launch: shows onboarding
- App navigation → Weekly timetable: shows schedule
- Student → First launch: starts import
- First launch → WebView sign-in: launches sign-in
- WebView sign-in → Login completion: signals login
- Login completion → Session manager: captures session
- Session manager → Portal source: verifies access
- Session manager → Encrypted session store: saves session
- Encrypted session store → Android Keystore: encrypts with
- Session manager → USTC portal: probes portal
- Semester import → Portal source: fetches pages
- Portal source → USTC portal: requests pages
- Sync engine → Portal source: fetches pages
- Sync engine → Portal parsers: parses pages
- Sync engine → Snapshot normalizer: normalizes snapshot
- Sync engine → Local timetable database: applies snapshot
- Semester import → Portal parsers: parses import
- Semester import → Snapshot normalizer: normalizes import
- Semester import → Schedule repositories: saves semester
- Manual sync → Sync engine: runs sync
- Weekly sync worker → Sync engine: runs sync
- Weekly timetable → Schedule repositories: observes schedule
- Weekly timetable → Timetable layout: renders grid
- Manual item editor → Schedule repositories: edits manual items
- Schedule repositories → Local timetable database: reads and writes
- Schedule profiles → Local timetable database: reads and writes
- App settings → Schedule profiles: edits profiles
- App settings → Theme and wallpaper: configures appearance
- Main activity → Theme and wallpaper: applies theme