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

Date: 2026-03-03
Time: 17:58:23 UTC
Session: gspace1-166.8
Agent: storage
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How to evolve storage-system from chat-specific sync to a universal persistence layer any feature can use with minimal code?

Task: Session 166.3: Storage system evolution to universal persistence layer

🎯 Decision Made

Chosen:

Built BackendSyncEngine in @storage-system/sync/backend-sync — generic engine parameterized by SyncDescriptor (5-line descriptor per feature). Added syncToBackend() companion for autoFlashState (1-line opt-in). Added StorageObservabilityService (queue depth, quota, cache metrics, Prometheus export). Hardened state versioning with rollback safety (preserve known fields on downgrade) + cross-tab migration coordination via BroadcastChannel. Archived 7 deprecated docs, created new backend-sync guide.

Options Considered:

• No alternatives documented

💭 Reasoning

ChatBackendSyncService was 490 lines of 80% generic logic (retry queue, drain, backoff, dedup) hardcoded to chat. Extracting to BackendSyncEngine means any feature gets the same resilience by registering a 5-line SyncDescriptor. The SYNC_TRANSPORT_FN injection token keeps @storage-system free of HttpClient dependency (clean architecture). syncToBackend() companion uses Angular effect() to watch signals — consumers don't need to know about the engine internals. StorageObservabilityService fills a production gap: zero visibility into sync queue health, storage quota, or cache performance before this. State versioning rollback safety fixes a real bug: deployment rollbacks nuked all user data (returned defaultValue). Now it preserves known fields.

📁 Files Involved

• libs/libs-foundational/storage-system/src/sync/backend-sync/services/backend-sync-engine.service.ts
• libs/libs-foundational/storage-system/src/sync/backend-sync/helpers/sync-to-backend.ts
• libs/libs-foundational/storage-system/src/sync/backend-sync/models/backend-sync.types.ts
• libs/libs-foundational/storage-system/src/sync/backend-sync/tokens/backend-sync.tokens.ts
• libs/libs-foundational/storage-system/src/sync/backend-sync/providers/provide-backend-sync.ts
• libs/libs-foundational/storage-system/src/sync/observability/services/storage-observability.service.ts
• libs/libs-foundational/storage-system/src/flash/utils/state-versioning.ts
• docs/english/GoGrab-Space/docs.libs/docs.libs-foundational/storage-system/implementation/backend-sync/overview.md

🔗 Related

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

Auto-generated by MCP Smart Consolidation