docs: add comprehensive notification system documentation

- Add GLOSSARY.md with core terminology and cross-references - Add implementation-roadmap.md with 3-phase development plan - Add notification-system.md with Native-First architecture spec - Update ios/Plugin/README.md to reflect actual vs planned implementation status This establishes the foundation for implementing shared SQLite storage, TTL-at-fire enforcement, rolling window safety, and platform completion as outlined in the phased roadmap. Files: 4 changed, 807 insertions(+), 13 deletions(-)
2025-09-08 08:57:36 +00:00
parent 9f8a8e60a9
commit 3a181632d1
7 changed files with 903 additions and 13 deletions
--- a/doc/implementation-roadmap.md
+++ b/doc/implementation-roadmap.md
@@ -0,0 +1,486 @@
+# Daily Notification Plugin - Implementation Roadmap
+
+**📝 SANITY CHECK IMPROVEMENTS APPLIED:** This document has been updated to clarify current implementation status and distinguish between existing infrastructure and planned T–lead logic.
+
+**Status:** Ready for implementation  
+**Date:** 2025-01-27  
+**Author:** Matthew Raymer  
+**Assessment Date:** 2025-01-27
+
+---
+
+## Executive Summary
+
+This document outlines the implementation roadmap to bring the current Daily Notification Plugin (65% complete) to full compliance with the Native-First Notification System specification. The implementation is organized into three phases, with Phase 1 containing critical infrastructure components required for core functionality.
+
+### Current State Assessment
+- **Overall Completion:** 65% of specification requirements
+- **Critical Gaps:** SQLite database sharing, TTL-at-fire enforcement, rolling window safety
+- **Current Storage:** SharedPreferences (Android) / UserDefaults (iOS) + in-memory cache
+- **Background Infrastructure:** Basic WorkManager (Android) exists, but lacks T–lead logic
+- **Critical Path:** Data persistence → Freshness enforcement → Platform completion
+
+---
+
+## Current Implementation Status Clarification
+
+### Background Fetch Infrastructure
+**Current State:** Basic infrastructure exists but lacks T–lead logic
+- **Android:** `DailyNotificationFetchWorker.java` (WorkManager) exists
+- **Android:** `DailyNotificationFetcher.java` with scheduling logic exists
+- **Missing:** T–lead calculation, TTL enforcement, ETag support
+- **Status:** Infrastructure ready, T–lead logic needs implementation
+
+### iOS Implementation Status
+**Current State:** Basic plugin structure with power management
+- **Implemented:** Plugin skeleton, power management, UserDefaults storage
+- **Missing:** BGTaskScheduler, background tasks, T–lead prefetch
+- **Status:** Foundation exists, background execution needs implementation
+
+---
+
+**Gate:** No further freshness or scheduling work merges to main until **shared SQLite** (see Glossary → Shared DB) is in place and reading/writing under **WAL** (see Glossary → WAL), with UI hot-read verified.
+
+**Dependencies:** None
+
+### 1.1 SQLite Database Sharing Implementation
+
+**Priority:** CRITICAL
+
+#### Requirements
+- Migrate from SharedPreferences/UserDefaults to shared SQLite database (see Glossary → Shared DB)
+- WAL mode configuration for concurrent access (see Glossary → WAL)
+- Schema version checking and compatibility validation (see Glossary → PRAGMA user_version)
+- Required tables: `notif_contents`, `notif_deliveries`, `notif_config`
+- **Migration Strategy:** Gradual migration from current tiered storage (see Glossary → Tiered Storage)
+
+#### Implementation Tasks
+- [ ] **Migration from Current Storage**
+  - Create migration utilities from SharedPreferences to SQLite
+  - Implement data migration from UserDefaults to SQLite (iOS)
+  - Add backward compatibility during transition
+  - Preserve existing notification data during migration
+
+- [ ] **SQLite Setup (Android)**
+  - Create `DailyNotificationDatabase.java` with WAL mode (see Glossary → WAL)
+  - Implement schema version checking (`PRAGMA user_version`) (see Glossary → PRAGMA user_version)
+  - Add database connection management with proper error handling
+
+- [ ] **Database Configuration**
+  - Add `dbPath: string` to `ConfigureOptions` interface
+  - Implement database path resolution (absolute vs platform alias)
+  - Add `storage: 'shared'` configuration option
+  - Extend existing `NotificationOptions` with database settings
+
+- [ ] **Database Schema**
+  ```sql
+  -- notif_contents: keep history, newest-first reads
+  CREATE TABLE IF NOT EXISTS notif_contents(
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    slot_id TEXT NOT NULL,
+    payload_json TEXT NOT NULL,
+    fetched_at INTEGER NOT NULL,  -- epoch ms
+    etag TEXT,
+    UNIQUE(slot_id, fetched_at)
+  );
+  CREATE INDEX IF NOT EXISTS notif_idx_contents_slot_time
+    ON notif_contents(slot_id, fetched_at DESC);
+
+  -- notif_deliveries: track many deliveries per slot/time
+  CREATE TABLE IF NOT EXISTS notif_deliveries(
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    slot_id TEXT NOT NULL,
+    fire_at INTEGER NOT NULL,     -- intended fire time (epoch ms)
+    delivered_at INTEGER,         -- when actually shown (epoch ms)
+    status TEXT NOT NULL DEFAULT 'scheduled',  -- scheduled|shown|error|canceled
+    error_code TEXT, error_message TEXT
+  );
+
+  -- notif_config: generic configuration KV
+  CREATE TABLE IF NOT EXISTS notif_config(
+    k TEXT PRIMARY KEY,
+    v TEXT NOT NULL
+  );
+  ```
+
+#### Acceptance Criteria
+- [ ] App and plugin can open the same SQLite file
+- [ ] WAL mode enables concurrent reads during writes
+- [ ] Schema version checking prevents compatibility issues
+- [ ] All required tables exist and are accessible
+- [ ] Shared DB visibility: UI reads updated rows immediately
+- [ ] WAL overlap shows no UI blocking during background writes
+- [ ] UI can read a row written by a background job **within the same second** (WAL hot-read)
+- [ ] Plugin refuses to write if `PRAGMA user_version` < expected
+
+### 1.2 TTL-at-Fire Enforcement
+
+**Priority:** CRITICAL
+
+#### Requirements
+- Skip arming notifications if `(T - fetchedAt) > ttlSeconds` (see Glossary → TTL)
+- Validate freshness before scheduling
+- Log TTL violations for debugging
+- **Current State:** Not implemented - needs to be added to existing scheduling logic
+- **Shared DB (single file):** App owns migrations (`PRAGMA user_version`) (see Glossary → PRAGMA user_version); plugin opens the **same path**; enable `journal_mode=WAL` (see Glossary → WAL), `synchronous=NORMAL`, `busy_timeout=5000`, `foreign_keys=ON`; background writes are **short & serialized**.
+
+#### Implementation Tasks
+- [ ] **TTL Validation Logic**
+  - Insert TTL check into the scheduler path **before** any arm/re-arm
+  - Add log code `TTL_VIOLATION`
+  - Implement freshness validation before arming
+  - Before arming, if `(T − fetchedAt) > ttlSeconds`, **skip arming** and log `TTL_VIOLATION`
+  - Add TTL configuration to `NotificationOptions`
+
+- [ ] **Freshness Checking**
+  - Create `isContentFresh()` method
+  - Implement TTL calculation logic
+  - Add logging for TTL violations
+
+- [ ] **Configuration Integration**
+  - Add `ttlSeconds` to `NotificationOptions` interface
+  - Implement default TTL values (3600 seconds = 1 hour)
+  - Add TTL validation in option validation
+
+#### Acceptance Criteria
+- [ ] Notifications are skipped if content is stale
+- [ ] TTL violations are logged with timestamps
+- [ ] Default TTL values are applied when not specified
+- [ ] Freshness checking works across all platforms
+- [ ] No armed notification violates **TTL-at-fire**
+- [ ] No armed row violates TTL at T across platforms
+
+### 1.3 Rolling Window Safety
+
+**Priority:** CRITICAL
+
+#### Requirements
+- Keep today's remaining notifications armed
+- Keep tomorrow's notifications armed (within iOS caps) (see Glossary → Rolling window)
+- Ensure closed-app delivery reliability
+- **Current State:** Basic scheduling exists, but no rolling window logic
+
+#### Implementation Tasks
+- [ ] **Rolling Window Logic** (see Glossary → Rolling window)
+  - Implement `armRollingWindow()` method
+  - Calculate today's remaining slots
+  - Calculate tomorrow's slots within iOS limits
+  - Account for iOS pending-notification limits; arm tomorrow only if within cap
+
+- [ ] **iOS Capacity Management**
+  - Implement iOS pending notification limit checking
+  - Add capacity-aware scheduling logic
+  - Handle capacity overflow gracefully
+
+- [ ] **Window Maintenance**
+  - Create `maintainRollingWindow()` method
+  - Implement automatic re-arming logic
+  - Add window state persistence
+
+#### Acceptance Criteria
+- [ ] Today's remaining notifications stay armed
+- [ ] Tomorrow's notifications are armed within iOS caps
+- [ ] Closed-app delivery works reliably
+- [ ] Window maintenance runs automatically
+- [ ] Today always armed; tomorrow armed when within iOS cap
+
+### 1.4 Configuration API Enhancement
+
+**Priority:** HIGH
+
+#### Requirements
+- Add `dbPath` configuration option
+- Implement database path resolution
+- Add storage mode configuration
+- **Current State:** No database path configuration exists
+
+#### Implementation Tasks
+- [ ] **Interface Updates**
+  - Extend `ConfigureOptions` with `dbPath: string`
+  - Add `storage: 'shared'` option
+  - Update validation logic
+
+- [ ] **Path Resolution**
+  - Implement absolute path handling
+  - Add platform-specific path resolution
+  - Create path validation logic
+
+#### Acceptance Criteria
+- [ ] `dbPath` can be configured via API
+- [ ] Path resolution works on all platforms
+- [ ] Configuration validation prevents invalid paths
+
+---
+
+## Phase 2: Platform Completion (High Priority)
+
+**Dependencies:** Phase 1 completion - **CRITICAL:** Phase 2 cannot start until SQLite sharing + TTL enforcement are finished
+
+### 2.1 iOS Background Tasks Implementation
+
+**Priority:** HIGH
+
+#### Requirements
+- `BGTaskScheduler` for T-lead prefetch (see Glossary → T–lead)
+- Silent push nudge support
+- Background execution budget management
+- Schedule prefetch at **T–lead = T − prefetchLeadMinutes** (see Glossary → T–lead)
+- On wake, perform **one** ETag-aware fetch with **12s** timeout; **never** fetch at delivery
+- Optionally (re)arm if still within **TTL-at-fire** (see Glossary → TTL)
+- Single attempt at **T–lead**; **12s** timeout; no delivery-time fetch; (re)arm only if within **TTL-at-fire**. **(Planned)**
+
+#### Implementation Tasks
+- [ ] **BGTaskScheduler Integration**
+  - Create `DailyNotificationBackgroundTask.swift`
+  - Implement background task registration
+  - Add task expiration handling
+
+- [ ] **Silent Push Support**
+  - Add silent push notification handling
+  - Implement push-to-background task bridge
+  - Add push token management
+
+- [ ] **Budget Management**
+  - Implement execution budget tracking
+  - Add budget-aware scheduling
+  - Handle budget exhaustion gracefully
+
+#### Acceptance Criteria
+- [ ] Background tasks run at T-lead (see Glossary → T–lead)
+- [ ] Silent push can trigger background execution
+- [ ] Budget management prevents system penalties
+- [ ] Background execution works when app is closed
+- [ ] iOS BGTask best-effort at T–lead; closed-app still delivers via rolling window (see Glossary → Rolling window)
+
+### 2.2 Android Fallback Completion
+
+**Priority:** HIGH
+
+#### Requirements
+- Complete ±10 minute windowed alarm implementation (see Glossary → Windowed alarm)
+- Finish reboot/time change recovery
+- Improve exact alarm fallback handling (see Glossary → Exact alarm)
+- Finalize ±10m windowed alarm; reboot/time-change recovery; deep-link to Exact Alarm permission. **(Planned)**
+
+#### Implementation Tasks
+- [ ] **Windowed Alarm Implementation**
+  - Complete `scheduleInexactAlarm()` method
+  - Implement ±10 minute window targeting
+  - Add window size configuration
+
+- [ ] **Recovery Mechanisms**
+  - Complete `BOOT_COMPLETED` receiver
+  - Implement `TIMEZONE_CHANGED` handling
+  - Add `TIME_SET` recovery logic
+
+- [ ] **Fallback Logic**
+  - Improve exact alarm permission checking
+  - Add graceful degradation to windowed alarms
+  - Implement fallback logging
+
+#### Acceptance Criteria
+- [ ] Windowed alarms target ±10 minute windows
+- [ ] Reboot recovery re-arms next 24h
+- [ ] Time change recovery recomputes schedules
+- [ ] Fallback works seamlessly
+- [ ] Android exact permission path verified with fallback ±10m
+
+### 2.3 Electron Platform Support
+
+**Priority:** MEDIUM
+
+#### Requirements
+- Notifications while app is running
+- Start-on-Login support
+- Best-effort background scheduling
+
+#### Implementation Tasks
+- [ ] **Electron Integration**
+  - Create `DailyNotificationElectron.ts`
+  - Implement notification API
+  - Add Start-on-Login support
+
+- [ ] **Background Limitations**
+  - Document Electron limitations
+  - Implement best-effort scheduling
+  - Add fallback mechanisms
+
+#### Acceptance Criteria
+- [ ] Notifications work while app is running
+- [ ] Start-on-Login enables post-reboot delivery
+- [ ] Limitations are clearly documented
+- [ ] Best-effort scheduling is implemented
+
+---
+
+## Phase 3: Network Optimization (Medium Priority)
+
+**Dependencies:** Phase 1 completion - **CRITICAL:** Phase 3 cannot start until SQLite sharing + TTL enforcement are finished
+
+### 3.1 ETag Support Implementation
+
+**Priority:** MEDIUM
+
+#### Requirements
+- ETag headers in fetch requests
+- 304 response handling
+- Network efficiency optimization
+
+#### Implementation Tasks
+- [ ] **ETag Headers**
+  - Add ETag to fetch requests
+  - Implement ETag storage in database
+  - Add ETag validation logic
+
+- [ ] **304 Response Handling**
+  - Implement 304 response processing
+  - Add conditional request logic
+  - Handle ETag mismatches
+
+- [ ] **Network Optimization**
+  - Add request caching
+  - Implement conditional fetching
+  - Add network efficiency metrics
+
+#### Acceptance Criteria
+- [ ] ETag headers are sent with requests
+- [ ] 304 responses are handled correctly
+- [ ] Network efficiency is improved
+- [ ] Conditional requests work reliably
+
+### 3.2 Advanced Error Handling
+
+**Priority:** MEDIUM
+
+#### Requirements
+- Comprehensive error categorization
+- Retry logic with exponential backoff
+- Error reporting and telemetry
+
+#### Implementation Tasks
+- [ ] **Error Categories**
+  - Define error types and codes
+  - Implement error classification
+  - Add error severity levels
+
+- [ ] **Retry Logic**
+  - Implement exponential backoff
+  - Add retry limit configuration
+  - Create retry state management
+
+- [ ] **Telemetry**
+  - Add error reporting
+  - Implement success/failure metrics
+  - Create debugging information
+
+#### Acceptance Criteria
+- [ ] Errors are properly categorized
+- [ ] Retry logic works with backoff
+- [ ] Telemetry provides useful insights
+- [ ] Debugging information is comprehensive
+
+### 3.3 Performance Optimization
+
+**Priority:** LOW
+
+#### Requirements
+- Database query optimization
+- Memory usage optimization
+- Battery usage optimization
+
+#### Implementation Tasks
+- [ ] **Database Optimization**
+  - Add database indexes
+  - Optimize query performance
+  - Implement connection pooling
+
+- [ ] **Memory Optimization**
+  - Reduce memory footprint
+  - Implement object pooling
+  - Add memory usage monitoring
+
+- [ ] **Battery Optimization**
+  - Minimize background CPU usage
+  - Optimize network requests
+  - Add battery usage tracking
+
+#### Acceptance Criteria
+- [ ] Database queries are optimized
+- [ ] Memory usage is minimized
+- [ ] Battery usage is optimized
+- [ ] Performance metrics are tracked
+
+---
+
+## Implementation Guidelines
+
+### Development Standards
+- **Code Quality:** Follow existing code style and documentation standards
+- **Testing:** Write unit tests for all new functionality
+- **Documentation:** Update documentation for all API changes
+- **Logging:** Add comprehensive logging with proper tagging
+- **Security:** Follow security best practices for database access
+
+### Testing Requirements
+- **Unit Tests:** All new methods must have unit tests
+- **Integration Tests:** Test database sharing functionality
+- **Platform Tests:** Test on Android, iOS, and Electron
+- **Edge Cases:** Test TTL violations, network failures, and recovery scenarios
+
+### Documentation Updates
+- **API Documentation:** Update TypeScript definitions
+- **Implementation Guide:** Update implementation documentation
+- **Troubleshooting:** Add troubleshooting guides for common issues
+- **Examples:** Create usage examples for new features
+
+---
+
+## Success Metrics
+
+### Phase 1 Success Criteria
+- [ ] SQLite database sharing works reliably
+- [ ] TTL-at-fire enforcement prevents stale notifications
+- [ ] Rolling window ensures closed-app delivery
+- [ ] Configuration API supports all required options
+
+### Phase 2 Success Criteria
+- [ ] iOS background tasks run at T-lead
+- [ ] Android fallback works seamlessly
+- [ ] Electron notifications work while running
+- [ ] All platforms support the unified API
+
+### Phase 3 Success Criteria
+- [ ] ETag support improves network efficiency
+- [ ] Error handling is comprehensive and robust
+- [ ] Performance is optimized across all platforms
+- [ ] System meets all specification requirements
+
+---
+
+## Risk Mitigation
+
+### Technical Risks
+- **Database Compatibility:** Test schema version checking thoroughly
+- **Platform Differences:** Implement platform-specific fallbacks
+- **Background Execution:** Handle iOS background execution limitations
+- **Permission Changes:** Monitor Android permission policy changes
+
+### Implementation Risks
+- **Scope Creep:** Stick to specification requirements
+- **Testing Coverage:** Ensure comprehensive testing
+- **Documentation:** Keep documentation up-to-date
+- **Performance:** Monitor performance impact
+
+---
+
+## Conclusion
+
+This roadmap provides a structured approach to completing the Daily Notification Plugin implementation. Phase 1 addresses the critical infrastructure gaps, Phase 2 completes platform-specific functionality, and Phase 3 optimizes the system for production use.
+
+The implementation should follow the existing code patterns and maintain the high quality standards established in the current codebase. Regular testing and documentation updates are essential for success.
+
+**Next Steps:**
+1. Review and approve this roadmap
+2. Begin Phase 1 implementation
+3. Set up testing infrastructure
+4. Create implementation tracking system