Arquitectura

┌──────────────────────────────────────────────────────────────┐
│ FRONTEND — web/ (Next.js)                                    │
│ Consola: equipo, cartera con procedencia, aprobaciones       │
└────────────────────────────┬─────────────────────────────────┘
                             │ REST /v1
┌────────────────────────────▼─────────────────────────────────┐
│ API GATEWAY — cloud/aiuda_cloud/api (FastAPI)                │
│ Auth · webhooks entrantes · responde <5s: valida y encola    │
└────────────────────────────┬─────────────────────────────────┘
                             │ Redis (ARQ)
┌────────────────────────────▼─────────────────────────────────┐
│ WORKER — cloud/aiuda_cloud/worker (ARQ)                      │
│ Aquí (y solo aquí) corre el motor de agentes + crons         │
└────────────────────────────┬─────────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────────┐
│ MOTOR DE AGENTES — core/aiuda_core/engine                    │
│ Loop de tool-use · HITL: draft → pending → approved → sent   │
└──────────┬──────────────────────────────────┬────────────────┘
┌──────────▼──────────────┐      ┌────────────▼────────────────┐
│ DATOS                   │      │ CONECTORES                  │
│ Postgres multi-tenant   │      │ WhatsApp · Odoo · tu Excel  │
│ procedencia por registro│      │ (import inteligente)        │
└─────────────────────────┘      └─────────────────────────────┘

Las reglas que no se negocian

1. Multi-tenancy en toda tabla: tenant_id indexado; ninguna query sin filtro.
2. El gateway nunca llama al LLM. Recibe, valida, persiste, encola, responde. El agente vive en el worker.
3. Un solo runtime de agentes. Todo el acceso al LLM pasa por core/aiuda_core/engine/llm.py (loop de tool-use con gates de aprobación). Anthropic es la implementación de referencia; el contrato es pluggable.
4. HITL estructural: el estado de cada envío es una máquina de estados en Postgres (engine/approval.py). El LLM redacta; el código decide qué se puede enviar. El agente no puede saltarse estados ni cerrar facturas por dicho del cliente (payment_reported, no paid).
5. Modelos por tarea: Haiku clasifica y mapea, Sonnet redacta y razona.
6. Costos medidos desde el primer token: usage_events por tenant, modelo y tarea. Sin esto no hay pricing serio.
7. Procedencia por registro: cada factura lleva source (excel/odoo) y verified; cada pago lleva paid_source (manual/banco).

El flujo principal (mensaje de WhatsApp)

1. Evolution API → POST /v1/webhooks/evolution (validación de token + idempotencia por wa_message_id).
2. API resuelve el tenant por instancia, persiste el mensaje, encola y responde 200.
3. Worker: si la conversación tiene human_takeover, no hace nada (el humano manda). Si no, invoca al agente con sus tools (consultar_cartera, registrar_promesa_pago, registrar_pago — que solo registra el reporte).
4. Los envíos reales solo ocurren sobre trabajos approved, vía la máquina de aprobación.

¿Qué sigue?

• Quickstart
• La visión — los principios de producto detrás de estas reglas