Dashboard de Sentimiento del Cliente vía WhatsApp

Este monorepo contiene 2 aplicaciones para analizar mensajes de WhatsApp de "Café de El Salvador":

• /api: Backend con FastAPI que recibe mensajes vía webhook de Twilio, los analiza con IA y los guarda en MongoDB.
• /web: Frontend React que muestra gráficas de sentimientos, frecuencia de temas y mensajes recientes.

Cómo configurar y ejecutar localmente

Backend (API)

1. Requisitos: Python 3.14+, MongoDB

2. Instalar dependencias:

   cd api
   pip install "fastapi[all]" anthropic pymongo uvicorn python-dotenv
   # O con uv: uv sync

3. Configurar variables de entorno (crear archivo .env):

   MONGO_DB_URI=mongodb://localhost:27017
   MONGO_DB_NAME=api
   AI_PROVIDER=anthropic
   LLM_API_KEY=tu_api_key_aqui

4. Ejecutar:

   uvicorn app.main:app --reload

   La API estará disponible en http://localhost:8000

Frontend (Web)

1. Requisitos: Node.js 18+

2. Instalar dependencias:

   cd web
   npm install  # o pnpm install

3. Configurar variables de entorno (crear archivo .env):

   VITE_API_BASE_URL=http://localhost:8000

4. Ejecutar en modo desarrollo:

   npm run dev  # o pnpm dev

   El sitio estará disponible en http://localhost:5173

Decisiones técnicas

Backend

• FastAPI: Framework moderno y rápido con soporte nativo para async/await y validación automática con Pydantic.
• Background Tasks: Los mensajes se guardan inmediatamente y el análisis de IA se hace en segundo plano para no bloquear el webhook de Twilio.
• Factory Pattern para LLM: Soporta múltiples proveedores (Anthropic Claude, OpenAI) mediante una interfaz unificada, fácil de extender.
• MongoDB: Base de datos NoSQL con aggregation pipelines para consultas eficientes de estadísticas.
• Dependency Injection: FastAPI gestiona automáticamente las dependencias (DB, Logger, LLM).

Frontend

• React + Vite: Setup moderno con hot-reload rápido y optimización automática.
• Tanstack Query: Maneja peticiones asíncronas con caché inteligente y auto-revalidación, mejora la experiencia sin websockets.
• Tanstack Table: Tabla avanzada con filtros, ordenamiento y virtualización para manejar muchos datos sin perder rendimiento.
• shadcn/ui + Radix UI: Componentes accesibles y personalizables sin dependencias pesadas.
• Recharts: Biblioteca simple para gráficas de sentimientos y temas.
• Tailwind CSS: Estilos utility-first para desarrollo rápido y consistente.

Decisiones de arquitectura

Estas son cosas que pensé cambiar y/o integrar en su momento.

• Long polling vs WebSockets: Se usa polling con Tanstack Query porque es más simple, no requiere mantener conexiones largas y funciona bien con caché.
• Sin autenticación: Para mantener el proyecto simple y enfocado en la funcionalidad core.
• Sin Redis/colas: Background tasks de FastAPI son suficientes para el volumen esperado, se puede escalar después si es necesario.

Estructura y creación de prompts

Después de tanto tiempo creando prompts tanto para uso personal como para otros, he decidido seguir una arquitectura/estructura para la creación de prompts.

Aunque cada día surgen más y más formas de crear prompts, considero que esta estructura se adapta correctamente a la problemática actual.

También tuve en cuenta temas como el prompt spoofing para garantizar la seguridad.