Cómo Construir un Centro de Mando de IA con 14 Endpoints y React 18

Cómo Construir un Centro de Mando de IA con 14 Endpoints y React 18

La Brecha Entre Planear y Ejecutar

Hay una diferencia brutal entre diseñar un sistema en papel y tenerlo funcionando en producción. Durante años he visto proyectos que lucen impresionantes en diagramas de arquitectura, pero que nunca llegan a desplegarse. Este artículo documenta el recorrido de llevar un Centro de Mando de IA desde el concepto hasta producción, con 14 endpoints activos, React 18 en el frontend, y múltiples integraciones funcionando en paralelo.

Lo que hace especial este caso no es la tecnología en sí, sino la combinación de decisiones arquitectónicas que permitieron mantener la complejidad bajo control mientras se agregaban capacidades avanzadas.

Arquitectura del Sistema: Flask + React 18

El stack tecnológico se construyó con pragmatismo sobre purismo:

• Backend: Flask con 14 endpoints REST bien documentados
• Frontend: React 18 con componentes funcionales y hooks
• Base de datos: PostgreSQL para datos estructurados + JSON para configuraciones flexibles
• Automatización: n8n para workflows complejos con capacidad de auto-recuperación
• Monitoreo: Health checks cada 5 minutos con alertas a Telegram

La decisión de usar Flask sobre FastAPI se basó en simplicidad y ecosistema maduro. Cuando tienes 14 endpoints que necesitan funcionar de manera confiable, prefieres un framework battle-tested sobre el más moderno.

Los 14 Endpoints que Importan

No todos los endpoints son creados iguales. La arquitectura se diseñó alrededor de capacidades específicas:

1. Gestión de proyectos: CRUD completo para Work Packages con sync automático a OpenProject
2. Tracking de progreso: Extracción de CCDs (Cosas Completadas en el Día) desde texto libre
3. Inteligencia de voz: Integración con Gemini TTS y Chatterbox para voice cloning
4. Sistema de asistencia: Reconocimiento facial con InsightFace para registro de empleados
5. Lead management: Pipeline completo desde detección hasta clasificación

Cada endpoint fue diseñado con idempotencia en mente. Si un request falla, puede reintentar sin crear duplicados o corromper estado.

Integraciones de IA en Producción

La verdadera magia ocurre cuando múltiples sistemas de IA trabajan juntos de forma coordinada.

Gemini TTS: De Texto a Audio en 3 Segundos

La implementación del Text-to-Speech usa el modelo `gemini-2.5-flash-preview-tts` con la voz "Zephyr". El flujo es:

def generate_tts_gemini(text):
# Genera PCM 24kHz mono
pcm_audio = gemini_api.synthesize(text, voice="Zephyr")
# Convierte a MP3 con ffmpeg
mp3_audio = ffmpeg_convert(pcm_audio)
return mp3_audio

Latencia promedio: 3 segundos. Esto permite respuestas de voz en tiempo real para bots de Telegram sin infraestructura compleja.

Chatterbox TTS: Voice Cloning Local

Para casos que requieren voz personalizada, se implementó Chatterbox (open-source) corriendo localmente:

• Hardware: CPU (sin GPU necesaria)
• API: `localhost:3020`
• Tiempo de generación: ~4 minutos por frase
• Calidad: Excelente para clonación de voz

La dualidad Gemini (rápido) + Chatterbox (personalizado) cubre todo el espectro de necesidades.

InsightFace: Reconocimiento Facial sin Cloud

Para el sistema de asistencia de empleados, se implementó InsightFace corriendo en Docker:

• Precisión: Alta incluso con una sola foto de referencia
• Privacidad: Todo procesa localmente, cero datos a cloud
• Velocidad: <500ms por reconocimiento
• Integración: API REST lista para webhooks

La combinación con chatbot de IA permite que empleados consulten su historial de asistencia en lenguaje natural.

Auto-Recuperación y Resiliencia

Un sistema en producción no puede requerir supervisión constante. Se implementaron tres mecanismos de auto-recuperación:

1. Auto-Retry Engine (n8n)

Workflows que fallan se reintentan automáticamente con backoff exponencial. Configuración:

• Primer reintento: 1 minuto
• Segundo reintento: 5 minutos
• Tercer reintento: 15 minutos
• Cuarto reintento: Alerta a humano

2. Health Check Cada 5 Minutos

Un timer de systemd ejecuta verificaciones de salud:

Persistent=true  # Ejecuta inmediatamente si el sistema estuvo apagado
OnCalendar=*:0/5  # Cada 5 minutos

Si detecta problemas, envía diagnóstico completo a Telegram con logs relevantes.

3. Docker Monitor

Monitorea contenedores críticos y los reinicia automáticamente si detecta:

• Uso de memoria > 90%
• CPU throttling sostenido
• Health checks fallando
• Red desconectada

Gestión de Estado: Single Source of Truth

La complejidad de múltiples sistemas se manejó estableciendo un SSoT (Single Source of Truth):

• OpenProject: Fuente de verdad para Work Packages y estado de proyectos
• PostgreSQL: Fuente de verdad para datos de clientes
• TRACKING_200K: Fuente de verdad para métricas de progreso

Cualquier otro sistema que necesite estos datos los consume vía API, nunca duplica. Esto elimina problemas de sincronización.

Lecciones Aprendidas

1. Start Simple, Add Complexity Only When Needed

El sistema comenzó con 3 endpoints. Llegó a 14 porque cada uno resolvía un problema real, no por completitud arquitectónica.

2. Monitoreo > Logging

Logs detallados son útiles para debugging, pero monitoreo activo con alertas previene problemas antes de que los usuarios los reporten.

3. Deployment es Feature

Si un sistema requiere 20 pasos manuales para desplegarse, no se desplegará. Automatización de deployment debe ser prioridad uno.

Conclusión

Construir un Centro de Mando de IA funcional requiere más que juntar tecnologías modernas. Requiere decisiones arquitectónicas que prioricen confiabilidad sobre novedad, automatización sobre control manual, y simplicidad sobre completitud.

Los 14 endpoints no son el punto final, son la base sobre la cual seguir construyendo. La arquitectura permite agregar nuevas capacidades sin reestructurar lo existente, que es exactamente lo que un sistema en producción necesita.

Lo más importante: el sistema está en producción, sirviendo usuarios reales, no en un repositorio esperando "el momento correcto" para desplegarse. Esa es la única métrica que realmente importa.