How luigivalentino/voicely-code works
1. Propósito y forma general
Voicely es un SaaS multi-tenant para atención al cliente por WhatsApp con IA. El repositorio es principalmente un backend Flask monolítico modular: una misma aplicación sirve UI web, API REST, webhooks, lógica de negocio y orquestación de IA, mientras que el procesamiento pesado se delega a Celery workers.
2. Punto de entrada y composición de la app
El núcleo está en backend/app/__init__.py con el patrón app factory create_app. Ahí se ensamblan extensiones, configuración por entorno, blueprints y seguridad. extensions.py centraliza dependencias como SQLAlchemy, migraciones, Flask-Security, sesión en Redis y probablemente Celery.
3. Capas de exposición
Hay tres superficies principales:
- Frontend server-side en app/routes/ con Jinja2 + Tailwind para landing, auth y dashboard.
- REST API en app/api/ para conversaciones, mensajes, salud y estadísticas.
- Webhooks en app/api/webhooks_*.py para WhatsApp, Mercado Pago, Chatwoot y n8n.
Estas entradas convergen hacia los servicios y modelos comunes del backend.
4. Dominio y persistencia
El modelo de datos vive en app/models/ y cubre usuarios/roles, compañías, planes (Pack), conversaciones, mensajes, notas, pagos, tickets, recordatorios, plantillas WhatsApp, estados de servicio y suscripciones. La persistencia es PostgreSQL con SQLAlchemy y migraciones Alembic/Flask-Migrate. El diseño refleja multi-tenancy por Company, con separación lógica por organización.
5. Flujo principal de mensajes
El flujo crítico arranca desde WhatsApp Cloud API hacia el webhook de WhatsApp. Desde allí se crea o actualiza conversación/mensaje y se deriva trabajo asíncrono a Celery. Si el mensaje trae audio, pasa por ASR; si es texto, entra directo al pipeline IA. El resultado final se guarda y se envía de vuelta a WhatsApp.
6. Pipeline de IA en dos niveles
La lógica conversacional está separada en app/agents/:
- Router: clasifica intención y decide si responder, transferir o cerrar.
- Generator: genera la respuesta final cuando corresponde.
Los prompts están externalizados en app/agents/prompts/ por contexto de negocio (general, restaurante, consultorio, servicios_tecnicos). La capa de IA usa OpenRouter como proxy y modelos Claude distintos para enrutamiento y generación.
7. ASR y mensajes de audio
app/services/asr.py integra Groq Whisper Large v3 para transcribir audios, aceptando bytes o URL. La transcripción forma parte del pipeline de entrada antes de la clasificación del Router. Esto es importante para el diagrama porque el audio no se procesa dentro del request web principal, sino mediante tareas diferidas.
8. Servicios de negocio y orquestación
La lógica se distribuye en app/services/: booking, availability, integrations, notification, takeover, message storage, chatwoot, mercadopago, wsp, etc. orchestrator.py sugiere coordinación entre servicios y tareas, mientras debounce_service.py y takeover_service.py reflejan reglas de control de conversación. Esta capa es el puente entre API/webhooks y el dominio.
9. Procesamiento asíncrono
app/tasks/ contiene las tareas Celery para ASR, respuesta, mensajería WhatsApp, notificaciones y suscripciones. El README indica que el broker es Redis y que hay worker y beat separados. En la arquitectura, Celery absorbe las etapas costosas o reintentables: transcripción, generación IA y envío externo.
10. Integraciones externas
Los servicios externos relevantes son:
- WhatsApp Cloud API para entrada/salida de mensajes.
- OpenRouter para inferencia LLM.
- Groq para ASR.
- Mercado Pago para suscripciones/pagos.
- Chatwoot para sincronización de conversaciones.
- n8n como posible automatizador de eventos.
Estas integraciones son boundary points claros del sistema.
11. Seguridad y aislamiento
La app usa Flask-Security para autenticación, CSRF con SeaSurf, HSTS con Talisman y sesiones en Redis. El repositorio menciona RLS en PostgreSQL vía app.current_user_id, lo que refuerza el aislamiento por tenant. También hay rate limiting en Nginx para login y webhooks.
12. Infraestructura de ejecución
docker-compose.yml levanta seis servicios: app (Flask/Gunicorn), worker, beat, postgres, redis y nginx. Nginx actúa como reverse proxy y límite de tasa; Gunicorn con gevent atiende la app; Redis sirve de broker, cache y sesiones. Esto define un despliegue claramente desacoplado entre web, background jobs y datos.
13. Observabilidad y verificación
El stack menciona Langfuse y Sentry como observabilidad, y el health check verifica base de datos y Redis. Hay tests de modelos, rutas y API en backend/tests/, además de evaluaciones Promptfoo para prompts del Router y Generator. Esto indica que la calidad de IA y la integridad de endpoints forman parte del diseño operativo, no solo del código.
14. Qué dibujar en un diagrama
Un diagrama correcto debería mostrar: usuarios/web/WhatsApp entrando a Nginx; Nginx enruta a Flask; Flask persiste en PostgreSQL y usa Redis; Flask dispara tareas a Celery; Celery llama a Groq, OpenRouter, WhatsApp y Mercado Pago; y la UI web/REST comparten el mismo backend y base de datos. El límite principal del sistema está entre la capa síncrona de Flask y la capa asíncrona de Celery/integraciones externas.
Main entry points: __init__.py App factory · api API layer · services Business services · tasks Task queue
Components 19
Runtime
Execution entrypoints and deployment surface
- run.py · App bootstrap
backend/run.py - Celery app · Background task bootstrap
backend/celery_app.py
Backend
Flask app, routes, domain, and services
- App factory · create_app composition root
backend/app/__init__.py - Extensions · SQLAlchemy, Redis, security, migration wiring
backend/app/extensions.py - Web UI · Landing, auth, dashboard, docs
backend/app/routes - API layer · Conversations, messages, subscriptions, inbound webhooks
backend/app/api - Domain models · Users, companies, conversations, payments, subscriptions
backend/app/models - Business services · Booking, notification, WhatsApp, payment, takeover, storage
backend/app/services - Task queue · Async ASR, response, messaging, notifications, subscriptions
backend/app/tasks
AI Pipeline
Routing, generation, and prompt management
- Agents · Router and generator for conversation decisions
backend/app/agents - Prompts · Context-specific system prompts
backend/app/agents/prompts - OpenRouter · LLM inference proxy
backend/app/services/openrouter.py - ASR · Audio transcription via Groq Whisper
backend/app/services/asr.py
Infrastructure
Database, cache, workers, and proxy
- WhatsApp · Cloud API send/receive integration
backend/app/services/wsp_service.py - Mercado Pago · Subscriptions and payment webhooks
backend/app/services/mercadopago_service.py - Chatwoot · Conversation synchronization
backend/app/services/chatwoot_service.py - PostgreSQL · Multi-tenant persistence with RLS
backend/migrations - Redis · Sessions, cache, and Celery broker
backend/app/services/redis_pool.py - Nginx · TLS termination and rate limiting
backend/nginx/default.conf
Connections 26
- run.py → App factory: starts · Gunicorn/Flask bootstraps the application
- Celery app → Task queue: runs · Celery worker executes async jobs
- App factory → Extensions: configures · Registers shared extensions and security
- App factory → Web UI: mounts · Serves server-side pages
- App factory → API layer: mounts · Serves REST and webhook endpoints
- App factory → Domain models: binds · Application context uses ORM models
- App factory → Business services: uses · Requests delegate into business services
- API layer → Business services: delegates · API/webhooks hand off to service layer
- Web UI → Business services: reads/writes · Dashboard and auth use shared business logic
- Business services → Domain models: persists · Service layer stores business state
- Business services → PostgreSQL: queries · SQLAlchemy/Postgres persistence
- Extensions → Redis: shares · Sessions, cache, and broker access
- Task queue → ASR: calls · Audio jobs transcribe voice notes
- Task queue → Agents: calls · Response jobs invoke router and generator
- Task queue → WhatsApp: sends · Background delivery to WhatsApp
- Task queue → Mercado Pago: processes · Subscription and payment jobs
- Business services → Chatwoot: syncs · Conversation synchronization boundary
- Agents → Prompts: loads · Context-specific system prompts
- Agents → OpenRouter: invokes · LLM routing and generation requests
- API layer → WhatsApp: webhooks · Inbound and outbound WhatsApp flow
- API layer → Mercado Pago: webhooks · Payment gateway callbacks
- API layer → Chatwoot: webhooks · Support platform callbacks
- Nginx → run.py: proxies · Reverse proxy to Flask app
- Nginx → API layer: routes · External HTTP entry surface
- run.py → Redis: uses · Runtime sessions/cache integration
- run.py → PostgreSQL: uses · Primary persistence connection