consolidate: Merge all analysis documents into single BACKGROUND_DATA_FETCHING_PLAN.md
- Consolidated DATABASE_ACCESS_CLARIFICATION.md content into main plan - Consolidated ACTIVE_DID_CHANGE_REQUIREMENTS.md content into main plan - Consolidated TIMESAFARI_INTEGRATION_ANALYSIS.md content into main plan - Enhanced main document with Option A architecture overview - Added comprehensive TimeSafari integration patterns section - Added critical requirement section for activeDid change detection - Added event-based solution implementation details - Updated README.md to reference single consolidated document - Eliminated unnecessary document proliferation as requested The BACKGROUND_DATA_FETCHING_PLAN.md now serves as the single source of truth for all implementation guidance, containing Option A architecture, TimeSafari integration patterns, activeDid change management, and platform-specific details.
This commit is contained in:
Matthew Raymer
@@ -3,26 +3,48 @@
|
||||
**Author**: Matthew Raymer
|
||||
**Version**: 1.0.0
|
||||
**Created**: 2025-10-02 07:47:04 UTC
|
||||
**Last Updated**: 2025-10-02 12:30:00 UTC
|
||||
**Last Updated**: 2025-10-02 12:45:00 UTC
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the implementation plan for background data fetching in the Capacitor Daily Notification Plugin, replacing web push implementations with native platform solutions. The plan covers Android, iOS, and cross-platform considerations for API data fetching with authentication.
|
||||
This document outlines the **complete implementation plan** for background data fetching in the Capacitor Daily Notification Plugin, replacing web push implementations with native platform solutions. This consolidated plan includes:
|
||||
|
||||
## Platform Architecture Overview
|
||||
- **Option A Architecture**: Host always provides activeDid approach
|
||||
- **TimeSafari Integration**: PlatformServiceMixin coordination patterns
|
||||
- **Cross-Platform Implementation**: Android/Electron, iOS, Web specifications
|
||||
- **Database Access Patterns**: Clear separation between host and plugin storage
|
||||
- **ActiveDid Change Management**: Event-based notification and cache invalidation
|
||||
- **Security Requirements**: Data isolation and authentication patterns
|
||||
|
||||
This document consolidates all previous analysis documents to provide a single source of truth for implementation.
|
||||
|
||||
## Consolidated Architecture: Option A Platform Overview
|
||||
|
||||
```
|
||||
JavaScript Layer → Native Bridge → Native Background Executor
|
||||
TimeSafari Host App
|
||||
↓ (provides activeDid)
|
||||
Daily Notification Plugin → Native Background Executor
|
||||
↓
|
||||
HTTP Client + Auth
|
||||
↓
|
||||
API Server Response
|
||||
↓
|
||||
Parse & Cache Data
|
||||
Parse & Cache Data (plugin storage)
|
||||
↓
|
||||
Trigger Notifications
|
||||
```
|
||||
|
||||
### **Option A: Host Always Provides activeDid**
|
||||
|
||||
**Core Principle**: Host application queries its own database and provides activeDid to plugin.
|
||||
|
||||
### **Why Option A Is Superior:**
|
||||
1. **Clear Separation**: Host owns identity management, plugin owns notifications
|
||||
2. **No Database Conflicts**: Zero shared database access between host and plugin
|
||||
3. **Security Isolation**: Plugin data physically separated from user data
|
||||
4. **Platform Independence**: Works consistently regardless of host's database technology
|
||||
5. **Simplified Implementation**: Fewer moving parts, clearer debugging
|
||||
|
||||
## Android Implementation Strategy
|
||||
|
||||
### A. Background Execution Framework
|
||||
@@ -252,6 +274,85 @@ Based on TimeSafari's optimization patterns:
|
||||
- **Cache cleanup** on memory pressure
|
||||
- **Resource lifecycle** management
|
||||
|
||||
## Critical Requirement: Plugin Must Know When activeDid Changes
|
||||
|
||||
### **Security Implications of Missing ActiveDid Change Detection**
|
||||
|
||||
**Without immediate activeDid change detection, the plugin faces severe risks:**
|
||||
- **Cross-User Data Exposure**: Plugin fetches notifications for wrong user after identity switch
|
||||
- **Unauthorized API Access**: JWT tokens valid for incorrect user context
|
||||
- **Background Task Errors**: Content fetching operates with wrong identity
|
||||
|
||||
### **Event-Based Solution**
|
||||
|
||||
**Host Application Responsibility**: Dispatch `activeDidChanged` event
|
||||
```typescript
|
||||
// TimeSafari PlatformServiceMixin modification
|
||||
async $updateActiveDid(newDid: string | null): Promise<void> {
|
||||
// Update TimeSafari's active_identity table (existing logic)
|
||||
await this.$dbExec(
|
||||
"UPDATE active_identity SET activeDid = ?, lastUpdated = datetime('now') WHERE id = 1",
|
||||
[newDid || ""]
|
||||
);
|
||||
|
||||
// CRITICAL: Notify plugin of change IMMEDIATELY
|
||||
document.dispatchEvent(new CustomEvent('activeDidChanged', {
|
||||
detail: { activeDid: newDid }
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
**Plugin Responsibility**: Listen and respond to changes
|
||||
```typescript
|
||||
// Plugin service layer implementation
|
||||
plugin.onActiveDidChange(async (newActiveDid) => {
|
||||
// 1. Clear all cached content for previous identity
|
||||
await plugin.clearCacheForNewIdentity();
|
||||
|
||||
// 2. Refresh authentication tokens with new activeDid
|
||||
await plugin.refreshAuthenticationForNewIdentity(newActiveDid);
|
||||
|
||||
// 3. Restart background tasks with correct identity
|
||||
await plugin.updateBackgroundTaskIdentity(newActiveDid);
|
||||
|
||||
logger.info(`[DailyNotificationService] ActiveDid updated to: ${newActiveDid}`);
|
||||
});
|
||||
```
|
||||
|
||||
## TimeSafari Integration Patterns
|
||||
|
||||
### **ActiveDid Management Analysis**
|
||||
|
||||
**TimeSafari's Database Architecture:**
|
||||
- **Table**: `active_identity` (single row with `id = 1`)
|
||||
- **Content**: `activeDid TEXT`, `lastUpdated DATETIME`
|
||||
- **Purpose**: Single source of truth for active user identity
|
||||
|
||||
**Access via PlatformServiceMixin:**
|
||||
```typescript
|
||||
// Retrieving activeDid in TimeSafari components
|
||||
const activeIdentity = await this.$getActiveIdentity();
|
||||
const activeDid = activeIdentity.activeDid;
|
||||
|
||||
// Updating activeDid via PlatformServiceMixin
|
||||
async $updateActiveDid(newDid: string | null): Promise<void> {
|
||||
await this.$dbExec(
|
||||
"UPDATE active_identity SET activeDid = ?, lastUpdated = datetime('now') WHERE id = 1",
|
||||
[newDid || ""]
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### **Plugin Hosting Strategy**
|
||||
|
||||
**Existing Plugin Usage**: TimeSafari already uses Capacitor plugins extensively via `CapacitorPlatformService.ts`
|
||||
|
||||
**Recommended Integration Architecture:**
|
||||
- Plugin integrates as standard Capacitor plugin
|
||||
- Host provides activeDid via event-driven pattern
|
||||
- Plugin manages own isolated storage
|
||||
- Clear separation of responsibilities maintained
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Enhanced Plugin Interface for Host Application Integration
|
||||
|
||||
Reference in New Issue
Block a user