Browse Source
- 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(-)research/notification-plugin-enhancement
Matthew Raymer
1 week ago
7 changed files with 903 additions and 13 deletions
@ -0,0 +1,96 @@ |
|||||
|
--- |
||||
|
title: Documentation, References, and Model Agent Use |
||||
|
version: 1.1 |
||||
|
alwaysApply: true |
||||
|
scope: code, project-plans |
||||
|
--- |
||||
|
|
||||
|
# Directive on Documentation, References, and Model Agent Use in Code and Project Plans |
||||
|
|
||||
|
To ensure clarity, efficiency, and high-value documentation within code and project plans—and to leverage **model agents** (AI- or automation-based assistants) effectively—contributors must follow these rules: |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 1. Documentation and References Must Add Clear Value |
||||
|
|
||||
|
- Only include documentation, comments, or reference links when they provide _new, meaningful information_ that assists understanding or decision-making. |
||||
|
- Avoid duplicating content already obvious in the codebase, version history, or linked project documents. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 2. Eliminate Redundant or Noisy References |
||||
|
|
||||
|
- Remove references that serve no purpose beyond filling space. |
||||
|
- Model agents may automatically flag and suggest removal of trivial references (e.g., links to unchanged boilerplate or self-evident context). |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 3. Explicit Role of Model Agents |
||||
|
|
||||
|
Model agents are **active participants** in documentation quality control. Their tasks include: |
||||
|
|
||||
|
- **Relevance Evaluation**: Automatically analyze references for their substantive contribution before inclusion. |
||||
|
- **Redundancy Detection**: Flag duplicate or trivial references across commits, files, or tasks. |
||||
|
- **Context Linking**: Suggest appropriate higher-level docs (designs, ADRs, meeting notes) when a code change touches multi-stage or cross-team items. |
||||
|
- **Placement Optimization**: Recommend centralization of references (e.g., in plan overviews, ADRs, or merge commit messages) rather than scattered low-value inline references. |
||||
|
- **Consistency Monitoring**: Ensure references align with team standards (e.g., ADR template, architecture repo, or external policy documents). |
||||
|
|
||||
|
Contributors must treat agent recommendations as **first-pass reviews** but remain accountable for final human judgment. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 4. Contextual References for Complex Items |
||||
|
|
||||
|
- Use **centralized references** for multi-stage features (e.g., architectural docs, research threads). |
||||
|
- Keep inline code comments light; push broader context into centralized documents. |
||||
|
- Model agents may auto-summarize complex chains of discussion and attach them as a single reference point. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 5. Centralization of Broader Context |
||||
|
|
||||
|
- Store overarching context (design docs, proposals, workflows) in accessible, well-indexed places. |
||||
|
- Model agents should assist by **generating reference maps** that track where docs are cited across the codebase. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 6. Focused Documentation |
||||
|
|
||||
|
- Documentation should explain **why** and **how** decisions are made, not just what was changed. |
||||
|
- Model agents can auto-generate first-pass explanations from commit metadata, diffs, and linked issues—but humans must refine them for accuracy and intent. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 7. Review and Accountability |
||||
|
|
||||
|
- Reviewers and team leads must reject submissions containing unnecessary or low-quality documentation. |
||||
|
- Model agent outputs are aids, not replacements—contributors remain responsible for **final clarity and relevance**. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 8. Continuous Improvement and Agent Feedback Loops |
||||
|
|
||||
|
- Encourage iterative development of model agents so their evaluations become more precise over time. |
||||
|
- Contributions should include **feedback on agent suggestions** (e.g., accepted, rejected, or corrected) to train better future outputs. |
||||
|
- Agents should log patterns of “rejected” suggestions for refinement. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## 9. Workflow Overview (Mermaid Diagram) |
||||
|
|
||||
|
```mermaid |
||||
|
flowchart TD |
||||
|
A[Contributor] -->|Writes Code & Draft Docs| B[Model Agent] |
||||
|
B -->|Evaluates References| C{Relevant?} |
||||
|
C -->|Yes| D[Suggest Placement & Context Links] |
||||
|
C -->|No| E[Flag Redundancy / Noise] |
||||
|
D --> F[Contributor Refines Docs] |
||||
|
E --> F |
||||
|
F --> G[Reviewer] |
||||
|
G -->|Approves / Requests Revisions| H[Final Documentation] |
||||
|
G -->|Feedback on Agent Suggestions| B |
||||
|
``` |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
✅ **Outcome:** By integrating disciplined contributor standards with **model agent augmentation**, the team achieves documentation that is consistently _relevant, concise, centralized, and decision-focused_. AI ensures coverage and noise reduction, while humans ensure precision and judgment. |
||||
@ -0,0 +1,31 @@ |
|||||
|
# Glossary |
||||
|
|
||||
|
**📝 SANITY CHECK IMPROVEMENTS APPLIED:** This document has been updated to accurately reflect current implementation status vs. planned features. |
||||
|
|
||||
|
**T (slot time)** — The local wall-clock time a notification should fire (e.g., 08:00). *See Notification System → Scheduling & T–lead.* |
||||
|
|
||||
|
**T–lead** — The moment **`prefetchLeadMinutes`** before **T** when the system *attempts* a **single** background prefetch. T–lead **controls prefetch attempts, not arming**; locals are pre-armed earlier to guarantee closed-app delivery. *See Notification System → Scheduling & T–lead and Roadmap Phase 2.1.* |
||||
|
|
||||
|
**Lead window** — The interval from **T–lead** up to **T** during which we **try once** to refresh content. It does **not** control arming; we pre-arm earlier. *See Notification System → Scheduling & T–lead.* |
||||
|
|
||||
|
**Rolling window** — Always keep **today's remaining** (and tomorrow if iOS pending caps allow) locals **armed** so the OS can deliver while the app is closed. *See Notification System → Scheduling & T–lead and Roadmap Phase 1.3.* |
||||
|
|
||||
|
**TTL (time-to-live)** — Maximum allowed payload age **at fire time**. If `T − fetchedAt > ttlSeconds`, we **skip** arming for that T. *See Notification System → Policies and Roadmap Phase 1.2.* |
||||
|
|
||||
|
**Shared DB (planned)** — The app and plugin will open the **same SQLite file**; the app owns schema/migrations, the plugin performs short writes with WAL. *Currently using SharedPreferences/UserDefaults.* *See Notification System → Storage and Roadmap Phase 1.1.* |
||||
|
|
||||
|
**WAL (Write-Ahead Logging)** — SQLite journaling mode that permits concurrent reads during writes; recommended for foreground-read + background-write. *See Notification System → Storage and Roadmap Phase 1.1.* |
||||
|
|
||||
|
**`PRAGMA user_version`** — An integer the app increments on each migration; the plugin **checks** (does not migrate) to ensure compatibility. *See Notification System → Storage and Roadmap Phase 1.1.* |
||||
|
|
||||
|
**Exact alarm (Android)** — Minute-precise alarm via `AlarmManager.setExactAndAllowWhileIdle`, subject to policy and permission. *See Notification System → Policies and Roadmap Phase 2.2.* |
||||
|
|
||||
|
**Windowed alarm (Android)** — Batched/inexact alarm via `setWindow(start,len)`; we target **±10 minutes** when exact alarms are unavailable. *See Notification System → Policies and Roadmap Phase 2.2.* |
||||
|
|
||||
|
**Delivery-time mutation (iOS)** — Not available for **local** notifications. Notification Service Extensions mutate **remote** pushes only; locals must be rendered before scheduling. *See Notification System → Policies.* |
||||
|
|
||||
|
**Start-on-Login** — Electron feature that automatically launches the application when the user logs into their system, enabling background notification scheduling and delivery after system reboot. *See Roadmap Phase 2.3.* |
||||
|
|
||||
|
**Tiered Storage (current)** — Current implementation uses SharedPreferences (Android) / UserDefaults (iOS) for quick access, in-memory cache for structured data, and file system for large assets. *See Notification System → Storage and Roadmap Phase 1.1.* |
||||
|
|
||||
|
**No delivery-time network:** Local notifications display **pre-rendered content only**; never fetch at delivery. *See Notification System → Policies.* |
||||
@ -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 |
||||
@ -0,0 +1,247 @@ |
|||||
|
# TimeSafari — Native-First Notification System |
||||
|
|
||||
|
**📝 SANITY CHECK IMPROVEMENTS APPLIED:** This document has been updated to clarify current background fetch infrastructure status and iOS implementation completeness. |
||||
|
|
||||
|
**Status:** Ready for implementation |
||||
|
**Date:** 2025-09-07 |
||||
|
**Author:** Matthew Raymer |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Executive Summary |
||||
|
|
||||
|
Ship a **single, Native-First** notification system: OS-scheduled **background prefetch at T–lead** + **pre-armed** local notifications. Web-push is retired. |
||||
|
|
||||
|
### What we deliver |
||||
|
|
||||
|
- **Closed-app delivery:** Pre-armed locals fire even if the app is closed. |
||||
|
- **Freshness:** One prefetch attempt per slot at **T–lead**; ETag/TTL controls; skip when stale. |
||||
|
- **Android precision:** Exact alarms with permission; windowed fallback (±10m) otherwise. |
||||
|
- **Resilience:** Re-arm after reboot/time-change (Android receivers; iOS on next wake/silent push). |
||||
|
- **Cross-platform:** Same TS API (iOS/Android/Electron). Electron is best-effort while running. |
||||
|
|
||||
|
### Success signals |
||||
|
|
||||
|
- High delivery reliability, minute-precision on Android with permission. |
||||
|
- Prefetch budget hit rate at **T–lead**; zero stale deliveries beyond TTL. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Strategic Plan |
||||
|
|
||||
|
### Goal |
||||
|
|
||||
|
Deliver 1..M daily notifications with **OS background prefetch at T–lead** *(see Glossary)* and **rolling-window safety** *(see Glossary)* so messages display with fresh content even when the app is closed. |
||||
|
|
||||
|
### Tenets |
||||
|
|
||||
|
- **Reliability first:** OS delivers once scheduled; no JS at delivery time. |
||||
|
- **Freshness with guardrails:** Prefetch at **T–lead** *(see Glossary)*; enforce **TTL-at-fire** *(see Glossary)*; ETag-aware. |
||||
|
- **Single system:** One TS API; native adapters swap under the hood. |
||||
|
- **Platform honesty:** Android exactness via permission; iOS best-effort budget. |
||||
|
- **No delivery-time network:** Local notifications display **pre-rendered content only**; never fetch at delivery. |
||||
|
|
||||
|
### Architecture (high level) |
||||
|
|
||||
|
App (Vue/TS) → Orchestrator (policy) → Native Adapters: |
||||
|
|
||||
|
- **SchedulerNative** — AlarmManager (Android) / UNUserNotificationCenter (iOS) |
||||
|
- **BackgroundPrefetchNative** — WorkManager (Android) / BGTaskScheduler (+ silent push) (iOS) |
||||
|
- **DataStore** — SQLite |
||||
|
|
||||
|
**Storage:** **Current:** SharedPreferences (Android) / UserDefaults (iOS) + in-memory cache (see Glossary → Tiered Storage). **Planned:** one **shared SQLite** file (see Glossary → Shared DB); the app owns schema/migrations; the plugin opens the same path with **WAL** (see Glossary → WAL); background writes are **short & serialized**. *(Keep the "(Planned)" label until Phase 1 ships.)* |
||||
|
|
||||
|
### SQLite Ownership & Concurrency *(Planned)* |
||||
|
|
||||
|
* **One DB file:** The plugin will open the **same path** the app uses (no second DB). |
||||
|
* **Migrations owned by app:** The app executes schema migrations and bumps `PRAGMA user_version` (see Glossary → PRAGMA user_version). The plugin **never** migrates; it **asserts** the expected version. |
||||
|
* **WAL mode:** Open DB with `journal_mode=WAL`, `synchronous=NORMAL`, `busy_timeout=5000`, `foreign_keys=ON`. WAL (see Glossary → WAL) allows foreground reads while a background job commits quickly. |
||||
|
* **Single-writer discipline:** Background jobs write in **short transactions** (UPSERT per slot), then return. |
||||
|
* **Encryption (optional):** If using SQLCipher, the **same key** is used by both app and plugin. Do not mix encrypted and unencrypted openings. |
||||
|
|
||||
|
*Note: Currently using SharedPreferences (Android) / UserDefaults (iOS) with in-memory cache. See Implementation Roadmap → Phase 1.1 for migration steps.* |
||||
|
|
||||
|
### Scheduling & T–lead *(Planned)* |
||||
|
|
||||
|
- Arm **rolling window** (see Glossary → Rolling window). **(Planned)** |
||||
|
- Exactly **one** online-first fetch at **T–lead** (see Glossary → T–lead) with **12s** timeout; **ETag/304** respected. **(Planned)** |
||||
|
- If fresh **and** within **TTL-at-fire** (see Glossary → TTL), (re)arm; otherwise keep prior content. **(Planned)** |
||||
|
- If the OS skips the wake, the pre-armed local still fires from cache. **(Planned)** |
||||
|
|
||||
|
*Note: Current implementation has basic scheduling and WorkManager infrastructure (Android) but lacks T–lead prefetch logic, rolling window logic, and iOS background tasks. See Implementation Roadmap → Phase 1-2.* |
||||
|
|
||||
|
### Policies *(Mixed Implementation)* |
||||
|
|
||||
|
- **TTL-at-fire** (see Glossary → TTL): Before arming for T, if `(T − fetchedAt) > ttlSeconds` → **skip**. **(Planned)** |
||||
|
- **Android exactness** (see Glossary → Exact alarm): **(Partial)** — permission flow exists; finalize ±10m window & deep-link to settings. |
||||
|
- **Reboot/time change:** **(Partial)** — Android receivers partially present; iOS via next wake/silent push. |
||||
|
- **No delivery-time network** (see Glossary → No delivery-time network): Local notifications display **pre-rendered content only**; never fetch at delivery. **(Implemented)** |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Implementation Guide |
||||
|
|
||||
|
### 1) Interfaces (TS stable) |
||||
|
|
||||
|
- **SchedulerNative**: `scheduleExact({slotId, whenMs, title, body, extra})`, `scheduleWindow(..., windowLenMs)`, `cancelBySlot`, `rescheduleAll`, `capabilities()` |
||||
|
- **BackgroundPrefetchNative**: `schedulePrefetch(slotId, atMs)`, `cancelPrefetch(slotId)` |
||||
|
- **DataStore**: SQLite adapters (notif_contents, notif_deliveries, notif_config) |
||||
|
- **Public API**: `configure`, `requestPermissions`, `runFullPipelineNow`, `reschedule`, `getState` |
||||
|
|
||||
|
### DB Path & Adapter Configuration *(Planned)* |
||||
|
|
||||
|
* **Configure option:** `dbPath: string` (absolute path or platform alias) will be passed from JS to the plugin during `configure()`. |
||||
|
* **Shared tables:** |
||||
|
|
||||
|
* `notif_contents(slot_id, payload_json, fetched_at, etag, …)` |
||||
|
* `notif_deliveries(slot_id, fire_at, delivered_at, status, error_code, …)` |
||||
|
* `notif_config(k, v)` |
||||
|
* **Open settings:** |
||||
|
|
||||
|
* `journal_mode=WAL` |
||||
|
* `synchronous=NORMAL` |
||||
|
* `busy_timeout=5000` |
||||
|
* `foreign_keys=ON` |
||||
|
|
||||
|
*Note: Currently using SharedPreferences/UserDefaults (see Glossary → Tiered Storage). Database configuration is planned for Phase 1.* |
||||
|
|
||||
|
See **Implementation Roadmap → Phase 1.1** for migration steps and schema. |
||||
|
|
||||
|
**Type (TS) extension** *(Planned)* |
||||
|
|
||||
|
```ts |
||||
|
export type ConfigureOptions = { |
||||
|
// …existing fields… |
||||
|
dbPath: string; // shared DB file the plugin will open |
||||
|
storage: 'shared'; // canonical value; plugin-owned DB is not used |
||||
|
}; |
||||
|
``` |
||||
|
|
||||
|
*Note: Current `NotificationOptions` interface exists but lacks `dbPath` configuration. This will be added in Phase 1.* |
||||
|
|
||||
|
**Plugin side (pseudo)** |
||||
|
|
||||
|
```kotlin |
||||
|
// Android open |
||||
|
val db = SQLiteDatabase.openDatabase(dbPath, null, SQLiteDatabase.OPEN_READWRITE) |
||||
|
db.execSQL("PRAGMA journal_mode=WAL") |
||||
|
db.execSQL("PRAGMA synchronous=NORMAL") |
||||
|
db.execSQL("PRAGMA foreign_keys=ON") |
||||
|
db.execSQL("PRAGMA busy_timeout=5000") |
||||
|
// Verify schema version |
||||
|
val uv = rawQuery("PRAGMA user_version").use { it.moveToFirst(); it.getInt(0) } |
||||
|
require(uv >= MIN_EXPECTED_VERSION) { "Schema version too old" } |
||||
|
``` |
||||
|
|
||||
|
```swift |
||||
|
// iOS open (FMDB / SQLite3) |
||||
|
// Set WAL via PRAGMA after open; check user_version the same way. |
||||
|
``` |
||||
|
|
||||
|
### 2) Templating & Arming |
||||
|
|
||||
|
- Render `title/body` **before** scheduling; pass via **SchedulerNative**. |
||||
|
- Route all arming through **SchedulerNative** to centralize Android exact/window semantics. |
||||
|
|
||||
|
### 3) T–lead (single attempt) |
||||
|
|
||||
|
**T–lead governs prefetch, not arming.** We **arm** one-shot locals as part of the rolling window so closed-app delivery is guaranteed. At **T–lead = T − prefetchLeadMinutes**, the **native background job** attempts **one** 12s ETag-aware fetch. If fresh content arrives and will not violate **TTL-at-fire**, we (re)arm the upcoming slot; if the OS skips the wake, the pre-armed local still fires with cached content. |
||||
|
|
||||
|
- Compute T–lead = `whenMs - prefetchLeadMinutes*60_000`. |
||||
|
- `BackgroundPrefetchNative.schedulePrefetch(slotId, atMs=T–lead)`. |
||||
|
- On wake: **ETag** fetch (timeout **12s**), persist, optionally cancel & re-arm if within TTL. |
||||
|
- Never fetch at delivery time. |
||||
|
|
||||
|
### 4) TTL-at-fire |
||||
|
|
||||
|
**TTL-at-fire:** Before arming for time **T**, compute `T − fetchedAt`. If that exceeds `ttlSeconds`, **do not arm** (skip). This prevents posting stale notifications when the app has been closed for a long time. |
||||
|
|
||||
|
`if (whenMs - fetchedAt) > ttlSeconds*1000 → skip` |
||||
|
|
||||
|
### 5) Android specifics |
||||
|
|
||||
|
- Request `SCHEDULE_EXACT_ALARM`; deep-link if denied; fallback to `setWindow(start,len)` (±10m). |
||||
|
- Receivers: `BOOT_COMPLETED`, `TIMEZONE_CHANGED`, `TIME_SET` → recompute & re-arm for next 24h and schedule T–lead prefetch. |
||||
|
|
||||
|
### 6) iOS specifics |
||||
|
|
||||
|
- `BGTaskScheduler` for T–lead prefetch (best-effort). Optional silent push nudge. |
||||
|
- Locals: `UNCalendarNotificationTrigger` (one-shots); no NSE mutation for locals. |
||||
|
|
||||
|
### 7) Network & Timeouts |
||||
|
|
||||
|
- Content fetch: **12s** timeout; single attempt at T–lead; ETag/304 respected. |
||||
|
- ACK/Error: **8s** timeout, fire-and-forget. |
||||
|
|
||||
|
### 8) Electron |
||||
|
|
||||
|
- Notifications while app is running; recommend **Start-on-Login**. No true background scheduling when fully closed. |
||||
|
|
||||
|
### 9) Telemetry |
||||
|
|
||||
|
- Record `scheduled|shown|error`; ACK deliveries (8s timeout); include slot/times/TZ/app version. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Capability Matrix |
||||
|
|
||||
|
| Capability | Android (Native) | iOS (Native) | Electron | Web | |
||||
|
|---|---|---|---|---| |
||||
|
| Multi-daily locals (closed app) | ✅ | ✅ | ✅ (app running) | — | |
||||
|
| Prefetch at T–lead (app closed) | ✅ WorkManager | ⚠️ BGTask (best-effort) | ✅ (app running) | — | |
||||
|
| Re-arm after reboot/time-change | ✅ Receivers | ⚠️ On next wake/silent push | ✅ Start-on-Login | — | |
||||
|
| Minute-precision alarms | ✅ with exact permission | ❌ not guaranteed | ✅ timer best-effort | — | |
||||
|
| Delivery-time mutation for locals | ❌ | ❌ | — | — | |
||||
|
| ETag/TTL enforcement | ✅ | ✅ | ✅ | — | |
||||
|
| Rolling-window safety | ✅ | ✅ | ✅ | — | |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Acceptance Criteria |
||||
|
|
||||
|
### Core |
||||
|
|
||||
|
- **Closed-app delivery:** Armed locals fire at T with last rendered content. No delivery-time network. |
||||
|
- **T–lead prefetch:** Single background attempt at **T–lead**; if skipped, delivery still occurs from cache. |
||||
|
- **TTL-at-fire:** No armed local violates TTL at T. |
||||
|
|
||||
|
### Android |
||||
|
|
||||
|
- **Exact permission path:** With `SCHEDULE_EXACT_ALARM` → within ±1m; else **±10m** window. |
||||
|
- **Reboot recovery:** After reboot, receivers re-arm next 24h and schedule T–lead prefetch. |
||||
|
- **TZ/DST change:** Recompute & re-arm; future slots align to new wall-clock. |
||||
|
|
||||
|
### iOS |
||||
|
|
||||
|
- **BGTask budget respected:** Prefetch often runs but may be skipped; delivery still occurs via rolling window. |
||||
|
- **Force-quit caveat:** No background execution after user terminate; delivery still occurs if pre-armed. |
||||
|
|
||||
|
### Electron |
||||
|
|
||||
|
- **Running-app rule:** Delivery only while app runs; with Start-on-Login, after reboot the orchestrator re-arms and subsequent slots deliver. |
||||
|
|
||||
|
### Network |
||||
|
|
||||
|
- Content fetch timeout **12s**; ACK/Error **8s**; no retries inside lead; ETag honored. |
||||
|
|
||||
|
### Observability |
||||
|
|
||||
|
- Log/telemetry for `scheduled|shown|error`; ACK payload includes slot, times, device TZ, app version. |
||||
|
|
||||
|
### DB Sharing *(Planned)* |
||||
|
|
||||
|
* **Shared DB visibility:** A background prefetch writes `notif_contents`; the foreground UI **immediately** reads the same row. |
||||
|
* **WAL overlap:** With the app reading while the plugin commits, no user-visible blocking occurs. |
||||
|
* **Version safety:** If `user_version` is behind, the plugin emits an error and does not write (protects against partial installs). |
||||
|
|
||||
|
*Note: Currently using SharedPreferences/UserDefaults with in-memory cache. SQLite sharing is planned for Phase 1.* |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Web-Push Cleanup |
||||
|
|
||||
|
Web-push functionality has been retired due to unreliability. All web-push related code paths and documentation sections should be removed or marked as deprecated. See `web-push-cleanup-guide.md` for detailed cleanup steps. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
_This document consolidates the Native-First notification system strategy, implementation details, capabilities, and acceptance criteria into a single comprehensive reference._ |
||||
Binary file not shown.
Binary file not shown.
Loading…
Reference in new issue