# 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}.