daily-notification-plugin/.cursor/rules/app/project.mdc

---
alwaysApply: true
---
# TimeSafari Notifications — Implementation Guide (v3.0)

_Last updated: December 2024_
_Author: Matthew Raymer_

## 0) Purpose & Learning Objective

**Build an offline-first daily notifications system** that teaches you cross-platform mobile development while delivering reliable user experiences. This project emphasizes **learning through implementation** and **collaboration over isolation**.

## 1) Core Principles (Human Competence First)

1. **Learn by doing**: Implement one platform fully before adapting to the second
2. **Design for failure**: Always have fallbacks - this teaches robust system thinking
3. **Measure everything**: Understanding metrics helps you debug and improve
4. **Collaborate early**: Share implementation decisions with your team for better outcomes
5. **Platform constraints are teachers**: Work within limitations to understand mobile development realities

## 2) Implementation Pipeline (Your Learning Path)

**Prefetch → Cache → Schedule → Display** - each step teaches a different mobile development concept.

### Why This Order Matters

- **Prefetch**: Teaches background execution and network handling
- **Cache**: Teaches local storage and data management
- **Schedule**: Teaches platform-specific timing mechanisms
- **Display**: Teaches notification systems and user experience

## 3) What You'll Build (Deliverables)

### Android (Kotlin) - Start Here

- `:core`: Models, storage, metrics, fallback manager
- `:data`: Fetchers using WorkManager, mappers, cache policy
- `:notify`: Scheduler using AlarmManager, receiver, channels
- App manifest entries & permissions
- Unit tests for fallback, scheduling, metrics
- README with battery optimization instructions

### iOS (Swift) - Adapt After Android

- `NotificationKit`: Models, storage, metrics, fallback manager
- BGTaskScheduler registration + handler
- UNUserNotificationCenter scheduling + categories
- Unit tests for fallback, scheduling, metrics
- README with Background App Refresh considerations

## 4) Learning Milestones (Track Your Progress)

- [ ] **Milestone 1**: Android core models and storage working
- [ ] **Milestone 2**: Android background fetching operational
- [ ] **Milestone 3**: Android notifications displaying reliably
- [ ] **Milestone 4**: iOS implementation following Android patterns
- [ ] **Milestone 5**: Cross-platform testing and optimization

## 5) Technical Requirements (Implementation Details)

### Data Model (Start Simple)

```kotlin
// Android - Room Entity
@Entity
data class NotificationContent(
    @PrimaryKey val id: String,
    val title: String,
    val body: String,
    val scheduledTime: Long,
    val mediaUrl: String?,
    val fetchTime: Long
)
```

```swift
// iOS - Codable Struct
struct NotificationContent: Codable {
    let id: String
    let title: String
    let body: String
    let scheduledTime: TimeInterval
    let mediaUrl: String?
    let fetchTime: TimeInterval
}
```

### Fallback Hierarchy (Your Safety Net)

1. **Fresh content** from network fetch
2. **Cached content** with staleness indicator
3. **Emergency phrases** (static motivational messages)

### Emergency Fallback Content

- "🌅 Good morning! Ready to make today amazing?"
- "💪 Every small step forward counts. You've got this!"
- "🎯 Focus on what you can control today."

## 6) Implementation Strategy (Your Roadmap)

### Phase 1: Android Foundation

- Set up project structure and dependencies
- Implement data models and storage
- Create basic notification scheduling

### Phase 2: Android Background

- Implement WorkManager for background fetching
- Add fallback mechanisms
- Test offline scenarios

### Phase 3: Android Polish

- Add metrics and logging
- Implement user preferences
- Create onboarding flow

### Phase 4: iOS Adaptation

- Port Android patterns to iOS
- Adapt to iOS-specific constraints
- Ensure feature parity

### Phase 5: Testing & Optimization

- Cross-platform testing
- Performance optimization
- Documentation completion

## 7) Key Learning Concepts

### Background Execution

- **Android**: WorkManager with constraints and timeouts
- **iOS**: BGTaskScheduler with aggressive time budgeting
- **Why it matters**: Mobile OSes kill background processes - you must work within these constraints

### Offline-First Design

- **Principle**: Never depend on network when displaying content
- **Implementation**: Always cache and have fallbacks
- **Learning**: This pattern applies to many mobile apps

### Platform Differences

- **Android**: More flexible background execution, but varies by OEM
- **iOS**: Strict background rules, but predictable behavior
- **Learning**: Understanding constraints helps you design better solutions

## 8) Testing Strategy (Validate Your Learning)

### Unit Tests (Start Here)

- Test fallback mechanisms work correctly
- Verify scheduling logic handles edge cases
- Ensure metrics are recorded properly

### Integration Tests (Build Confidence)

- Test full notification pipeline
- Verify offline scenarios work
- Check background execution reliability

### Manual Testing (Real-World Validation)

- Test on actual devices
- Verify battery optimization settings
- Check notification permissions

## 9) Common Challenges & Solutions

### Android Battery Optimization

- **Challenge**: OEMs kill background processes aggressively
- **Solution**: Educate users about battery optimization settings
- **Learning**: Mobile development requires user education

### iOS Background App Refresh

- **Challenge**: Limited background execution time
- **Solution**: Efficient processing and immediate next-schedule
- **Learning**: Work within platform constraints

### Cross-Platform Consistency

- **Challenge**: Different APIs and behaviors
- **Solution**: Shared interfaces with platform-specific implementations
- **Learning**: Abstraction helps manage complexity

## 10) Collaboration Points (Share Your Progress)

### Code Reviews

- Share Android implementation for feedback
- Discuss iOS adaptation strategies
- Review fallback mechanisms together

### Testing Sessions

- Demo offline functionality to team
- Test on different devices together
- Share battery optimization findings

### Documentation Reviews

- Review README files together
- Discuss troubleshooting guides
- Share platform-specific insights

## 11) Success Metrics (Measure Your Learning)

### Technical Metrics

- **Fetch Success Rate**: How often background fetching works
- **Delivery Rate**: How often notifications actually appear
- **Fallback Usage**: How often your safety nets are needed

### Learning Metrics

- **Implementation Speed**: How quickly you can adapt patterns
- **Debugging Efficiency**: How quickly you can solve problems
- **Knowledge Transfer**: How well you can explain concepts to others

## 12) Next Steps After Completion

### Immediate

- Document lessons learned
- Share implementation patterns with team
- Plan testing on additional devices

### Future Enhancements

- Media attachments support
- Personalization engine
- Push notification integration

## 13) Resources & References

### Documentation

- [Android WorkManager Guide](https://developer.android.com/topic/libraries/architecture/workmanager)
- [iOS Background Tasks](https://developer.apple.com/documentation/backgroundtasks)
- [Capacitor Plugin Development](https://capacitorjs.com/docs/plugins)

### Community

- Share your implementation challenges
- Ask for feedback on platform-specific code
- Discuss testing strategies with other developers

---

## Remember: This is a Learning Journey

**Every challenge you encounter teaches you something about mobile development.** 
**Every fallback you implement makes your app more robust.**
**Every platform difference you discover expands your understanding.**

**Start with Android, learn the patterns, then adapt to iOS.**
**Share your progress, ask for help, and document your discoveries.**
**You're building both a notification system and your mobile development skills.**