system-docs/v4-archive/deck/docs/ARQUITECTURA.md

DECK - Arquitectura del Sistema

Rol de DECK en el Ecosistema TZZR

DECK es el servidor central y punto de iniciación de todas las conexiones hacia los servicios de IA del ecosistema TZZR. Actúa como:

1. Iniciador de conexiones: Todas las llamadas a GRACE, PENNY y THE FACTORY se originan desde DECK
2. Gestor de contexto: Envía la información de contexto necesaria con cada request
3. Router de despliegue: Decide si usar servicios self-hosted o externos
4. Almacén de credenciales: Gestiona las API keys a través de Vaultwarden/Key Vault

┌─────────────────────────────────────────────────────────────────┐
│                           DECK                                   │
│                    (Servidor Central)                           │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  PostgreSQL  │  │   NocoDB     │  │ FileBrowser  │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ Vaultwarden  │  │    Shlink    │  │   Addy.io    │          │
│  │ (Key Vault)  │  │              │  │              │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              DEPLOYMENT ROUTER                            │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │   │
│  │  │   GRACE     │  │   PENNY     │  │  FACTORY    │      │   │
│  │  │  Connector  │  │  Connector  │  │  Connector  │      │   │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘      │   │
│  └─────────┼────────────────┼────────────────┼──────────────┘   │
└────────────┼────────────────┼────────────────┼──────────────────┘
             │                │                │
             ▼                ▼                ▼
    ┌────────────────────────────────────────────────────┐
    │              SERVICIOS DE IA                        │
    ├────────────────────────────────────────────────────┤
    │                                                     │
    │  ┌─────────────────┐     ┌─────────────────┐       │
    │  │  SELF-HOSTED    │     │    EXTERNAL     │       │
    │  │  (RunPod/GPU)   │     │    (APIs)       │       │
    │  ├─────────────────┤     ├─────────────────┤       │
    │  │ Faster Whisper  │     │ Groq API        │       │
    │  │ Local LLM       │     │ OpenRouter      │       │
    │  │ Tesseract       │     │ OpenAI          │       │
    │  │ Embeddings      │     │ Anthropic       │       │
    │  └─────────────────┘     │ ElevenLabs      │       │
    │                          └─────────────────┘       │
    └────────────────────────────────────────────────────┘

Modos de Despliegue

DECK soporta tres modos de despliegue definidos en config/deployment.yaml:

1. EXTERNAL

• Todas las llamadas van a proveedores externos (APIs)
• Sin infraestructura propia de IA
• Ideal para: Inicio rápido, bajo volumen

grace:
  mode: EXTERNAL
  external:
    providers_allowed: [groq, openrouter, openai, anthropic]

2. SELF_HOSTED

• Todas las llamadas van a infraestructura propia
• Requiere RunPod/GPU configurado
• Ideal para: Privacidad total, alto volumen, costos predecibles

grace:
  mode: SELF_HOSTED
  self_hosted:
    endpoint: "https://your-runpod-endpoint.runpod.net"
    timeout_ms: 30000

3. SEMI (Recomendado)

• Intenta self-hosted primero
• Fallback automático a external si falla
• Balance entre privacidad y disponibilidad

grace:
  mode: SEMI
  tier_preference:
    - SELF_HOSTED
    - EXTERNAL
  self_hosted:
    endpoint: "..."
    retry_on_failure: true
  external:
    providers_allowed: [groq, openrouter]

Flujo de una Request

┌──────────┐     ┌──────────┐     ┌───────────────┐     ┌──────────────┐
│  Cliente │────▶│   DECK   │────▶│  Deployment   │────▶│   Servicio   │
│          │     │          │     │    Router     │     │   (IA)       │
└──────────┘     └────┬─────┘     └───────┬───────┘     └──────────────┘
                      │                    │
                      │  1. Recibe request │
                      │  2. Lee config/deployment.yaml
                      │  3. Obtiene credenciales de Vaultwarden
                      │  4. Construye S-CONTRACT request
                      │                    │
                      │           ┌────────▼────────┐
                      │           │  mode: SEMI     │
                      │           ├─────────────────┤
                      │           │ 1. Try SELF_HOSTED
                      │           │ 2. If fail → EXTERNAL
                      │           └─────────────────┘

Estructura de Directorios

deck/
├── config/
│   └── deployment.yaml      # Configuración de modos de despliegue
├── docker-compose.yml       # Servicios principales
├── docs/
│   ├── ARQUITECTURA.md      # Este documento
│   └── ESPECIFICACION_SERVIDOR.md
├── .env.example             # Variables de entorno (incluye AI)
└── README.md

Integración con S-CONTRACT v2.1

DECK construye requests siguiendo el S-CONTRACT v2.1 de contratos-comunes:

{
  "contract_version": "2.1",
  "profile": "FULL",
  "envelope": {
    "trace_id": "uuid-generado-por-deck",
    "idempotency_key": "sha256-del-contenido",
    "timestamp_init": "2025-12-18T10:00:00Z"
  },
  "routing": {
    "module": "ASR_ENGINE"
  },
  "deployment": {
    "mode": "SEMI",
    "tier_preference": ["SELF_HOSTED", "EXTERNAL"],
    "self_hosted": {
      "endpoint": "https://asr.runpod.net",
      "timeout_ms": 60000
    },
    "credentials_ref": "kv://deck/credentials/grace"
  },
  "payload": {
    "type": "audio",
    "encoding": "url",
    "content": "https://storage.tzzr.net/audio/file.mp3"
  }
}

Gestión de Credenciales

Las credenciales se almacenan en Vaultwarden y se referencian con URIs kv://:

URI	Contenido
kv://deck/credentials/groq	{"api_key": "gsk_..."}
kv://deck/credentials/openrouter	{"api_key": "sk-or-..."}
kv://deck/credentials/runpod	{"api_key": "..."}
kv://deck/credentials/grace	{"groq": "...", "openrouter": "..."}
kv://deck/credentials/penny	{"groq": "...", "openai": "..."}
kv://deck/credentials/factory	{"anthropic": "...", "openrouter": "..."}

Servicios Actuales en DECK

Servicio	Puerto	Descripción
PostgreSQL	5432	Base de datos principal
NocoDB	8080	Interface de datos low-code
FileBrowser	8081	Gestión de archivos
Vaultwarden	8082	Key Vault / Gestor de contraseñas
Shlink	8083	Acortador de URLs
Addy.io	8084	Alias de correo
Redis	6379	Cache y colas

Conectores de IA

GRACE Connector

• Procesa requests de módulos GRACE
• Soporta todos los M-CONTRACTs (ASR, OCR, Classifier, etc.)
• Maneja fallback chain según M-CONTRACT

PENNY Connector

• Conexión WebSocket para real-time voice
• VAD integrado para detección de turnos
• Barge-in para interrupciones

FACTORY Connector

• Procesos documentales largos
• Batch processing
• Pipelines multi-step

Variables de Entorno Relevantes

# Modo de despliegue
DEPLOYMENT_MODE=SEMI

# Proveedores externos
GROQ_API_KEY=gsk_...
OPENROUTER_API_KEY=sk-or-...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Self-hosted (RunPod)
RUNPOD_API_KEY=...
GRACE_SELF_HOSTED_URL=https://...
PENNY_RUNPOD_ENDPOINT=https://...
ASR_RUNPOD_ENDPOINT=https://...

Monitoreo y Alertas

Configurado en config/deployment.yaml:

monitoring:
  latency:
    warn_threshold_ms: 5000
    error_threshold_ms: 15000
  cost:
    daily_budget_usd: 10.00
    alert_at_percent: 80

Próximos Pasos

1. Implementar el Deployment Router en código
2. Integrar con Vaultwarden para credenciales
3. Crear endpoints para GRACE/PENNY/FACTORY
4. Dashboard de monitoreo de costos y latencia