Vitto Analysis Summary — Up to Session 116

Purpose: This document describes what Vitto is today, what changed since Session 101, what works, what still needs testing, and what remains on the roadmap. It is the single reference for the team to understand, test, and extend Vitto.

Table of Contents

1. What Is Vitto
2. Evolution Timeline
3. Architecture Overview
4. Module Inventory
5. What Changed: Sessions 101 → 116
6. Current Feature Matrix
7. Security Deep-Dive
8. API Reference (117 Endpoints)
9. How to Use Vitto — Developer Guide
10. How to Use Vitto — Space Builders
11. How to Use Vitto — End Users
12. Use Cases
13. Testing Checklist
14. Known Gaps & Roadmap
15. Deployment & Configuration
16. Competitive Positioning vs OpenClaw
17. Vitto Frontend Ecosystem (Session 117)

1. What Is Vitto

Vitto is the central intelligence layer of the GoGrab platform — an autonomous AI agent system that can read code, write code, run builds, deploy websites, coordinate teams of specialized AI agents, manage messaging channels, and learn from every interaction.

What makes Vitto different from a chatbot:

By the numbers (Session 116):

2. Evolution Timeline

Phase 0 — Before Session 98: Basic Chat Agent

Vitto was a simple chat module inside backend-ai-api. No tools, no memory, no autonomy.

Sessions 98-101: The Nervous System Transformation (Phases 1-9)

Extracted into standalone backend-vitto-api on port 3003 with own MongoDB (vitto-mind). Added:

• 4-phase workflow (ANALYZE → PLAN → EXECUTE → VERIFY)
• 10 agentic tools (file I/O, shell, HTTP, handoffs, memory, docs)
• Provider-agnostic LLM layer (Claude, OpenAI, Gemini, DeepSeek)
• Persistent memory (9 MongoDB schemas)
• Proactive monitoring (API health, build health, deployment health)
• Space builder orchestration (10 specialized agents)
• Customer intelligence (intent classification, session management)
• Dynamic skills (runtime-learned procedures)
• 4-tier autonomy (OBSERVE → SUGGEST → DIRECT → AUTONOMOUS)

Sessions 108-113: Library Restructuring & UX Standardization

• 238+ NX libraries reorganized
• 60+ API endpoints added for monitoring, mind explorer, cost tracking
• Channel manager UI + webhook builder in Vitto Command Hub
• 314 passing tests across the platform
• Developer routes moved from gograb-admin to gograb-dev

Sessions 114-115: Vitto Superpower Plan (Phases 1-5)

The "Superpower Plan" was designed to close the gap with OpenClaw while exceeding it on security and UX. 22 new files created in the security module alone:

Session 116: The Wiring Sprint

Critical finding: ~40% of Phase 1-5 security code was "dead" — built, registered in SecurityModule, but never called from any execution path. A 10-item wiring sprint connected all services:

Result: Every security service now has at least one caller in the production execution flow. Build compiles successfully.

3. Architecture Overview

                    GoGrab Platform Ecosystem
    ┌──────────────────────────────────────────────────┐
    │                                                  │
    │   ┌─────────┐  ┌──────────┐  ┌──────────────┐   │
    │   │Frontend  │  │ Chrome   │  │   VSCode     │   │
    │   │  Apps    │  │Extension │  │  Extension   │   │
    │   └────┬────┘  └────┬─────┘  └──────┬───────┘   │
    │        │            │               │            │
    │        ▼            ▼               ▼            │
    │   ┌──────────────────────────────────────┐       │
    │   │     backend-api (port 3000)          │       │
    │   │  Spaces, Universes, Modules, Users   │       │
    │   └────────────────┬─────────────────────┘       │
    │                    │                             │
    │   ┌──────────────────────────────────────┐       │
    │   │    backend-ai-api (port 3001)        │       │
    │   │  Agent Registry, Learning Pyramid,   │       │
    │   │  Command Center, Space Agents (10)   │       │
    │   └───────────┬──────────────────────────┘       │
    │               │                                  │
    │   ┌───────────▼──────────────────────────┐       │
    │   │     VITTO (port 3003)                │       │
    │   │                                      │       │
    │   │  ┌────────┐ ┌──────┐ ┌───────────┐  │       │
    │   │  │ Engine │ │ Mind │ │   Security │  │       │
    │   │  │(21 files)│(18)  │ │  (22 files)│  │       │
    │   │  └────────┘ └──────┘ └───────────┘  │       │
    │   │  ┌────┐ ┌───────┐ ┌──────────┐     │       │
    │   │  │LLM │ │ Tools │ │ Strategy │     │       │
    │   │  │(11) │ │  (9)  │ │  (10)    │     │       │
    │   │  └────┘ └───────┘ └──────────┘     │       │
    │   │  ┌────────────┐ ┌───────────────┐  │       │
    │   │  │Connectivity│ │  Proactive    │  │       │
    │   │  │   (12)     │ │    (6)        │  │       │
    │   │  └────────────┘ └───────────────┘  │       │
    │   │  ┌──────────┐ ┌──────────────────┐ │       │
    │   │  │SpaceBuild│ │ ModuleGeneration │ │       │
    │   │  │   (6)    │ │     (18)         │ │       │
    │   │  └──────────┘ └──────────────────┘ │       │
    │   │  ┌──────────┐ ┌────────┐           │       │
    │   │  │ Customer │ │Prompts │           │       │
    │   │  │   (4)    │ │  (2)   │           │       │
    │   │  └──────────┘ └────────┘           │       │
    │   │                                    │       │
    │   │  MongoDB: vitto-mind (23 schemas)  │       │
    │   └────────────────────────────────────┘       │
    │                                                │
    │   ┌──────────────────────────────────────┐     │
    │   │   backend-docs-api (port 3002)       │     │
    │   └──────────────────────────────────────┘     │
    │   ┌──────────────────────────────────────┐     │
    │   │   MCP Server (claude-agent-mcp)      │     │
    │   └──────────────────────────────────────┘     │
    └──────────────────────────────────────────────────┘

Messaging Flow (new in Sessions 114-116):

  Slack/Discord/WhatsApp/Telegram
            │
            ▼
  POST /engine/integrations/{channel}/webhook
            │
            ▼
  ChannelRateLimiterService.check()  ← Rate limit per user per channel
            │ (if allowed)
            ▼
  ChannelGatewayService.handle{Channel}Event()
            │
            ▼
  VittoEngineService.submitTask()
            │
            ▼
  4-Phase Workflow (ANALYZE → PLAN → EXECUTE → VERIFY)
            │
       Each tool call passes through:
       ├── PromptInjectionGuardService.scan()
       ├── ToolSecurityService (sandbox level check)
       ├── ProcessSandboxService.execute() (for shell commands)
       ├── NetworkPolicyService.validate() (for HTTP requests)
       └── SecurityAuditService.record() + HashChain
            │
            ▼
  CostTrackerService.recordSpending()
            │
            ▼
  Result → ChannelGatewayService.routeTaskResult()
            │
            ▼
  Reply to Slack/Discord/WhatsApp/Telegram

4. Module Inventory

4.1 Engine (21 files) — The Brain

4.2 Mind (18 files) — The Memory

Schemas (12):

• ExecutionTrace — Task execution logs (90-day TTL)
• StrategyMemory — Best provider+model combos per task type
• AgentPerformance — Agent reliability scores
• UserPattern — Developer preferences
• AutonomyConfig — Autonomy levels
• AutonomyCheckpoint — Pending human approvals (30-day TTL)
• ActiveTask — In-flight tasks (24-hour TTL)
• CodebaseEntry — NX project index (refreshed every 6h)
• VittoSkill — Runtime-learned procedures
• VittoMemory — Vector-embedded semantic memories
• CustomerSession — Customer interaction context
• ProactiveAlert — Monitoring alerts

Services:

• VittoMemoryService — Vector search, semantic recall, team sharing, GDPR export
• CodebaseIndexerService — Scans NX monorepo every 6 hours
• PlatformModelService — Hardcoded GoGrab architecture knowledge
• SpaceContextService — Live space data with 5-minute cache
• OutcomeFeedbackService — Self-improvement feedback loop

4.3 Security (22 files) — The Shield

See Section 7: Security Deep-Dive for full details.

4.4 LLM (11 files) — The Voice

SmartRouterService routes requests by complexity, cost, and provider health. Each provider call is now wrapped in a CircuitBreakerService.execute() call — if a provider fails 5 consecutive times, the circuit opens and traffic reroutes to fallbacks.

4.5 Tools (9 files) — The Hands

24+ tools organized by layer permission:

All tool calls now pass through: injection scan → security check → sandbox execution → output sanitization → audit logging with hash chain.

4.6 Connectivity (12 files) — The Nervous System

4.7 Strategy (10 files) — The Judgment

4.8 Other Modules

5. What Changed: Sessions 101 → 116

Before (Session 101)

• 9 modules, ~50 files
• 16 tools
• 9 MongoDB schemas
• ~17 endpoints
• No security module
• In-memory audit logging (lost on restart)
• In-memory cost tracking (lost on restart)
• In-memory routing decisions (lost on restart)
• No prompt injection defense
• No sandbox for shell commands
• No rate limiting on messaging channels
• No circuit breaker on LLM calls
• No dead letter queue for failed tasks
• No hash chain for audit tamper detection
• No skill versioning or rollback
• No GDPR export capability
• No voice integration
• No webhook management
• No sub-agent mesh

After (Session 116)

• 16 modules, 147 files
• 24+ tools
• 23 MongoDB schemas
• 117 endpoints
• Full security module (22 files, 12 services)
• Persistent audit logging to MongoDB with hot cache
• Persistent cost tracking with per-user budgets
• Persistent routing decisions with provider health
• Prompt injection defense (50+ patterns across 8 categories)
• ProcessSandbox for all shell commands (sanitized env, resource limits)
• Rate limiting on all 4 messaging channels (per-user, per-minute)
• Circuit breaker on all LLM provider calls (per-provider state machine)
• Dead letter queue with exponential backoff (1min → 5min → 15min → 60min)
• SHA-256 hash chain on every audit entry (tamper-evident)
• Skill versioning with rollback to any previous version
• GDPR memory export per user
• Voice integration (Whisper STT + provider-agnostic TTS)
• Webhook management (CRUD + event ingestion + history)
• Sub-agent mesh with spawn, topology, cancellation
• Compliance reporting with CSV/JSON export
• Daily retention cleanup via @Cron
• Team memory sharing (private/team/organization levels)
• Module generation with 6-phase AI pipeline
• Ollama local model support

6. Current Feature Matrix

Fully Implemented & Wired

Partially Implemented (Inbound Works, Reply Path Incomplete)

Not Yet Implemented

7. Security Deep-Dive

Security Module Structure

security/
  security.module.ts                    (12 providers, 9 schemas)
  security.controller.ts                (5 audit endpoints + CSV/JSON export)
  security-audit.service.ts             (persistent logging + hot cache + hash chain)
  secret-vault.service.ts               (AES-256-GCM encrypted storage)
  credential-redactor.service.ts        (PII/credential masking)
  prompt-injection-guard.service.ts     (50+ patterns across 8 categories)
  network-policy.service.ts             (SSRF + private IP blocking)
  sandbox/
    process-sandbox.service.ts          (spawn with sanitized env, resource limits)
    container-sandbox.service.ts        (Docker-based isolation — stub)
  resilience/
    circuit-breaker.service.ts          (CLOSED→OPEN→HALF_OPEN per provider)
    dead-letter-queue.service.ts        (exponential backoff: 1→5→15→60 min)
  rate-limiting/
    channel-rate-limiter.service.ts     (per-user per-channel per-minute)
  compliance/
    hash-chain-verifier.service.ts      (SHA-256 tamper-evident audit chain)
    retention-policy.service.ts         (@Cron daily: 365d audit, 90d traces, 180d approvals)
  schemas/
    security-audit-log.schema.ts
    spending-record.schema.ts
    user-budget.schema.ts
    routing-decision.schema.ts
    approval-request.schema.ts
    encrypted-secret.schema.ts
    schedule-execution.schema.ts
    skill-version.schema.ts

Prompt Injection Defense (8 categories, 50+ patterns)

Flow: Fast static regex scan → if flagged, optional LLM semantic check → block or allow.

Tool Execution Security Pipeline

Every tool call passes through this pipeline:

1. Input received
   ↓
2. PromptInjectionGuardService.scan(input)      → Block if injection detected
   ↓
3. ToolSecurityService.checkSandboxLevel(tool)   → Verify tool has permission
   ↓
4. [If shell command] ProcessSandboxService.execute()
   - spawn() with shell=false
   - Sanitized env (only SAFE_ENV_KEYS)
   - Resource limits (memory, timeout)
   - Working directory boundary check
   ↓
5. [If HTTP request] NetworkPolicyService.validate()
   - Block private IPs (10.x, 172.16-31.x, 192.168.x)
   - Block dangerous schemes (file://, ftp://)
   - Block path traversal (../)
   ↓
6. Tool executes
   ↓
7. CredentialRedactorService.sanitize(output)    → Scrub leaked secrets
   ↓
8. SecurityAuditService.record()                 → Persist + hash chain
   ↓
9. CostTrackerService.recordSpending()           → Persist cost data

8. API Reference (117 Endpoints)

Health & Status

Task Management

Real-Time Events

Autonomy Configuration

Checkpoints (Human-in-Loop)

Delegation

Proactive Monitoring

Mind Explorer

Memory System

Smart Routing

Cost Tracking

Security & Audit

Security Controller (dedicated)

Skills Management

Channel Management

Integration Webhooks (Public receivers)

Webhook Management

Task Scheduling

Sub-Agent Mesh

Voice

Compliance & Retention

Local Models (Ollama)

9. How to Use Vitto — Developer Guide

Starting Vitto

# Option 1: Via NX
npx nx serve backend-vitto-api

# Option 2: Via project script
yarn serve:backend-vitto

# Verify it's running
curl http://localhost:3003/engine/health

Prerequisites: MongoDB running with vitto-mind database, .env.local configured with API keys.

Submitting a Task

curl -X POST http://localhost:3003/engine/tasks \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Fix the failing test in libs-ui-button",
    "type": "bugfix",
    "layer": "developer",
    "priority": "high",
    "context": {
      "errorMessage": "Cannot find module CommonModule",
      "affectedProject": "libs-ui-button"
    }
  }'

Monitoring Progress

# Real-time SSE stream
curl http://localhost:3003/engine/events
# Events: task.started, phase.started, tool_call, phase.completed, task.completed

# Get task status
curl http://localhost:3003/engine/tasks/<taskId>

# Task history with filters
curl "http://localhost:3003/engine/tasks/history?limit=20&status=completed"

Configuring Autonomy

# Set global level (OBSERVE | SUGGEST | DIRECT | AUTONOMOUS)
curl -X PUT http://localhost:3003/engine/autonomy/global \
  -H "Authorization: Bearer <JWT>" \
  -d '{ "level": "SUGGEST" }'

# Check pending checkpoints
curl http://localhost:3003/engine/checkpoints

# Approve a checkpoint
curl -X POST http://localhost:3003/engine/checkpoints/<id> \
  -H "Authorization: Bearer <JWT>" \
  -d '{ "decision": "approved", "resolvedBy": "frank" }'

Monitoring Costs

# Spending overview
curl http://localhost:3003/engine/costs/stats

# Estimate before running
curl "http://localhost:3003/engine/costs/estimate?type=bugfix&complexity=medium"

# Set user budget
curl -X PUT http://localhost:3003/engine/costs/budget/user123 \
  -H "Authorization: Bearer <JWT>" \
  -d '{ "dailyTokenLimit": 500000, "monthlyTokenLimit": 10000000 }'

Security Monitoring

# Audit log
curl "http://localhost:3003/engine/security/audit?toolName=run_command&limit=50"

# Export audit as CSV
curl http://localhost:3003/security/audit/export/csv > audit.csv

# Security stats
curl http://localhost:3003/engine/security/stats

Memory Operations

# Semantic search
curl "http://localhost:3003/engine/memories/search?query=authentication+bug&limit=5"

# Create a memory
curl -X POST http://localhost:3003/engine/memories \
  -H "Authorization: Bearer <JWT>" \
  -d '{
    "content": "The auth service requires the JWT_SECRET env var to be set",
    "category": "infrastructure",
    "importance": "high"
  }'

# Team recall
curl http://localhost:3003/engine/memories/team/team123

# GDPR export
curl http://localhost:3003/engine/memories/export/user123

10. How to Use Vitto — Space Builders

Generate Universe Blueprint

curl -X POST http://localhost:3003/space-builder/blueprint \
  -H "Authorization: Bearer <JWT>" \
  -d '{
    "spaceId": "space_123",
    "description": "Create an e-commerce store with product catalog, cart, and admin dashboard",
    "preferences": { "style": "modern", "colorScheme": "blue" }
  }'

Build and Deploy

# Build from blueprint
curl -X POST http://localhost:3003/space-builder/build \
  -H "Authorization: Bearer <JWT>" \
  -d '{ "spaceId": "space_123", "blueprint": { ... } }'

# Deploy
curl -X POST http://localhost:3003/space-builder/deploy/universe_456 \
  -H "Authorization: Bearer <JWT>"

# Check status
curl http://localhost:3003/space-builder/deploy/universe_456/status

# Rollback if needed
curl -X POST http://localhost:3003/space-builder/rollback/universe_456 \
  -H "Authorization: Bearer <JWT>"

Agent Chains

# Run a pre-defined chain
curl -X POST http://localhost:3003/space-builder/chain \
  -H "Authorization: Bearer <JWT>" \
  -d '{
    "spaceId": "space_123",
    "chainName": "full-page-build",
    "context": { "pageId": "page_789", "description": "Product detail with gallery" }
  }'

# Available chains: full-page-build, style-overhaul, content-refresh, performance-audit
curl http://localhost:3003/space-builder/chains

11. How to Use Vitto — End Users

End users interact through deployed spaces, not directly with Vitto's API:

# Customer query (no JWT needed)
curl -X POST http://localhost:3003/customer/query \
  -d '{
    "spaceId": "space_123",
    "universeId": "universe_456",
    "userId": "user_789",
    "message": "Where is the pricing page?",
    "sessionId": "session_abc",
    "pageContext": { "currentUrl": "/products", "pageId": "page_products" }
  }'

Response includes message, actions (navigate, highlight), and confidence score.

12. Use Cases

Use Case 1: Developer — Proactive Build Fix

1. Proactive monitor detects failing nx affected:build
2. Auto-creates task: { type: 'bugfix', layer: 'developer', priority: 'high' }
3. ANALYZE: Loads codebase index, queries Mind for similar past fixes
4. PLAN: Read error → find file → add missing import → rebuild
5. EXECUTE: Tool calls (run_command, read_file, write_file, run_command) — all through sandbox + injection scan
6. VERIFY: Build passes, lesson stored
7. Cost tracked, audit logged with hash chain

Use Case 2: Multi-Channel Customer Support

1. Customer sends WhatsApp message: "How do I track my order?"
2. Rate limiter checks: user under 50 msgs/min — allowed
3. ChannelGateway normalizes message → submits task
4. ANALYZE: Loads space context, identifies intent as 'navigation'
5. EXECUTE: Searches space modules, finds Order Tracking page
6. VERIFY: Response generated with navigation action
7. (Gap): Reply-path back to WhatsApp not yet wired

Use Case 3: AI Module Generation

1. Developer describes: "Create a user management module with CRUD"
2. ModuleGeneration 6-phase pipeline: analyze → plan → decompose → enhance → integrate → execute
3. Generates Angular components, services, routes following codebase conventions
4. All file writes pass through sandbox + audit

Use Case 4: Scheduled Maintenance Task

1. Admin creates schedule: { summary: "Run npm audit", cron: "0 6 * * 1" }
2. TaskScheduler persists to MongoDB (survives restart)
3. Every Monday at 6 AM, task fires
4. If task fails, DLQ catches it → retries at 1min, 5min, 15min, 60min
5. If provider is down, circuit breaker opens → routes to fallback

Use Case 5: Security-Conscious Skill Execution

1. Skill registered: { name: "deploy-preview", allowedEndpoints: ["https://api.vercel.com/*"] }
2. Skill calls http_request to https://api.vercel.com/deploy — NetworkPolicy allows
3. Skill tries http_request to http://169.254.169.254/metadata — NetworkPolicy blocks (private IP)
4. Skill tries run_command with curl — removed from allowlist
5. All attempts logged to audit trail with hash chain

13. Testing Checklist

Foundation (Phase 1) — Priority: Critical

• Persistent audit: Submit a task → check /security/audit → restart Vitto → verify audit entries survive
• Cost persistence: Submit task → check /engine/costs/stats → restart → verify spending data persists
• Routing persistence: Submit task with LLM call → check /engine/routing/decisions → restart → verify decisions persist
• Budget enforcement: Set budget via PUT /engine/costs/budget/:userId → submit tasks until budget exhausted → verify rejection
• Hash chain integrity: Submit 10 tasks → export audit JSON → verify each entryHash chains from previousHash
• Prompt injection blocking: Submit task with input containing "ignore previous instructions" → verify blocked in audit log
• Output sanitization: Submit task that returns content with API key patterns → verify redacted in audit
• Secret vault: Store secret via SecretVaultService → retrieve → verify encrypted at rest in MongoDB
• Retention cleanup: Manually trigger POST /engine/compliance/retention → verify old entries deleted per policy

Messaging (Phase 2) — Priority: High

• Slack inbound: Send Slack event to POST /engine/integrations/slack/events → verify task created
• WhatsApp inbound: Send via Twilio to POST /engine/integrations/whatsapp/webhook → verify task created
• Discord inbound: Send Discord interaction to POST /engine/integrations/discord/webhook → verify task created
• Telegram inbound: Send Telegram update to POST /engine/integrations/telegram/webhook → verify task created
• Rate limiting: Send 60 messages in 1 minute from same user → verify rate limit kicks in
• Channel CRUD: Create/read/update/delete channel via /engine/channels endpoints

Resilience (Phase 3) — Priority: High

• Circuit breaker: Configure invalid API key for Claude → submit tasks → verify circuit opens after 5 failures → verify fallback to OpenAI
• DLQ retry: Cause task failure → check /engine/compliance/audit for DLQ entry → verify retry after backoff
• Process sandbox: Submit task with run_command tool → verify command runs via spawn (not shell) with sanitized env
• Network policy: Submit task with http_request to private IP → verify blocked

Skills (Phase 4) — Priority: Medium

• Skill versioning: Create skill → update it → verify version history at /engine/skills/:id/versions
• Skill rollback: Create skill → update → rollback → verify content matches original
• Skill publishing: Publish skill → verify validation runs (LLM vetting)
• Skill rating: Rate skill → verify rating persisted

Compliance (Phase 5) — Priority: Medium

• Compliance report: GET /engine/compliance/report?startDate=2026-01-01&endDate=2026-02-18 → verify report generates
• CSV export: GET /security/audit/export/csv → verify valid CSV file
• JSON export: GET /security/audit/export/json → verify valid JSON
• GDPR export: GET /engine/memories/export/:userId → verify all user memories included
• Team sharing: Share memory → recall from team → verify accessible

End-to-End Flows — Priority: Critical

• Full task lifecycle: Submit task → stream SSE events → verify all 4 phases execute → verify audit trail → verify cost recorded
• Delegation flow: Submit complex task → verify handoff created → verify delegation tree
• Proactive alert: Trigger health check failure → verify alert created → resolve alert
• Memory recall: Create memories → search semantically → verify relevant results

14. Known Gaps & Roadmap

Immediate (Next Session)

Short-Term (2-4 weeks)

Medium-Term (1-2 months)

Long-Term (3+ months)

15. Deployment & Configuration

Environment Variables

MongoDB Collections (vitto-mind database)

Running Locally

# 1. Ensure MongoDB is running
mongosh --eval "db.adminCommand('ping')"

# 2. Ensure .env.local has required variables
cat .env.local | grep -E "VITTO_|ANTHROPIC_|JWT_SECRET|SYSTEM_TOKEN"

# 3. Build
npx nx build backend-vitto-api

# 4. Serve
npx nx serve backend-vitto-api
# OR
yarn serve:backend-vitto

# 5. Verify
curl http://localhost:3003/engine/health

Port Reference

16. Competitive Positioning vs OpenClaw

OpenClaw (197K+ GitHub stars) proves massive demand for autonomous AI agents but suffers from critical weaknesses. Vitto addresses all of them:

Strategic message: "Vitto is the AI agent platform that combines OpenClaw's autonomous power with enterprise-grade security. The more anyone uses GoGrab, the smarter Vitto gets for everyone."

17. Vitto Frontend Ecosystem (Session 117)

Added by: Session 117 (S114 Handoff Completion) Purpose: Document Vitto's complete frontend library architecture, component catalog, integration patterns, and bug fixes applied during S114 deep testing.

17.1 Frontend Library Architecture

Vitto's frontend spans 5 Angular libraries under libs/libs-ai/, each with a distinct role:

┌─────────────────────────────────────────────────────────────┐
│                  Frontend Library Stack                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │ ai-panel-core   │  │ vitto-hub       │  BUILDABLE       │
│  │ (user-facing    │  │ (admin command  │                  │
│  │  AI panel)      │  │  hub + routes)  │                  │
│  └────────┬────────┘  └────────┬────────┘                  │
│           │                    │                            │
│  ┌────────▼────────────────────▼────────────────────────┐  │
│  │ gograb-ai-lib (70+ components, 112+ services)        │  │
│  │ - VittoHubComponent (unified dashboard)              │  │
│  │ - VittoMonitorService (SSE stream)                   │  │
│  │ - UsageDashboardComponent (MCP billing)              │  │
│  │ - AgentMeshVisualizationComponent                    │  │
│  │ - CursorAgentsDashboardComponent                     │  │
│  │ BUILDABLE                                            │  │
│  └──────────────────────────┬───────────────────────────┘  │
│                             │                               │
│  ┌──────────────────────────▼───────────────────────────┐  │
│  │ vitto-chat (NON-BUILDABLE — source imports only)     │  │
│  │ - VittoChatShellComponent, VittoChatEngineService    │  │
│  │ - UserContextService, TaskBridgeService              │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ space-agents (NON-BUILDABLE)                         │  │
│  │ - SpaceAgentPanelComponent, SpaceBuilderService      │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

17.2 Key Component Catalog

@libs-ai/vitto-hub — Command Hub

The administrative interface for managing Vitto's capabilities. Route-based tab architecture (Session 112):

Service: VittoApiService — HTTP client targeting backend-vitto-api (port 3003) with methods for skills, channels, webhooks, schedules, memory, observatory, and cost APIs.

@libs-ai/vitto-chat — Chat Engine

Non-buildable by design — prevents circular dependencies with ai-panel-core. Imported as source via loadComponent at app level.

@libs-ai/gograb-ai-lib — Core AI Library

The largest AI library (70+ components, 112+ services). Key Vitto-related exports:

Key Services:

• VittoMonitorService — SSE stream from backend-vitto-api (/engine/tasks/stream, /engine/mind/summary)
• OrchestrationClientService — WebSocket to backend-ai-api (/ai-api/command-center)
• IntelligenceCoordinatorService — Multi-agent coordination
• HierarchicalMemoryService — Decision/pattern recall

Shared Types (vitto.types.ts): TaskPhase, TaskStatus, VittoTaskSummary, AutonomyLevel, AutonomyCheckpoint, MindSummary, VittoTool, EngineStatus, ProactiveAlert

17.3 Route Composition Pattern (Session 117)

Problem: @libs-ai/vitto-chat is non-buildable, so it can't be part of VittoHubRoutes (exported from buildable @libs-ai/vitto-hub). Apps that need chat must compose their own route tree.

Solution: VittoHubChildRoutes — exported separately from VittoHubRoutes — enables per-app composition:

// For apps WITHOUT chat (use loadChildren):
{ path: 'vitto', loadChildren: () => import('@libs-ai/vitto-hub').then(m => m.VittoHubRoutes) }

// For apps WITH chat (use loadComponent + spread children):
import { VittoHubChildRoutes } from '@libs-ai/vitto-hub';

{
  path: 'vitto',
  loadComponent: () => import('@libs-ai/vitto-hub').then(m => m.VittoCommandHubComponent),
  children: [
    { path: '', redirectTo: 'chat', pathMatch: 'full' },
    { path: 'chat', loadComponent: () => import('@libs-ai/vitto-chat').then(m => m.VittoChatShellComponent) },
    ...VittoHubChildRoutes,
  ],
}

Applied to: gograb-dev and gograb-admin (both default to /vitto/chat).

17.4 Proxy & Environment Architecture

Frontend apps reach backend services through the Angular dev server proxy:

Shared config: libs/libs-foundational/api-config/proxy.conf.json Custom override: apps/gograb-ai/proxy.conf.js — adds Chrome Private Network Access (PNA) support for extension embedding.

Session 117 fix: gograb-ai/src/environments/environment.ts had hardcoded http://localhost:3001/ai-api URLs. Changed to proxy paths (/api, /ai-api, /docs-api) except WebSocket URL which must remain direct (http://localhost:3001) since Angular dev server can't proxy WebSocket connections.

17.5 Auth Flow for API Requests

User logs in → JWT stored via Flash Persistence (localStorage signals)
     │
     ▼
HTTP Request → @auth-ui authInterceptor attaches "Authorization: Bearer <JWT>"
     │
     ▼
Angular proxy → /ai-api/* → backend-ai-api:3001
              → /api/* → backend-api:3000
     │
     ▼
Backend guard (JwtOrApiKeyGuard OR InfrastructureAuthGuard)
  - JwtOrApiKeyGuard: Validates JWT or API key
  - InfrastructureAuthGuard: Has localhost bypass for non-production

Session 117 fix: UsageDashboardComponent was calling /api/ai-api/mcp/usage (double prefix — routes to port 3000 which doesn't have MCP endpoints). Fixed to /ai-api/mcp/usage (routes to port 3001 correctly).

17.6 Decision Metric Scopes

Different metric numbers across dashboards are correct by design — each shows a different scope:

Session 117 fix: Added tooltips to each metric card clarifying its scope.

17.7 Session 117 Bug Fixes Summary

10 fixes applied across 20 files, resolving all S114 handoff tasks:

17.8 Supporting Libraries (Vitto-Adjacent)

Document updated: Session 117 — February 18, 2026 Covers: Sessions 98-117 of the Vitto platform evolution Previous baseline: docs/english/vitto/VITTO.md (Session 101)