Backend Vitto Api Architecture

Ecosistema completo para organización y gestión de contenido con interfaces espaciales

Backend Vitto API — Architecture & AI Agent Guide

Purpose: Source of truth for backend-vitto-api structure, module boundaries, and refactoring guidance.
Audience: AI agents and developers extending or maintaining the Vitto super-agent backend.
Updated: March 2026 — Post Global Engineering Standard refactor (Session 214)

Overview

backend-vitto-api (port 3003) is the Vitto super-agent backend. It orchestrates:

Architecture

APIs/backend-vitto-api/src/app/
├── engine/                    # Core brain — orchestration, phases, context
│   ├── controllers/          # VittoCoreController, domain controllers
│   ├── context-assembly/     # Prompt assembly, channel/web builders
│   ├── phase-executor/       # Phase-specific prompt building
│   ├── orchestration/        # Vitto config factory
│   └── adapters/              # Channel adapters (WhatsApp, Web)
├── mind/                      # Memory, knowledge, intelligence
│   └── memory/               # Memory sub-services (store, recall, embedding)
├── connectivity/              # Channel gateway, WebSocket, handoff
├── llm/                       # Smart routing, provider factory
├── tools/                     # Tool registry (plugin-based)
├── module-generation/         # Module spec → code generation
├── awareness/                 # Proactive awareness channels
├── proactive/                 # Proactive monitoring
├── security/                  # Resilience, DLQ
└── a2a/                       # Google A2A protocol bridge

Module Boundaries

Module Responsibility Key Services
Engine Task lifecycle, phases, context assembly, channel processing VittoEngineService, PhaseExecutorService, ContextAssemblyService
Mind Memory, recall, embeddings, knowledge graph VittoMemoryService, VisualMemoryService
Connectivity Channels, WebSocket, handoff to backend-ai-api ChannelGatewayService
LLM Model routing, provider selection SmartRouterService, ProviderFactoryService
Tools Tool registry (plugins), handlers ToolRegistryService
Module Generation Spec → Nx library code ModuleGenPhaseExecutor, AutoCorrectionService

Key Refactor Patterns (Session 214)

  1. Controllers: Split by domain (e.g. VittoCoreController, tool utilities)
  2. Services: Extract sub-services when >500 lines; keep orchestrator thin
  3. Context Assembly: context-assembly/ — ChannelPromptBuilder, WebPromptBuilder, EmotionalContext
  4. Memory: mind/memory/ — Store, Recall, HotCache, Importance, Embedding
  5. Tools: Plugin-based registry with tools/plugins/
  6. Auto-correction: Strategy pattern under validation/corrections/strategies/

File Size Guidelines

Target Max Lines Action
Services ~400 Extract sub-services or helpers
Controllers ~300 Split by domain
Utils ~200 Split by concern

Extending the Codebase

Adding a new awareness channel

  1. Implement AwarenessChannel in awareness/channels/
  2. Register in AwarenessModule
  3. See docs/english/GoGrab-Space/architecture/ for awareness design

Adding a new tool

  1. Create plugin in tools/plugins/
  2. Register in plugins.index.ts
  3. Add handler if needed in tools/handlers/

Adding a new module generation correction

  1. Add strategy in module-generation/validation/corrections/strategies/
  2. Register in correction rules

Dependencies

Testing

Common Test Fixes

Error Fix
Cannot resolve dependencies of X (?). Please make sure that the argument Y at index [n] is available Add { provide: Y, useValue: mockY } or { provide: getModelToken(Schema.name), useValue: mockModel } to providers
sseSubject.complete() → Cannot read properties of undefined Use sseSubject?.complete() in afterEach — sseSubject may be undefined if beforeEach fails
VittoMemoryService not found Provide by class: { provide: VittoMemoryService, useValue: mockMemoryService } (not string token)
GenerationEventDocModel not found Add { provide: getModelToken(GenerationEventDoc.name), useValue: mockEventModel }
TrustEscalationService not found Add { provide: TrustEscalationService, useValue: { getTrustLevel: jest.fn().mockResolvedValue(null), getTrustScore: jest.fn().mockResolvedValue(null) } }

Segregation Checklist

When adding or refactoring:

Documentation References