taskbot/docs/architecture.md

Arquitectura y responsabilidades

Módulos principales

• src/server.ts
  • Expone endpoints (webhook, /metrics), valida entorno, lanza migraciones y arranque.
  • Extrae texto de mensajes con lógica tolerante a formatos (texto/caption).
• src/db.ts
  • Abre la base de datos (data/…), aplica PRAGMAs por defecto y expone helpers.
  • initializeDatabase() ejecuta migraciones up-only.
• src/db/migrations/index.ts
  • Registro de migraciones con versión, nombre, checksum y función up.
  • Helpers para inspección del esquema (tableHasColumn).

Servicios (src/services)

• command.ts: orquesta el manejo de comandos. Entrada: { sender, groupId, message, mentions }.
• contacts.ts: resolución de nombres de contactos vía Evolution API con caché en memoria y TTL.
• group-sync.ts: sincronización de grupos y miembros, cachés en memoria, schedulers configurables.
• identity.ts: gestión de alias ↔ user_id real; caché en memoria y tabla user_aliases.
• maintenance.ts: limpieza programada de miembros inactivos según retención.
• metrics.ts: contadores y gauges in-memory con render a Prometheus o JSON.
• rate-limit.ts: token bucket por usuario, con burst, refill y cooldown de notificación.
• reminders.ts: recordatorios según preferencias (zona horaria, frecuencia, hora).
• response-queue.ts: cola de respuestas con intentos, backoff y limpieza.
• webhook-manager.ts: configuración de webhooks salientes (si aplica).

Utilidades (src/utils)

• whatsapp.ts: normalización de IDs, helpers para distinguir usuario/grupo.
• formatting.ts: utilidades de representación (IDs, fechas abreviadas, etc.).

Tareas (src/tasks)

• model.ts: interfaces Task, TaskAssignment, etc.
• service.ts: operaciones de alto nivel sobre tareas (crear, asignar, soltar, etc.).

Dependencias internas

• La mayoría de servicios aceptan/injectan una instancia Database estática configurable para test.
• utils no dependen de servicios; servicios pueden usar utils y db.
• server.ts invoca servicios y metrics; no debe contener lógica de dominio pesada.

Puntos de extensión

• Nuevos comandos: ver how-to/adding-command.md.
• Nuevas tablas/campos: ver how-to/adding-migration.md.
• Ajustes de sincronización de grupos/miembros: ver how-to/adjusting-group-sync.md.
• Nuevas variables de entorno: ver how-to/adding-env.md.
• Nuevas métricas: usar Metrics.inc/set/get y documentar en operations.md.

Observabilidad y errores

• Logging pragmático en operaciones críticas; errores de migración detienen el arranque.
• Métricas:
  • sync_runs_total, contadores de alias resueltos, etc.
  • Estados de gauges/counters expuestos en /metrics (Prom/JSON).