student-timekeeper-ios

DreamLauncherLite iOS - Complete Documentation

📚 Documentation Index

This folder contains complete documentation for the new, streamlined iOS app that replaces the bloated dreamlauncher-ios.

Core Documents

STREAMLINED_IOS_APP_PLAN.md
- Executive summary and rationale
- Complete architecture overview
- Feature breakdown
- Implementation phases (5 weeks)
- Data models and API integration
- Comparison with student-time-tracker
IOS_APP_TECHNICAL_SPEC.md
- Detailed code specifications
- Complete service implementations
- View and ViewModel patterns
- Core Data schema
- API client implementation
- Storage layer design
- ~2,300 lines of code total
IOS_APP_IMPLEMENTATION_CHECKLIST.md
- Day-by-day implementation plan
- 30-day timeline to App Store
- Testing checklist
- App Store submission guide
- Troubleshooting section
OLD_VS_NEW_IOS_COMPARISON.md
- Side-by-side feature comparison
- Performance metrics
- Cost analysis
- Legal compliance comparison
- Why the old app failed

🎯 Quick Summary

The Problem

The old dreamlauncher-ios app:

❌ 10,000+ lines of bloated code
❌ 20+ screens users never needed
❌ 8 permission requests (creepy)
❌ Tracked health, location, motion, friends
❌ Legal issues → deprecated
❌ Never properly shipped

The Solution

The new DreamLauncherLite app:

✅ 2,300 lines of focused code (77% less)
✅ 3 screens (Auth, Dashboard, Settings)
✅ 2 permissions (Apple Sign-In, Screen Time)
✅ Tracks only screen time
✅ No legal issues
✅ Ships in 6 weeks

🚀 What It Does

One thing: Cross-platform screen time tracking

Core Features

Track iOS screen time using Family Controls
Sync to cloud via existing dreamlauncher-api
View combined data from iOS + macOS devices
See weekly trends with simple charts
Platform breakdown (how much time on each device)

What It Doesn’t Do

❌ No health tracking
❌ No location tracking
❌ No social features
❌ No screenshots
❌ No audio recording
❌ No bloat

📋 Prerequisites

Development Requirements

macOS 13.0+ with Xcode 15.0+
Apple Developer Account ($99/year)
Family Controls entitlement (request from Apple)
Swift 5.9+ knowledge
SwiftUI experience

Existing Infrastructure

✅ dreamlauncher-api - Already built and running
✅ Database schema - UserScreenTime table exists
✅ Authentication - Apple Sign-In endpoints ready
✅ API endpoints - /user-screen-time ready

🏗️ Architecture

┌─────────────────────────────────────────┐
│         iOS App (SwiftUI)               │
│                                         │
│  Views                                  │
│  ├── AuthView                           │
│  ├── DashboardView                      │
│  └── SettingsView                       │
│                                         │
│  ViewModels                             │
│  ├── AuthViewModel                      │
│  └── DashboardViewModel                 │
│                                         │
│  Services                               │
│  ├── AuthService                        │
│  ├── ScreenTimeService                  │
│  ├── SyncService                        │
│  └── APIClient                          │
│                                         │
│  Storage                                │
│  ├── KeychainService                    │
│  ├── CoreDataStack                      │
│  └── StorageService                     │
└─────────────┬───────────────────────────┘
              │
              │ HTTPS/REST
              ▼
┌─────────────────────────────────────────┐
│      dreamlauncher-api (Node.js)        │
│                                         │
│  Endpoints                              │
│  ├── POST /apple-auth/sign-in           │
│  ├── POST /user-screen-time             │
│  ├── GET  /user-screen-time             │
│  └── GET  /user-screen-time/combined    │
│                                         │
│  Database (PostgreSQL)                  │
│  ├── users                              │
│  └── user_screen_time                   │
└─────────────┬───────────────────────────┘
              │
              │ Shared Data
              ▼
┌─────────────────────────────────────────┐
│      macOS App (student-time-tracker)   │
│                                         │
│  - Displays iOS data                    │
│  - Uploads macOS data                   │
│  - Combined view                        │
└─────────────────────────────────────────┘

📦 File Structure

DreamLauncherLite-iOS/
├── DreamLauncherLite/
│   ├── App/
│   │   ├── DreamLauncherLiteApp.swift
│   │   └── AppDelegate.swift
│   ├── Models/
│   │   ├── ScreenTimeEntry.swift
│   │   └── User.swift
│   ├── Services/
│   │   ├── AuthService.swift              (100 lines)
│   │   ├── ScreenTimeService.swift        (150 lines)
│   │   ├── SyncService.swift              (200 lines)
│   │   └── APIClient.swift                (350 lines)
│   ├── ViewModels/
│   │   ├── AuthViewModel.swift            (100 lines)
│   │   └── DashboardViewModel.swift       (200 lines)
│   ├── Views/
│   │   ├── AuthView.swift                 (100 lines)
│   │   ├── DashboardView.swift            (300 lines)
│   │   └── SettingsView.swift             (100 lines)
│   ├── Storage/
│   │   ├── CoreDataStack.swift            (100 lines)
│   │   ├── StorageService.swift           (200 lines)
│   │   ├── KeychainService.swift          (100 lines)
│   │   └── DreamLauncher.xcdatamodeld
│   ├── Extensions/
│   │   ├── Date+Extensions.swift          (100 lines)
│   │   └── View+Extensions.swift          (100 lines)
│   ├── Config.swift                       (50 lines)
│   └── Info.plist
├── DeviceActivityMonitorExtension/
│   ├── DeviceActivityMonitorExtension.swift
│   └── Info.plist
└── DeviceActivityReportExtension/
    ├── TotalActivityReport.swift
    └── Info.plist

Total: ~2,300 lines of code across ~20 files

🎯 Implementation Timeline

Week 1: Foundation (5 days)

Day 1: Project setup, folder structure
Day 2: Storage layer (Keychain, Core Data)
Day 3: Network layer (APIClient)
Day 4: Authentication service
Day 5: App structure, auth flow

Deliverable: Working authentication

Week 2: Screen Time (5 days)

Day 6: Screen Time service
Day 7-8: DeviceActivityReport extension
Day 9: DeviceActivityMonitor extension
Day 10: Dashboard UI

Deliverable: Collecting real iOS screen time

Week 3: Sync (5 days)

Day 11: Sync service
Day 12: Background sync
Day 13-14: Offline support
Day 15: Code cleanup

Deliverable: Data syncing to backend

Week 4: Cross-Platform (5 days)

Day 16-17: Fetch combined data
Day 18: Week chart
Day 19: Settings view
Day 20: UI polish

Deliverable: Shows iOS + macOS data

Week 5: Polish (5 days)

Day 21-22: Unit tests
Day 23: Integration tests
Day 24: Bug fixes
Day 25: TestFlight prep

Deliverable: Production-ready app

Week 6: Submission

Day 26: Archive & upload
Day 27: App Store Connect setup
Day 28-30: Review & approval

Deliverable: Live on App Store

💡 Key Design Decisions

1. Why No Third-Party Dependencies?

Faster compile times
Smaller app size
Better security
Easier App Store approval
Less maintenance

2. Why SwiftUI Only?

Modern, declarative UI
Less code than UIKit
Better Dark Mode support
Easier animations
Future-proof

3. Why Actor for SyncService?

Thread-safe by default
Prevents race conditions
Modern Swift concurrency
Better than locks/semaphores

4. Why Core Data Instead of SQLite?

Native Apple framework
Better iOS integration
iCloud sync ready (future)
Relationship management
Migration tools

5. Why No Firebase?

Don’t need real-time updates
Own API already exists
Reduce dependencies
Cost savings
Better control

🔒 Privacy & Security

Data Collection

Only collects:

Screen time duration (minutes)
Device type (iOS_PHONE or IOS_TABLET)
Time period (start/end dates)
Time zone

Does NOT collect:

Per-app usage
Website URLs
Screen content
Location
Health data
Contacts
Any personal data beyond screen time

Data Storage

Encrypted in transit (HTTPS)
Encrypted at rest (database)
User can delete anytime
No data sharing
No third-party analytics

Compliance

✅ GDPR compliant
✅ CCPA compliant
✅ COPPA compliant
✅ App Store guidelines
✅ Family Controls terms

🧪 Testing

Unit Tests (~80% coverage)

AuthServiceTests
- testAppleSignIn()
- testTokenRefresh()
- testLogout()

StorageServiceTests
- testSaveEntry()
- testFetchUnsynced()
- testMarkSynced()

APIClientTests
- testAuth()
- testUpload()
- testFetch()

SyncServiceTests
- testBatchUpload()
- testRetry()
- testOfflineQueue()

Integration Tests

EndToEndTests
- testAuthToSync()
- testCrossPlatformData()
- testOfflineToOnline()

Manual Tests

Fresh install flow
Background sync
Offline mode
App termination
Token refresh
Different device types

🚢 Deployment

App Store Checklist

Launch Strategy

Submit to App Store
Wait for approval (1-3 days)
Soft launch to beta testers
Monitor crashes/feedback
Fix critical bugs
Full public release

📊 Success Metrics

Technical KPIs

Crash-free rate: >99.5%
App launch time: <2 seconds
Sync success rate: >95%
Battery drain: <2% per day

User KPIs

Time to first value: <1 minute
Day 1 retention: >80%
Day 30 retention: >70%
App Store rating: >4.5 stars

Business KPIs

Development time: 6 weeks
Development cost: <$10K
First submission approval: Yes
Time to 100 users: <1 month

🎓 Learning Resources

Apple Documentation

SwiftUI

Best Practices

🤔 FAQ

Q: Why build a new app instead of fixing the old one?

A: The old app has too much technical debt and legal issues. Starting fresh is faster and safer.

Q: Can we add [feature X] later?

A: Maybe, but resist feature creep. Keep it simple. Every feature has a cost.

Q: What about Android/Windows?

A: Focus on iOS first. Prove the concept. Then consider other platforms.

Q: Why not use React Native?

A: Native SwiftUI is faster, smaller, more reliable, and better for Family Controls integration.

Q: How do I request Family Controls entitlement?

A: Go to https://developer.apple.com/contact/request/family-controls-distribution and explain your use case.

Q: What if Apple rejects the app?

A: Follow the checklist, be clear about purpose, and provide demo credentials. Should be approved first try.

🛠️ Troubleshooting

Family Controls not working

Check entitlement is approved in developer portal
Verify bundle ID matches exactly
Restart device after install
Check authorization status

Background sync not triggering

Verify BGTaskScheduler registered
Check background modes enabled
Test with Xcode debugger
Check battery optimization settings

API sync failing

Verify API is running
Check token validity
Inspect network requests
Review API logs

Core Data crashes

Check thread safety
Use background contexts correctly
Verify schema matches
Check for nil values

📞 Support

Issues

Check existing documentation first
Review troubleshooting section
Test on clean install
Provide logs and steps to reproduce

Contributing

This is a personal project, but feedback welcome:

Suggest improvements (keep it simple!)
Report bugs with details
Share testing results

📝 License

This documentation and code are part of the DreamLauncher project. See main project LICENSE for details.

🎉 Let’s Ship It!

You have everything you need:

✅ Complete architecture design
✅ Detailed technical specs
✅ Day-by-day implementation plan
✅ Testing strategy
✅ Deployment checklist
✅ Lessons learned from old app

Next step: Create the Xcode project and start Day 1.

Estimated time to App Store: 6-7 weeks

Let’s build something simple, focused, and actually useful! 🚀

dreamlauncher-api/ - Existing backend (already built)
student-time-tracker/ - macOS app (uses same API)
dreamlauncher-ios/ - Old app (DEPRECATED, legal issues)
dreamlauncher-lite-ios/ - New app (TO BE CREATED)

Last updated: January 2025 Version: 1.0 (Pre-development documentation)