# Arquitectura general

## Las piezas que se conectan

```
┌─────────────┐    ┌─────────┐    ┌──────────────┐    ┌────────────┐
│  Cliente    │ ←→ │  Twilio │ ←→ │   Webhook    │ ←→ │  Claude    │
│ (WhatsApp)  │    │  (BSP)  │    │  (PHP/etc)   │    │ (Anthropic)│
└─────────────┘    └─────────┘    └──────────────┘    └────────────┘
                       ↑                ↓
                       │           ┌──────────┐
                       │           │  MySQL   │ ← historial, slots,
                       │           │          │   tabla de pedidos
                       │           └──────────┘
                       │                ↓
                       │           ┌──────────┐
                       └────────── │ Whisper  │ ← transcribir audios
                                   │ (OpenAI) │
                                   └──────────┘
```

### Flujo de un mensaje entrante

1. **Cliente** escribe/manda audio/foto al número WhatsApp del comercio.
2. **WhatsApp Cloud (Meta)** lo recibe.
3. **Twilio** lo recibe de Meta y dispara webhook HTTP POST al server.
4. **Webhook** valida firma HMAC-SHA1, identifica al cliente por número, carga historial.
5. Si hay **audio** → Whisper → texto.
6. Si hay **imagen** → se anexa como input multimodal al primer mensaje de Claude.
7. **Loop agentic con Claude**: el modelo decide si responder directo, llamar tools (buscar productos, consultar pedido, etc.) o usar `mostrar_opciones` (templates con botones).
8. Resultado se manda al cliente vía Twilio Messages API.

## Componentes obligatorios

| Componente | Para qué | Opciones |
|---|---|---|
| **BSP** (Business Solution Provider) | Intermediar con Meta sin pelearse con Cloud API | Twilio (lo que usamos), 360dialog, MessageBird |
| **Servidor con HTTPS y dominio público** | Recibir webhook de Twilio | Cualquier VPS/cloud + cert SSL |
| **MySQL** o equivalente | Historial conversación, slots de selección, log de mensajes | Postgres también va |
| **LLM con tool-use** | Cerebro del agente | Claude (mejor en tool-use), GPT-4, Gemini |
| **(Opcional) Whisper** | Transcribir audios | OpenAI API |

## Costos estimados (USD, junio 2026)

Por mensaje conversacional entrante + respuesta:

| Pieza | Costo aprox |
|---|---|
| Twilio inbound + outbound (Argentina) | ~$0.005 + $0.030 conversación |
| Claude Sonnet 4 (3-4 turns en loop) | ~$0.003 - $0.010 |
| Whisper (si es audio, ~10seg) | ~$0.001 |
| Storage MySQL + servidor | negligible (~$0.0001) |
| **TOTAL por conversación** | **~$0.05 - $0.08** |

Para vender: cobrar $0.30 - $1.00 por conversación, o suscripción mensual con cuota. Ver [`07-modelo-negocio.md`](07-modelo-negocio.md).

## Latencia típica

- Inbound → primera respuesta: 3-8 segundos
- Si el loop hace 1 tool call: +1-2 segundos
- Si hay imagen: +2-4 segundos por la lectura
- Cliente lo percibe como "responde rápido" si está < 10s

## Estructura del código (recomendada)

```
proyecto/
├── webhook/
│   ├── whatsapp.php          # endpoint público
│   ├── lib/
│   │   ├── auth.php          # validar firma Twilio
│   │   ├── claude.php        # loop agentic + tools
│   │   ├── tools/            # implementación de cada tool
│   │   ├── media.php         # descargar audio/imagen, Whisper
│   │   └── templates.php     # gestión de templates Twilio
│   └── tools.json            # definición tools para Claude
├── admin/                    # panel para configurar agente del cliente
├── sql/                      # CREATE TABLEs
└── docs/                     # este kit
```