🏗️ Architecture: How to implement the Generation Versioning & Draft System sp...

Date: 2026-03-18
Time: 01:25:38 UTC
Session: gspace1-231.6
Agent: backend
Confidence: 90%
Status: ✅ Documented

📋 Decision Context

Question:

How to implement the Generation Versioning & Draft System spec (S231.10) — new GenerationsModule vs extending existing DraftsModule, DEPLOY phase modification strategy, frontend signal architecture?

Task: Implement generation versioning & draft system from spec 2026-03-17

🎯 Decision Made

Chosen:

New GenerationsModule in backend-api with GenerationManifest + DraftSession schemas (separate from existing S49.5 DraftsModule). DEPLOY phase replaces auto-merge with manifest creation POST. Frontend GenerationService with signal-based state, StudioGenerationsPanelComponent as dock panel, VfsSyncService draft branch auto-creation with mutex.

Options Considered:

1. Extend existing DraftsModule with stale status and universe-scoped routes
2. Create DraftSession as separate module from GenerationsModule
3. Keep auto-merge and add manifest as secondary tracking

💭 Reasoning

Existing DraftsModule (S49.5) serves a different purpose: user-initiated branches with preview deployments, version tags, flat routes at @Controller('drafts'). The spec's DraftSession is VFS-initiated, universe-scoped with stale detection — incompatible concerns. Creating a new GenerationsModule keeps the domain cohesive. The DEPLOY phase auto-merge (S230, lines 625-662) is replaced with a manifest creation POST to backend-api, which handles first-gen auto-activate on the backend. VfsSyncService uses a mutex pattern (draftCreationPending + ReplaySubject queue) to prevent concurrent draft branch creation from rapid edits. Frontend uses computed() signals derived from WritableSignal collections — no dual-update problem.

📁 Files Involved

• APIs/backend-api/src/app/generations/generations.service.ts
• APIs/backend-api/src/app/generations/generations.controller.ts
• APIs/backend-api/src/app/generations/generation-manifest.schema.ts
• APIs/backend-api/src/app/generations/draft-session.schema.ts
• APIs/backend-api/src/app/generations/generations.module.ts
• APIs/backend-vitto-api/src/app/module-generation/phases/module-gen-phase.executor.ts
• APIs/backend-vitto-api/src/app/connectivity/backend-api-client.service.ts
• libs/libs-foundational/core-models/src/lib/interfaces/generation.types.ts
• libs/libs-structural/vitto-studio/src/lib/services/generation.service.ts
• libs/libs-structural/vitto-studio/src/lib/panels/generations-panel.component.ts
• libs/libs-structural/vitto-studio/src/lib/services/vfs-sync.service.ts
• libs/libs-structural/vitto-studio/src/lib/services/studio-generation-listener.service.ts
• libs/libs-structural/vitto-studio/src/lib/components/studio-dock-shell/studio-dock-shell.component.ts
• libs/libs-structural/vitto-studio/src/lib/config/studio-dock-panels.config.ts

🔗 Related

• Decision ID: dev_1773797138125_s11ly50
• Session: 231
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation