How kirsh1/ustc-timetable works
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: SyncEngine.kt Sync engine · ImportFlowViewModel.kt Semester import · UstcSessionManager.kt Session manager · UstcHttpPortalSource.kt Portal source
Components 25
App experience
- Main activity
app/src/main/java/com/ustc/timetable/MainActivity.kt - App navigation
app/src/main/java/com/ustc/timetable/timetable/ui/AppRoot.kt - First launch
app/src/main/java/com/ustc/timetable/timetable/ui/FirstLaunchViewModel.kt - Weekly timetable
app/src/main/java/com/ustc/timetable/timetable/ui/TimetableScreen.kt - Timetable layout
app/src/main/java/com/ustc/timetable/timetable/layout/WeeklyTimetableGrid.kt - Manual item editor
app/src/main/java/com/ustc/timetable/manual/ManualItemEditorViewModel.kt
Portal access
- WebView sign-in
app/src/main/java/com/ustc/timetable/school/ustc/auth/WebViewLoginActivity.kt - Login completion
app/src/main/java/com/ustc/timetable/school/ustc/auth/LoginCompletionCoordinator.kt - Session manager
app/src/main/java/com/ustc/timetable/school/ustc/auth/UstcSessionManager.kt - Encrypted session store
app/src/main/java/com/ustc/timetable/school/ustc/auth/SessionStore.kt - Portal source
app/src/main/java/com/ustc/timetable/school/ustc/portal/UstcHttpPortalSource.kt - Portal parsers
app/src/main/java/com/ustc/timetable/school/ustc/parser - Snapshot normalizer
app/src/main/java/com/ustc/timetable/school/ustc/parser/UstcSnapshotNormalizer.kt
Schedule data
- Semester import
app/src/main/java/com/ustc/timetable/semester/ImportFlowViewModel.kt - Schedule repositories
app/src/main/java/com/ustc/timetable/timetable/data - Schedule profiles
app/src/main/java/com/ustc/timetable/scheduleprofile/ScheduleProfileRepository.kt - Local timetable database
app/src/main/java/com/ustc/timetable/timetable/data/db/TimetableDatabase.kt
Synchronization
- Sync engine
app/src/main/java/com/ustc/timetable/sync/SyncEngine.kt - Manual sync
app/src/main/java/com/ustc/timetable/sync/ManualSyncController.kt - Weekly sync worker
app/src/main/java/com/ustc/timetable/sync/WeeklySyncWorker.kt
Preferences
- App settings
app/src/main/java/com/ustc/timetable/settings/SettingsViewModel.kt - Theme and wallpaper
app/src/main/java/com/ustc/timetable/appearance/Appearance.kt
Other components
- Student
- Android Keystore
- USTC portal
Connections 31
- 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