a92a7efccc
- README principal con descripción del proyecto - Documento de diseño completo (arquitectura, DB, flujos) - Documentación de API REST y WebSocket - Guía del Flow Builder (30+ tipos de nodos) - Documentación de integración con Odoo - Guía de despliegue con Docker - Esquema de base de datos - Estructura de carpetas del proyecto - Archivo .env.example con todas las variables Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
228 lines
7.6 KiB
Markdown
228 lines
7.6 KiB
Markdown
# 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
|