consultoria-as/WhatsAppCentralizado
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Documentación completa del proyecto WhatsApp Centralizado

Browse Source 
- 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>
This commit is contained in:
Claude AI
2026-01-29 09:29:57 +00:00
commit a92a7efccc
17 changed files with 4475 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
docs/architecture/README.md Normal file
View File

@@ -0,0 +1,227 @@
# 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