# DECK

**Tipo:** Servidor Personal  
**IP:** 72.62.1.113  
**Dominio:** tzzrdeck.me

---

## Rol en el Ecosistema

DECK es el **servidor central** y **punto de iniciación** de todas las conexiones hacia los servicios de IA.

```
┌─────────────────────────────────────────────────────────────────┐
│                    PRINCIPIO DECK                               │
│                                                                 │
│   "DECK inicia TODAS las conexiones. Los servicios son         │
│    stateless. Cada request lleva su contexto completo."        │
└─────────────────────────────────────────────────────────────────┘
```

---

## Funciones

| Función | Descripción |
|---------|-------------|
| **Iniciador** | Todas las llamadas a GRACE, PENNY, FACTORY se originan aquí |
| **Gestor contexto** | Envía información de contexto con cada request |
| **Router despliegue** | Decide si usar self-hosted o externos |
| **Almacén credenciales** | Gestiona API keys vía Key Vault |

---

## Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                           DECK                                  │
│                    (Servidor Central)                           │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  PostgreSQL  │  │   Directus   │  │ 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       │       │
    │  └─────────────────┘     └─────────────────┘       │
    └────────────────────────────────────────────────────┘
```

---

## Componentes Internos

| Componente | Puerto | Función |
|------------|--------|---------|
| Clara (secretaría) | 5051 | Ingesta inmutable |
| Alfred (producción) | 5052 | Flujos predefinidos |
| Mason (administración) | 5053 | Enriquecimiento |
| Feldman (contable) | 5054 | Consolidación |

---

## Modos de Despliegue

### EXTERNAL

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

- Todas las llamadas a proveedores externos
- Sin infraestructura propia
- Ideal para: inicio rápido, bajo volumen

### SELF_HOSTED

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

- Todas las llamadas a infraestructura propia
- Requiere RunPod/GPU configurado
- Ideal para: privacidad total, alto volumen

### SEMI (Recomendado)

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

- Intenta self-hosted primero
- Fallback automático a external
- Balance privacidad/disponibilidad

---

## Flujo de 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
                      │           └─────────────────┘
```

---

## Servicios Docker

| Servicio | Puerto | Descripción |
|----------|--------|-------------|
| PostgreSQL | 5432 | Base de datos principal |
| Directus | 8055 | Interface datos |
| FileBrowser | 8081 | Gestión archivos |
| Vaultwarden | 8082 | Key Vault |
| Shlink | 8083 | Acortador URLs |
| Addy.io | 8084 | Alias correo |
| Redis | 6379 | Cache y colas |

---

## Conectores de IA

### GRACE Connector

- Procesa requests de módulos GRACE
- Soporta todos los M-CONTRACTs
- Maneja fallback chain según M-CONTRACT

### PENNY Connector

- Conexión WebSocket para real-time voice
- Sesiones de voz bidireccionales
- Integración con ASR/TTS

### FACTORY Connector

- Jobs de generación iterativa
- Gestión de iteraciones y convergencia
- Tracking de costos

---

## Gestión de Credenciales

Las credenciales se referencian con URIs `kv://`:

| URI | Contenido |
|-----|-----------|
| `kv://deck/credentials/groq` | API key Groq |
| `kv://deck/credentials/openrouter` | API key OpenRouter |
| `kv://deck/credentials/runpod` | API key RunPod |
| `kv://deck/credentials/grace` | Credenciales consolidadas GRACE |
| `kv://deck/credentials/penny` | Credenciales PENNY |
| `kv://deck/credentials/factory` | Credenciales FACTORY |

---

## Integración S-CONTRACT

DECK construye requests siguiendo S-CONTRACT v2.1:

```json
{
  "contract_version": "2.1",
  "profile": "FULL",
  "envelope": {
    "trace_id": "uuid-generado-por-deck",
    "idempotency_key": "sha256-del-contenido"
  },
  "routing": {
    "module": "ASR_ENGINE"
  },
  "deployment": {
    "mode": "SEMI",
    "tier_preference": ["SELF_HOSTED", "EXTERNAL"],
    "credentials_ref": "kv://deck/credentials/grace"
  },
  "payload": {
    "type": "audio",
    "encoding": "url",
    "content": "https://storage.tzzrdeck.me/audio/file.mp3"
  }
}
```

---

## Estructura de Directorios

```
deck/
├── config/
│   └── deployment.yaml      # Modos de despliegue
├── docker-compose.yml       # Servicios
├── docs/
│   ├── ARQUITECTURA.md
│   └── ESPECIFICACION_SERVIDOR.md
├── .env                     # Variables entorno
└── README.md
```