Architecture: How should the universe document represent what was generate...

Documentation for Sessions

🏗️ Architecture: How should the universe document represent what was generate...

Date: 2026-03-11
Time: 19:38:34 UTC
Session: gspace1-204.16
Agent: backend
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

How should the universe document represent what was generated? Current state: modules=[], structure=[] after generation completes.

Task: S204.20: Persist rich generation manifest to universe document

🎯 Decision Made

Chosen:

Add generationManifest field to universe document — a comprehensive JSON blob persisted during DEPLOY phase containing: full module specs with entity field definitions, navigation structure, file inventory (paths + languages), quality metrics, and deployment info. buildManifestJSON already had all this data but only sent it via SSE — now also persisted to MongoDB.

Options Considered:

  1. Populate universe.modules[] directly (wrong — those are for user-created modules)
  2. Store full files in MongoDB (too large, duplicates GitLab)
  3. Add generationManifest with structured metadata (chosen)
  4. Only store module IDs and fetch details on demand (too many round trips)

💭 Reasoning

The universe document was essentially blind after generation — Vitto or any agent reading it saw empty modules[] and structure[]. Meanwhile, rich data (entities with fields, routes, embeddables, file paths) existed only in ephemeral SSE events and was lost after phase outputs were cleared (line 827: phase.output = null). The manifest gives any consumer (Vitto chat, Studio UI, agent tools) immediate understanding of what's in the platform without hitting GitLab. Key insight: modules[] stays empty because generated modules live in a separate 'generated-modules' collection on backend-ai-api, not on the universe doc. The generationManifest bridges this gap.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation