trent_larson/daily-notification-plugin
4
0
Fork 0
Code Issues Pull Requests 2 Projects Releases Wiki Activity

chore: document formatting rules

Browse Source
This commit is contained in:
Matthew Raymer
2025-09-22 07:27:01 +00:00
parent 4b8f936247
commit fcc4e52d5d
12 changed files with 196 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
doc/implementation-roadmap.md
View File

@@ -14,6 +14,7 @@
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
@@ -25,14 +26,18 @@ This document outlines the implementation roadmap to bring the current Daily Not
## 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
@@ -48,6 +53,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
**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)
@@ -55,6 +61,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- **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)
@@ -73,6 +80,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- Extend existing `NotificationOptions` with database settings
- [ ] **Database Schema**
```sql
-- notif_contents: keep history, newest-first reads
CREATE TABLE IF NOT EXISTS notif_contents(
@@ -104,6 +112,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
```
#### Acceptance Criteria
- [ ] App and plugin can open the same SQLite file
- [ ] WAL mode enables concurrent reads during writes
- [ ] Schema version checking prevents compatibility issues
@@ -118,6 +127,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
**Priority:** CRITICAL
#### Requirements
- Skip arming notifications if `(T - fetchedAt) > ttlSeconds` (see Glossary → TTL)
- Validate freshness before scheduling
- Log TTL violations for debugging
@@ -125,6 +135,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- **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`
@@ -143,6 +154,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- 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
@@ -155,12 +167,14 @@ This document outlines the implementation roadmap to bring the current Daily Not
**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
@@ -178,6 +192,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- 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
@@ -189,12 +204,14 @@ This document outlines the implementation roadmap to bring the current Daily Not
**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
@@ -206,6 +223,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- Create path validation logic
#### Acceptance Criteria
- [ ] `dbPath` can be configured via API
- [ ] Path resolution works on all platforms
- [ ] Configuration validation prevents invalid paths
@@ -221,6 +239,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
**Priority:** HIGH
#### Requirements
- `BGTaskScheduler` for T-lead prefetch (see Glossary → T–lead)
- Silent push nudge support
- Background execution budget management
@@ -230,6 +249,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- 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
@@ -246,6 +266,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- 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
@@ -257,12 +278,14 @@ This document outlines the implementation roadmap to bring the current Daily Not
**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
@@ -279,6 +302,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- Implement fallback logging
#### Acceptance Criteria
- [ ] Windowed alarms target ±10 minute windows
- [ ] Reboot recovery re-arms next 24h
- [ ] Time change recovery recomputes schedules
@@ -290,11 +314,13 @@ This document outlines the implementation roadmap to bring the current Daily Not
**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
@@ -306,6 +332,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- Add fallback mechanisms
#### Acceptance Criteria
- [ ] Notifications work while app is running
- [ ] Start-on-Login enables post-reboot delivery
- [ ] Limitations are clearly documented
@@ -322,11 +349,13 @@ This document outlines the implementation roadmap to bring the current Daily Not
**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
@@ -343,6 +372,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- Add network efficiency metrics
#### Acceptance Criteria
- [ ] ETag headers are sent with requests
- [ ] 304 responses are handled correctly
- [ ] Network efficiency is improved
@@ -353,11 +383,13 @@ This document outlines the implementation roadmap to bring the current Daily Not
**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
@@ -374,6 +406,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- Create debugging information
#### Acceptance Criteria
- [ ] Errors are properly categorized
- [ ] Retry logic works with backoff
- [ ] Telemetry provides useful insights
@@ -384,11 +417,13 @@ This document outlines the implementation roadmap to bring the current Daily Not
**Priority:** LOW
#### Requirements
- Database query optimization
- Memory usage optimization
- Battery usage optimization
#### Implementation Tasks
- [ ] **Database Optimization**
- Add database indexes
- Optimize query performance
@@ -405,6 +440,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
- Add battery usage tracking
#### Acceptance Criteria
- [ ] Database queries are optimized
- [ ] Memory usage is minimized
- [ ] Battery usage is optimized
@@ -415,6 +451,7 @@ This document outlines the implementation roadmap to bring the current Daily Not
## 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
@@ -422,12 +459,14 @@ This document outlines the implementation roadmap to bring the current Daily Not
- **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
@@ -438,18 +477,21 @@ This document outlines the implementation roadmap to bring the current Daily Not
## 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
@@ -460,12 +502,14 @@ This document outlines the implementation roadmap to bring the current Daily Not
## 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
@@ -480,6 +524,7 @@ This roadmap provides a structured approach to completing the Daily Notification
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