Files

Claude AI a92a7efccc Initial commit: Documentación completa del proyecto WhatsApp Centralizado

- 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>

2026-01-29 09:29:57 +00:00

7.6 KiB

Raw Permalink Blame History

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

7.6 KiB Raw Permalink Blame History