Caso de estudio · Proyecto autodirigido
Tableros sincronizados, automatizaciones asíncronas y observabilidad integrada.
Una plataforma de gestión de tareas donde los cambios se propagan entre usuarios mediante WebSocket, las automatizaciones se procesan en workers separados y tres capas de observabilidad registran lo que ocurre en el sistema.
Demo pública no disponible
Next.js + Socket.io
Un custom server comparte HTTP y WebSocket en el mismo proceso.
Workers BullMQ
Proceso separado que consume colas de Redis de forma asíncrona.
Infraestructura Docker
PostgreSQL, Redis, Nginx, Prometheus y Grafana.
Arquitectura documentada en ARCHITECTURE.md. El servidor y los workers son procesos independientes que se comunican a través de Redis.
Una plataforma de gestión de tareas necesita que los cambios lleguen a todos los miembros del equipo en tiempo real. Además, las automatizaciones —tareas obsoletas, vencimientos próximos, condiciones externas— deben procesarse sin bloquear la interfaz ni depender de que el usuario tenga la aplicación abierta.
El documento de arquitectura plantea un servidor HTTP compartido para Next.js y Socket.io, con workers BullMQ en un proceso separado para las automatizaciones. La observabilidad se distribuye en tres capas: logs estructurados, métricas y error tracking.
Implementé la sincronización de tableros, el motor de automatización, la observabilidad y los controles de autenticación y autorización; añadí pruebas unitarias y end-to-end del flujo crítico.
server.ts crea un servidor HTTP que monta Next.js para las rutas web y Socket.io para las conexiones WebSocket. Las API routes publican eventos en Redis; el servidor Socket.io los retransmite a los clientes suscritos. Los workers BullMQ corren en un proceso separado y consumen tres colas: automatizaciones, notificaciones y limpieza.
Usuario
Mueve una tarea en el tablero
API Route
Persiste en PostgreSQL vía Prisma
Redis Pub/Sub
Publica el evento al canal del tablero
Socket.io
Retransmite a los clientes conectados
Scheduler
Evalúa triggers cada 5 minutos
BullMQ
Encola el job en Redis
Worker
Ejecuta acciones y registra resultados
Redis Pub/Sub
Publica el cambio al tablero
Las API routes no tienen acceso directo al servidor Socket.io. Redis Pub/Sub actúa como puente: cualquier proceso puede publicar y el servidor WS retransmite.
User, Session y OAuthAccount gestionan la identidad. Team agrupa miembros y es propietario de los Boards. Cada Board tiene Columns con Tasks. Automation, AutomationAction y AutomationRun representan las recetas y su historial de ejecución. AuditLog registra operaciones críticas.
Socket.io necesita un servidor HTTP persistente. Las API routes de Next.js son funciones stateless que no pueden mantener conexiones WebSocket. La solución es un custom server que comparte el proceso HTTP entre ambos.
API Route
Llama a publishToBoard()
Redis
Publica al canal board:{id}
Socket.io
Suscriptor permanente con psubscribe
Clientes
Reciben el evento en la room del tablero
El middleware de Socket.io extrae el access token del handshake (auth o cookie), verifica su validez con JWT y comprueba la blacklist en Redis antes de permitir la conexión.
El cliente Socket.io reconecta automáticamente, pero no existe un mecanismo de catch-up que recupere los eventos emitidos durante una desconexión. El documento de arquitectura lo identifica como decisión pendiente.
El motor de automatizaciones separa la evaluación de triggers, el encolado y la ejecución. Las automatizaciones activas se evalúan periódicamente sin depender de eventos inmediatos del usuario.
El scheduler recorre las automatizaciones activas cada 5 minutos. Para cada trigger periódico (TASK_STALE, TASK_DUE_SOON, WEATHER, SCHEDULE) evalúa la condición consultando PostgreSQL o una API externa. Antes de disparar, comprueba si ya existe una ejecución reciente para evitar duplicados.
Cuando un trigger se cumple, triggerAutomation() encola un job en BullMQ. La cola garantiza reintentos con backoff exponencial si el worker falla, persistencia si el proceso se detiene, e historial de ejecuciones.
El worker de automatizaciones ejecuta cada acción en orden, registra logs detallados y actualiza el AutomationRun con el resultado. Las acciones pueden publicar cambios a Redis Pub/Sub para que lleguen al tablero en tiempo real.
Scheduler
Evalúa TASK_STALE, detecta tareas obsoletas
triggerAutomation()
Encola en BullMQ
automationProcessor
Ejecuta acciones y registra logs
AutomationRun
Resultado persistido en PostgreSQL
Configuración del código en workers/index.ts. No se ejecutaron pruebas de carga.
El scheduler debe correr en una sola instancia para evitar ejecuciones duplicadas. El documento de arquitectura identifica la coordinación con Redis locks como decisión pendiente para escalado horizontal.
La observabilidad se distribuye en tres capas con herramientas especializadas para cada función. No se trata de una lista de tecnologías: cada capa responde a un tipo de pregunta diferente sobre el sistema.
Logs estructurados · Pino
Todos los logs son JSON con campos consistentes: module, userId, jobId. Los secrets y passwords se redactan automáticamente con la configuración de Pino. En producción se pueden enviar a cualquier servicio de log aggregation.
Métricas de sistema y negocio · Prometheus + Grafana
Dos tipos de métricas: infraestructura (latencia HTTP p95, jobs en cola, conexiones WebSocket activas) y negocio (automatizaciones ejecutadas por tipo, tareas completadas). El código registra activeWebSocketConnections con inc/dec en las conexiones de Socket.io.
Error tracking · Sentry
Captura errores con contexto: stack trace, usuario, request. Las alertas de Grafana cubren degradación de rendimiento; Sentry cubre errores específicos.
Se verificó la integración de prom-client en el código del servidor Socket.io y la presencia de @sentry/nextjs en las dependencias. Los dashboards de Grafana y las alertas configuradas no se revisaron durante esta auditoría.
El sistema implementa varias capas de seguridad documentadas en la arquitectura y verificadas en el código del repositorio.
JWT con rotación de refresh tokens
Access tokens con expiración de 15 minutos. Cada uso del refresh token invalida el anterior en la base de datos y emite uno nuevo. Si un atacante usa el token robado, el siguiente intento del usuario legítimo detecta la invalidación.
Blacklist de tokens en Redis
Para el logout inmediato, el access token se agrega a una blacklist con TTL igual al tiempo de expiración restante. Cada request verifica la blacklist: una operación GET en Redis por request autenticado.
Cookies httpOnly y rate limiting
Los tokens se almacenan en cookies httpOnly, Secure, SameSite=Lax. Rate limiting: 10 intentos de login por IP cada 15 minutos en Redis; 30 req/min general en Nginx.
Webhooks HMAC-SHA256
Verificación de webhooks entrantes con crypto.timingSafeEqual para prevenir timing attacks.
Se verificó la existencia del flujo OAuth de GitHub en el repositorio. El documento de arquitectura no menciona Google como proveedor implementado en esta versión.
El CV menciona RBAC. El documento de arquitectura describe Teams y Members con roles. No se revisó en detalle la implementación del middleware de autorización por roles durante esta auditoría.
Decisiones del código para responder rápido y sacar el trabajo pesado de la petición. Son características de la implementación, no mediciones: no hay benchmarks publicados.
Caché del tablero en Redis
GET /api/boards/:id guarda el tablero completo en board:{id} con withCache durante 5 minutos; crear, editar, borrar o mover una tarea invalida esa clave.
Caché de usuario
/api/auth/me lee el usuario de user:{id} (1 hora) antes de ir a PostgreSQL.
Colas BullMQ fuera de la petición
Automatizaciones y notificaciones se encolan y las procesa un worker aparte, con concurrencia 5 y 10, reintentos con backoff y retención limitada de jobs terminados.
Reordenar con pocas consultas
Mover una tarea corre en una transacción y desplaza las posiciones afectadas con un solo updateMany por rango, no una consulta por tarea.
Consultas acotadas e indexadas
Las relaciones se piden con select de los campos necesarios y _count en lugar de cargar comentarios; el esquema indexa columnId, position, assigneeId y dueDate, entre otras.
Tiempo real escalable
Socket.io usa el adaptador de Redis, y las API routes publican eventos por Redis Pub/Sub en lugar de hablar con el proceso de sockets.
El repositorio contiene tests E2E con Playwright que recorren los flujos críticos del sistema. Requieren la aplicación, PostgreSQL, Redis y un seed de datos. Se revisó el código de las pruebas, sin ejecutarlas.
Código de pruebas revisado · Ejecución no verificada
Lo verificable aquí es la implementación y la existencia de estas comprobaciones. No se publican porcentajes de cobertura, tiempos de ejecución ni resultados de producción sin evidencia reproducible.
Los enlaces siguientes fijan la versión del código que sustenta este caso. Las limitaciones descritas corresponden a esa revisión.