🏗️ Architecture: How should UserDossier be extended for proactive intelligenc...

Date: 2026-03-13
Time: 00:10:20 UTC
Session: gspace1-210.9
Agent: backend
Confidence: 94%
Status: ✅ Documented

📋 Decision Context

Question:

How should UserDossier be extended for proactive intelligence and bidirectional sync without breaking existing documents?

Task: S210.4: Dossier schema enhancement for proactive intelligence

🎯 Decision Made

Chosen:

Add 4 new @Prop fields with defaults (proactivePreferences, skillPreferences, subscriptionTier, syncMetadata) to UserDossier schema. Mongoose defaults only apply on .create(), not .findOne() — existing docs will have undefined for new fields. All consumer code handles undefined gracefully via optional chaining. DossierSyncService uses 15-min cron with pendingSyncFields tracking for outbound enrichment push. Staleness re-hydration fires on getDossierForPrompt() when lastSyncFromGograb > 24h.

Options Considered:

1. Option A: MongoDB migration script to backfill existing documents with defaults
2. Option B: Add fields with @Prop defaults, handle undefined in consumers via optional chaining
3. Option C: Create a separate ProactivePreferences collection per user

💭 Reasoning

Option B was chosen because: (1) Zero-downtime — no migration script needed, new fields appear naturally as dossiers are accessed; (2) Mongoose defaults apply on .create() (new users get defaults immediately), while existing users get undefined which all consumer code handles via prefs?.field pattern; (3) Keeping all user knowledge in one document (dossier) avoids cross-collection joins and maintains the single-document-per-user architecture established in S196; (4) The syncMetadata.pendingSyncFields tracking is elegant — only dirty fields trigger outbound sync, avoiding unnecessary API calls. A separate collection (Option C) would require joins and duplicate the userId index. A migration (Option A) would require downtime and risk on production data.

📁 Files Involved

• APIs/backend-vitto-api/src/app/users/schemas/user-dossier.schema.ts
• APIs/backend-vitto-api/src/app/users/user-dossier.service.ts
• APIs/backend-vitto-api/src/app/users/dossier-sync.service.ts

🔗 Related

• Decision ID: dev_1773360619960_snlbbzj
• Session: 210
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation