🏗️ Architecture: Where should the semantic model of a generated platform live...

Date: 2026-03-08
Time: 01:04:00 UTC
Session: gspace1-188.4
Agent: backend
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

Where should the semantic model of a generated platform live, and how should the visual canvas render it?

Task: S188: Structure-as-Blueprint — semantic model for visual canvas

🎯 Decision Made

Chosen:

Universe.structure[] in MongoDB is the living blueprint. It's a semantic JSON tree (V2 nodes: module→page→widget) that mirrors the generated platform. Both the visual canvas and Vitto AI read from it. Git holds runnable code. MongoDB holds the semantic model. They sync during generation: DEPLOY phase builds V2 nodes from ExecuteResult → PATCHes universe doc → emits SSE event → frontend UniverseStructureStateService updates signal → canvas re-renders.

Options Considered:

1. Continue using VFS (disk files) as source of truth for canvas
2. Store structure in a separate collection per universe
3. Use Universe.structure[] field in MongoDB as living blueprint (chosen)
4. Store structure in Redis for real-time performance

💭 Reasoning

Root cause of the empty studio: Universe.structure[] was NEVER populated after generation. The DEPLOY phase persisted modules to backend-ai-api and wrote files to disk, but never updated the universe document's structure tree. The VFS (Virtual File System) was reading from local disk /modules/ folder — wrong for production. The structure[] field already existed on the Universe interface with moduleTreeVersion for cache busting. The fix: buildV2StructureNodes() converts ExecuteResult into UniverseStructureNode[] with V2 types, then calls PUT /spaces/:spaceId/universes/:universeId via backendAiClient.httpRequest('api',...). This is groundbreaking for AI intelligence: every universe has a queryable semantic tree. Vitto can learn patterns across platforms ('restaurants always have menu+orders+reservations'). Cross-platform queries become trivial (db.universes.find({'structure.entities': 'Player'})).

📁 Files Involved

• APIs/backend-vitto-api/src/app/module-generation/phases/module-gen-phase.executor.ts
• libs/libs-structural/vitto-studio/src/lib/services/universe-structure-state.service.ts
• libs/libs-structural/vitto-studio/src/lib/panels/visual-canvas-panel.component.ts
• libs/libs-foundational/core-models/src/lib/types/space.types.ts

🔗 Related

• Decision ID: dev_1772931840496_q3tgqe0
• Session: 188
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation