🏗️ Architecture: How to evolve the storage system from chat-specific sync to ...

Date: 2026-03-03
Time: 17:21:23 UTC
Session: gspace1-166.7
Agent: storage
Confidence: 93%
Status: ✅ Documented

📋 Decision Context

Question:

How to evolve the storage system from chat-specific sync to a universal persistence layer that any feature can use with one line of code?

Task: Session 166.3: Storage system evolution strategy for universal reuse

🎯 Decision Made

Chosen:

Extract generic BackendSyncEngine from ChatBackendSyncService into @storage-system/sync, parameterized by SyncDescriptor. Create syncToBackend() companion function that pairs with autoFlashState. Keep autoFlashState itself lean (no HTTP deps). ChatBackendSyncService becomes a thin wrapper providing a chat-specific SyncDescriptor. This makes Session 169 codebase-wide migration trivial: each feature just needs autoFlashState() + SyncDescriptor.

Options Considered:

1. Extract generic BackendSyncEngine + syncToBackend() companion
2. Keep per-feature sync services
3. Extend autoFlashState options directly with sync config
4. Adopt RxDB as replacement

💭 Reasoning

4 alternatives evaluated: (1) Generic BackendSyncEngine + syncToBackend() — best balance of reusability and separation of concerns. The retry queue, drain-on-reconnect, exponential backoff, dedup logic is 100% generic. Only the endpoint/payload shape varies per feature. SyncDescriptor captures this variance cleanly. (2) Per-feature sync services — doesn't scale, leads to ChatBackendSyncService + PrefsBackendSyncService + SpaceBackendSyncService etc., all copying the same retry logic. DRY violation. (3) Extend autoFlashState options directly — couples storage library to HttpClient, breaks the clean dependency graph (storage-system has zero HTTP deps today). (4) Adopt RxDB — replaces our entire custom stack, massive migration cost, loses our optimizations (micro-cache, OPFS, BroadcastChannel, intelligent compression). Not practical. The audit found 61% of persistence points (375/619) still use fragmented patterns. The proposed SyncDescriptor approach means each migration in Session 169 is mechanical: replace localStorage/NGXS with autoFlashState + add 5-line SyncDescriptor. No new services needed per feature.

📁 Files Involved

• libs/libs-ai/chat-sync/src/lib/services/chat-backend-sync.service.ts
• libs/libs-foundational/storage-system/src/flash/helpers/auto-flash-state.ts
• libs/libs-foundational/storage-system/src/sync/services/intelligent-sync-engine.ts
• libs/libs-foundational/storage-system/src/sync/services/network-sync-state.service.ts

🔗 Related

• Decision ID: dev_1772558483942_s1w0g37
• Session: 166
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation