# Arquitectura del Sistema

## Visión General

WhatsApp Centralizado está diseñado como una arquitectura de microservicios, donde cada componente tiene una responsabilidad específica y se comunica con los demás a través de APIs REST y WebSocket.

## Diagrama de Arquitectura

```
                                    ┌─────────────────┐
                                    │    NGINX        │
                                    │  (Reverse Proxy)│
                                    │   :80 / :443    │
                                    └────────┬────────┘
                                             │
                    ┌────────────────────────┼────────────────────────┐
                    │                        │                        │
                    ▼                        ▼                        ▼
           ┌───────────────┐        ┌───────────────┐        ┌───────────────┐
           │   Frontend    │        │  API Gateway  │        │ WhatsApp Core │
           │    (React)    │        │   (FastAPI)   │        │   (Node.js)   │
           │    :3000      │        │    :8000      │        │    :3001      │
           └───────────────┘        └───────┬───────┘        └───────┬───────┘
                                            │                        │
                                            │                        │
                         ┌──────────────────┼──────────────────┐     │
                         │                  │                  │     │
                         ▼                  ▼                  ▼     │
                ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐
                │   Flow Engine   │ │  Integrations   │ │      Redis       │
                │    (Python)     │ │    (Python)     │ │    (Cache/PubSub)│
                │    :8001        │ │    :8002        │ │      :6379       │
                └────────┬────────┘ └────────┬────────┘ └──────────────────┘
                         │                   │                  ▲
                         │                   │                  │
                         └─────────┬─────────┘                  │
                                   │                            │
                                   ▼                            │
                         ┌─────────────────┐                    │
                         │   PostgreSQL    │────────────────────┘
                         │    (Database)   │
                         │      :5432      │
                         └─────────────────┘
```

## Componentes

### Frontend (React + TypeScript)
- **Puerto:** 3000
- **Responsabilidad:** Interfaz de usuario
- **Tecnologías:**
  - React 18
  - TypeScript
  - React Flow (editor visual)
  - Ant Design / shadcn/ui
  - TanStack Query
  - Zustand (estado)
  - Socket.io-client

**Módulos:**
- Dashboard con métricas
- Inbox de conversaciones
- Flow Builder visual
- Gestión de números WhatsApp
- Panel de supervisor
- Configuración

### API Gateway (Python + FastAPI)
- **Puerto:** 8000
- **Responsabilidad:** Punto de entrada único, autenticación, orquestación
- **Tecnologías:**
  - FastAPI
  - SQLAlchemy
  - Pydantic
  - python-jose (JWT)
  - Celery (tareas async)

**Endpoints principales:**
- `/auth/*` - Autenticación
- `/api/conversations/*` - Conversaciones
- `/api/messages/*` - Mensajes
- `/api/flows/*` - Flujos de chatbot
- `/api/contacts/*` - Contactos
- `/api/users/*` - Usuarios
- `/api/queues/*` - Colas
- `/api/whatsapp/*` - Gestión WhatsApp
- `/ws/*` - WebSocket

### WhatsApp Core (Node.js + TypeScript)
- **Puerto:** 3001
- **Responsabilidad:** Conexión con WhatsApp via Baileys
- **Tecnologías:**
  - Node.js 20
  - TypeScript
  - Baileys
  - Socket.io

**Funcionalidades:**
- Gestión de sesiones multi-número
- Generación de QR
- Envío/recepción de mensajes
- Manejo de media
- Reconexión automática
- Estados de mensajes

### Flow Engine (Python)
- **Puerto:** 8001 (interno)
- **Responsabilidad:** Ejecutar flujos de chatbot
- **Tecnologías:**
  - Python
  - Motor de ejecución propio

**Funcionalidades:**
- Parsear definición de flujos (JSONB)
- Ejecutar nodos secuencialmente
- Manejar bifurcaciones y condiciones
- Gestionar variables y contexto
- Integrar con IA (OpenAI, Claude, Ollama)

### Integrations (Python)
- **Puerto:** 8002 (interno)
- **Responsabilidad:** Conexión con sistemas externos
- **Tecnologías:**
  - Python
  - xmlrpc.client (Odoo)
  - httpx (webhooks)

**Integraciones:**
- Odoo via XML-RPC
- Webhooks entrantes/salientes
- Email (futuro)
- SMS (futuro)

### PostgreSQL
- **Puerto:** 5432
- **Responsabilidad:** Persistencia de datos
- **Datos almacenados:**
  - Usuarios y roles
  - Conversaciones y mensajes
  - Contactos
  - Flujos de chatbot
  - Configuración
  - Logs de auditoría

### Redis
- **Puerto:** 6379
- **Responsabilidad:** Cache, colas, pub/sub
- **Usos:**
  - Sesiones de usuario
  - Cache de datos frecuentes
  - Cola de mensajes salientes
  - Pub/Sub para tiempo real
  - Rate limiting

## Comunicación entre Servicios

### HTTP/REST
- Frontend → API Gateway
- API Gateway → Flow Engine
- API Gateway → Integrations
- WhatsApp Core → API Gateway

### WebSocket
- Frontend ↔ API Gateway (tiempo real)
- API Gateway ↔ WhatsApp Core (eventos)

### Pub/Sub (Redis)
- Eventos de nuevos mensajes
- Cambios de estado
- Notificaciones

## Flujo de Datos

### Mensaje Entrante
```
WhatsApp → Baileys → WhatsApp Core → API Gateway → Flow Engine
                                          ↓
                                    PostgreSQL
                                          ↓
                              Frontend (via WebSocket)
```

### Mensaje Saliente (Bot)
```
Flow Engine → API Gateway → WhatsApp Core → Baileys → WhatsApp
      ↓
PostgreSQL
```

### Mensaje Saliente (Agente)
```
Frontend → API Gateway → WhatsApp Core → Baileys → WhatsApp
                ↓
          PostgreSQL
```

## Escalabilidad

### Horizontal
- WhatsApp Core: Múltiples instancias para más números
- API Gateway: Load balancer con múltiples instancias
- Flow Engine: Workers independientes

### Vertical
- PostgreSQL: Aumentar recursos según carga
- Redis: Cluster para alta disponibilidad

## Seguridad

### Autenticación
- JWT con access tokens (1h) y refresh tokens (7d)
- Refresh tokens en httpOnly cookies
- Bcrypt para passwords (cost 12)

### Autorización
- RBAC: Admin, Supervisor, Agente
- Permisos granulares por endpoint

### Red
- HTTPS obligatorio
- Rate limiting
- Validación de entrada con Pydantic

### Datos
- Encriptación en reposo (PostgreSQL)
- Secrets en variables de entorno
- No logs de datos sensibles