How provincialcxz/worktimertrackerswift works
1. Project shape
- This is a Swift Package Manager macOS app, not a server or library.
- The runtime is a desktop timer application with a UI layer, a timer/pomodoro engine, persistence via SQLite, and a set of user-facing services like notifications, sound, export, and Dock/menu-bar behavior.
2. Top-level entry points
- WorkTimerTrackerApp.swift is the SwiftUI app entry.
- AppDelegate.swift likely bridges macOS app lifecycle concerns that SwiftUI doesn’t handle cleanly on its own, especially Dock/menu bar visibility and app behavior.
- AppModel.swift is the main shared state/orchestration layer connecting views to core logic and services.
3. UI layer
- The Views/ folder contains the main screens:
- MainView as the container/root screen
- TimerView for live timer control
- HistoryView for session browsing and filtering
- StatsView for aggregated reporting
- SettingsView for preferences
- EditSessionView for modifying stored work sessions
- DayTimelineView for a date-based visual breakdown
- AppTheme.swift centralizes visual styling.
- The UI is likely state-driven: views read from AppModel and trigger actions back into it.
4. Core timer/pomodoro subsystem
- Core/TimerEngine.swift is the low-level timing engine for start, pause, resume, stop, and reset behavior.
- Core/PomodoroManager.swift sits above the raw timer and manages pomodoro-specific state: work intervals, short/long breaks, and daily cycle counting.
- This is the heart of the app’s time progression logic and should be treated as separate from persistence and UI.
5. Domain model
- Models/WorkSession.swift represents a tracked session record, likely including timestamps, duration, project/tags, and status.
- Models/Formatters.swift is a presentation/helper layer for converting dates, durations, and related values for display/export.
- The domain model sits between the timer engine and the database/UI.
6. Persistence boundary
- Database/DatabaseManager.swift owns SQLite setup and database access.
- Database/SessionRepository.swift is the session-focused persistence API used by the rest of the app.
- The database is explicitly stored in the user’s Application Support directory:
~/Library/Application Support/WorkTimerTracker/worktimertracker.sqlite3
- This is the main durable store for historical sessions and any edits.
7. Data flow: live timer to stored session
- User actions in the UI start or control the timer.
- AppModel passes those actions into the core timer/pomodoro layer.
- When a work interval completes or a session is stopped, the app persists a WorkSession through the repository/database layer.
- Historical views and stats read back from the repository, not from the live timer engine.
8. History, stats, and editing
- HistoryView and StatsView are read-heavy consumers of the repository.
- Filtering by date/project/tag is part of the history/query boundary, meaning the repository or model layer likely exposes query methods rather than the views filtering raw data themselves.
- EditSessionView represents a write-back path from the UI to stored session records, so persistence is not append-only.
9. Ancillary services
- Services/NotificationService.swift handles user notifications, probably for interval transitions and completion events.
- Services/SoundService.swift handles alert sounds for timer events.
- Services/DockVisibilityService.swift manages macOS-specific behavior around Dock/menu-bar presentation.
- Services/ExportService.swift produces CSV and JSON exports from stored sessions, making the database a source for external reports.
10. Platform and deployment behavior
- The README emphasizes running as a real .app for correct Dock/menu bar behavior, which implies some app behavior depends on macOS application packaging rather than plain swift run.
- There are scripts to build the app bundle, package a DMG, generate icons, and create a DMG background, so distribution is a first-class concern.
11. Repository-level boundaries
- Sources/WorkTimerTrackerSwift/ is organized by concern: Core, Database, Models, Services, Views.
- That separation suggests a clean flow:
UI → AppModel → Core/Services → Repository/SQLite
with read paths returning back up to the views.
12. Testing and tooling
- There is a small XCTest target under Tests/, indicating at least some unit coverage, likely for core logic and model behavior.
- scripts/ contains packaging automation rather than build-time business logic, so it should be shown as a release/deployment support lane, not part of runtime architecture.
13. What to show in an architecture diagram
- A macOS SwiftUI app shell at the top.
- A central state/orchestration node (AppModel) connecting:
- UI screens
- timer/pomodoro engine
- notifications/sound/Dock services
- session repository/database
- export service
- A persistent SQLite store in Application Support as the system of record.
- Separate packaging/release tooling outside the runtime path.
Main entry points: AppModel.swift AppModel · MainView.swift Main View · SessionRepository.swift Sessions · HistoryView.swift History
Components 25
App Shell
macOS app entry and lifecycle coordination
- App · SwiftUI application entry point
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/WorkTimerTrackerApp.swift - Delegate · Bridges macOS app lifecycle behavior SwiftUI does not cover cleanly
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/AppDelegate.swift - AppModel · Shared state and coordination layer connecting UI, core logic, and services
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/AppModel.swift
UI
SwiftUI screens and theme
- Main View · Root container for the app's visible UI
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Views/MainView.swift - Timer · Live timer controls and active session display
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Views/TimerView.swift - History · Session history browsing and filtering
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Views/HistoryView.swift - Stats · Aggregated reporting and session summaries
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Views/StatsView.swift - Settings · User preferences and app settings
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Views/SettingsView.swift - Edit Session · Write-back UI for modifying stored sessions
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Views/EditSessionView.swift - Day Timeline · Date-based breakdown of work activity
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Views/DayTimelineView.swift - Theme · Shared visual styling and UI appearance constants
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Views/AppTheme.swift
Core
Timer and pomodoro progression
- Timer Engine · Low-level start, pause, resume, stop, and reset timing logic
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Core/TimerEngine.swift - Pomodoro · Pomodoro-specific work/break cycle and session progression
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Core/PomodoroManager.swift
Data
Domain model and SQLite persistence
- WorkSession · Tracked session model stored and edited by the app
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Models/WorkSession.swift - Formatters · Date, duration, and display formatting helpers
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Models/Formatters.swift - Database · SQLite setup and access layer; persists in Application Support
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Database/DatabaseManager.swift - Sessions · Session-focused persistence API used by the app
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Database/SessionRepository.swift
Services
macOS notifications, sound, export, and Dock behavior
- Notifications · Local notifications for timer transitions and completion events
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Services/NotificationService.swift - Sound · Alert sound playback for timer events
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Services/SoundService.swift - Dock Visibility · Controls Dock/menu-bar presentation behavior on macOS
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Services/DockVisibilityService.swift - Export · Exports stored sessions for external reporting
WorkTimerTrackerSwift/Sources/WorkTimerTrackerSwift/Services/ExportService.swift
Tooling
Packaging and release scripts
- Build App · Builds the app bundle for distribution
WorkTimerTrackerSwift/scripts/build_app.sh - Package DMG · Creates the distributable DMG package
WorkTimerTrackerSwift/scripts/package_dmg.sh - App Icon · Generates application icons
WorkTimerTrackerSwift/scripts/make_app_icon.swift - DMG Background · Generates DMG background artwork
WorkTimerTrackerSwift/scripts/make_dmg_background.swift
Connections 25
- App → Delegate: lifecycle · Application startup and macOS lifecycle integration
- App → AppModel: creates · App entry constructs the shared model
- Delegate → Dock Visibility: controls · Lifecycle bridge influences Dock/menu-bar presentation
- AppModel → Main View: binds · Shared state is observed by the root UI
- Main View → Timer: contains · Root screen hosts the live timer screen
- Main View → History: contains · Root screen hosts session history
- Main View → Stats: contains · Root screen hosts reporting views
- Main View → Settings: contains · Root screen hosts preferences
- Main View → Day Timeline: contains · Root screen hosts day breakdown view
- AppModel → Pomodoro: drives · Model sends timer control into pomodoro progression
- Pomodoro → Timer Engine: uses · Pomodoro logic is built atop the raw timer engine
- AppModel → Sessions: reads/writes · Model persists and queries tracked sessions
- Sessions → Database: backed by · Repository delegates to SQLite storage
- Database → WorkSession: stores · Persistent records are session domain objects
- History → Sessions: queries · History screen reads stored sessions and filters them
- Stats → Sessions: aggregates · Stats screen reads persisted sessions for summaries
- Edit Session → Sessions: updates · Editing screen writes changes back to persistence
- AppModel → Notifications: triggers · Timer transitions can produce notifications
- AppModel → Sound: triggers · Timer events can play alert sounds
- AppModel → Export: exports · Shared model coordinates CSV/JSON export from stored sessions
- History → Formatters: formats · History display uses shared presentation formatting
- Stats → Formatters: formats · Stats display uses shared presentation formatting
- Build App → Package DMG: supports · Build step feeds packaging workflow
- Package DMG → DMG Background: uses · DMG packaging relies on generated background assets
- Package DMG → App Icon: uses · Packaging workflow relies on generated app icons