TrueTime — True Solar Time
Project Overview
TrueTime is a SwiftUI iOS app that shows the true solar time at the user's current location — the time derived from the sun's actual position in the sky, as opposed to civil clock time, which is offset by time zone boundaries and the equation of time. The app resolves the device's precise GPS coordinates, computes true solar time and the sun's elevation/azimuth, and renders a live clock alongside an abstract sun-path diagram and a small map preview of the resolved location. A comparison view lets the user see true solar time next to standard clock time side by side.
Technical Details
The app is split into a SwiftUI application target and a standalone, unit-tested SolarAstronomy Swift package (Julian Day conversion, solar position, sunrise/sunset event calculation, and true-time results) that the app consumes. Location handling goes through CoreLocation with an explicit authorization state machine (LocationAuthorizationState, PermissionDeniedView, LoadingLocationView) so the UI degrades gracefully while permission is pending or denied. LocationTimeZoneResolver reconciles GPS coordinates with the correct local time zone, and TimeEngine/ClockTicker drive the live-updating clock. A MapKit preview (LocationMapPreview) shows the resolved location, and SunPositionDiagram renders elevation/azimuth visually. Settings (GeneralSettingsView) expose adjustable coordinate-display precision, and the app ships English and Simplified Chinese localizations with an in-app language picker (Localizable.xcstrings). GitHub Actions CI runs the SolarAstronomy test suite and builds the app on every push.
Features
- ✓Real-time true solar time clock derived from the device's precise GPS location
- ✓Solar elevation and azimuth calculation with an abstract sun-path diagram
- ✓Sunrise/sunset and other sun-event calculations
- ✓Side-by-side comparison of true solar time vs. standard clock time
- ✓Small MapKit preview confirming the resolved location
- ✓Adjustable coordinate-display precision in Settings
- ✓Graceful location-permission flow with dedicated loading and permission-denied states
- ✓English and Simplified Chinese localization with an in-app language picker
- ✓Standalone, unit-tested SolarAstronomy Swift package with CI running tests and app builds on every push
Technologies Used
Challenges and Solutions
Challenge 1
True solar time requires astronomically accurate calculations (Julian Day conversion, equation of time, solar position) that need to be correct and independently verifiable, not just visually plausible
Solution:
Isolated all astronomical math into a standalone SolarAstronomy Swift package with its own XCTest suite, decoupled from the UI and verified by GitHub Actions CI on every push
Challenge 2
Location access is sensitive and can be denied, delayed, or imprecise, so the UI needs to handle every permission and loading state without breaking the core clock experience
Solution:
Modeled location access as an explicit state machine (LocationAuthorizationState) with dedicated LoadingLocationView and PermissionDeniedView screens instead of ad-hoc conditionals
Challenge 3
Reconciling raw GPS coordinates with the correct local time zone for meaningful comparison against civil clock time
Solution:
Built a dedicated LocationTimeZoneResolver to map resolved coordinates to the correct time zone before computing the true-time-vs-clock-time comparison