# 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

```yaml
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

```yaml
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

```yaml
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`:

```json
{
  "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

```bash
# 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`:

```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