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