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).

Control de acceso por grupos (allowed_groups)

• Esquema: tabla allowed_groups (group_id PK, label, status: pending|allowed|blocked, discovered_at/updated_at, discovered_by).
• Servicio: AllowedGroups con caché en memoria e interfaz isAllowed, setStatus, upsertPending, listByStatus, seedFromEnv.
• Flujo:
  • Discover (GROUP_GATING_MODE='discover'): ante tráfico de un grupo desconocido, se registra como pending y se retorna temprano; opcionalmente se notifica a ADMIN_USERS (NOTIFY_ADMINS_ON_DISCOVERY='true').
  • Enforce (GROUP_GATING_MODE='enforce'): se ignoran mensajes/comandos en grupos no allowed; /admin tiene bypass para permitir aprobación in situ.
• Superficies aplicadas:
  • server.ts: retorno temprano en discover y enforce; excepción para /admin.
  • services/command.ts: guard de enforce para evitar procesar comandos de grupos no allowed.
  • services/group-sync.ts: sincronización de miembros salta grupos no allowed (incluye scheduler).
  • tasks/service.ts: en enforce, crear tareas con group_id=null si el grupo no está allowed (compatibilidad).
  • reminders.ts: omite tareas/grupos no allowed al generar recordatorios en enforce.
• Observabilidad:
  • Gauges allowed_groups_total_* y counters unknown_groups_discovered_total, messages_blocked_group_total, commands_blocked_total, sync_skipped_group_total, admin_actions_total_{allow,block}.