How ngoxuanchien/timepaper works
Timepaper is a native macOS menu-bar app that turns a user’s weekly class schedule and optional Calendar events into per-display desktop wallpapers. The main workflow runs through AppState: it gathers schedule inputs, coordinates rendering and caching, applies images, persists display references, and triggers safe cleanup. AutomationEngine refreshes this workflow on scheduled boundaries and system events. The README documents the major capabilities; unsampled source means some internal call links are shown only where the excerpts or documentation establish them.
Main entry points: AppState.swift AppState · AutomationEngine.swift Automation engine · CalendarService.swift Calendar sync · WallpaperCleanupService.swift Storage cleanup
Components 25
App coordination
- AppState
Timepaper/App/AppState.swift - Class reminders
Timepaper/Services/NotificationService.swift
Schedule and settings
- Schedule entries
Timepaper/Models/ScheduleEntry.swift - Display configuration
Timepaper/Models/DisplayConfiguration.swift - Imported wallpapers
Timepaper/Models/WallpaperItem.swift - App settings
Timepaper/Services/AppSettings.swift - Calendar sync
Timepaper/Services/CalendarService.swift - Schedule queries
Timepaper/Core/ScheduleEngine.swift
Wallpaper pipeline
- Wallpaper import
Timepaper/Services/WallpaperImportService.swift - Render request
Timepaper/Core/RenderRequest.swift - Wallpaper renderer
Timepaper/Core/WallpaperRenderer.swift - Render cache
Timepaper/Core/WallpaperCacheManager.swift - Display discovery
Timepaper/Core/DisplayManager.swift - Desktop apply
Timepaper/Services/WallpaperService.swift - Storage cleanup
Timepaper/Services/WallpaperCleanupService.swift - Cleanup planner
Timepaper/Core/WallpaperCleanupPlanner.swift
Automation
- Automation engine
Timepaper/Core/AutomationEngine.swift - Next-fire scheduler
Timepaper/Core/AutomationScheduler.swift
User interface
- Menu bar popover
Timepaper/UI/MenuBarPopover.swift - Settings views
Timepaper/UI/Settings
Other components
- User
- macOS events
- Calendar.app data
- SwiftData store
- macOS desktop
Connections 31
- User → Menu bar popover: opens
- User → Settings views: edits
- Menu bar popover → AppState: invokes
- Settings views → AppState: invokes
- AppState → Schedule entries: reads and writes
- AppState → Display configuration: reads and writes
- AppState → Imported wallpapers: reads and writes
- AppState → App settings: reads
- Schedule entries → SwiftData store: persists
- Display configuration → SwiftData store: persists
- Imported wallpapers → SwiftData store: persists
- AppState → Calendar sync: requests events
- Calendar sync → Calendar.app data: reads events
- AppState → Schedule queries: queries schedule
- AppState → Render request: builds
- AppState → Render cache: requests image
- Render cache → Wallpaper renderer: renders on miss
- AppState → Display discovery: discovers displays
- AppState → Desktop apply: applies image
- Desktop apply → macOS desktop: sets wallpaper
- AppState → Storage cleanup: requests cleanup
- Storage cleanup → Cleanup planner: plans deletion
- Storage cleanup → Render cache: scans generated files
- AppState → Automation engine: starts and configures
- Automation engine → Next-fire scheduler: computes next fire
- macOS events → Automation engine: signals changes
- Calendar sync → Automation engine: posts change event
- Automation engine → AppState: dispatches refresh
- AppState → Class reminders: schedules reminders
- Settings views → Wallpaper import: imports images
- Wallpaper import → Imported wallpapers: provides metadata