# Visión general

Qué hace el sistema
- Ingesta de webhooks de WhatsApp (Evolution API) y ruteo de eventos.
- Parsing de comandos de texto y operaciones sobre tareas.
- Sincronización periódica de grupos y miembros.
- Control de acceso por grupos (allowed_groups) con modos off/discover/enforce y comandos /admin.
- Recordatorios a usuarios según preferencias.
- Cola de respuestas con reintentos/backoff.
- Métricas y health para operación.

Flujos principales
1) Mensaje entrante
   - src/server.ts recibe webhook → extrae texto → delega en src/services/command.ts (CommandService).
   - CommandService puede interactuar con src/tasks/service.ts (crear/actualizar/consultar tareas) y encolar respuestas en src/services/response-queue.ts.
2) Schedulers
   - src/services/group-sync.ts sincroniza grupos activos y sus miembros.
   - src/services/reminders.ts consulta preferencias y encola recordatorios.
   - src/services/maintenance.ts aplica retención de miembros inactivos.
3) Persistencia
   - src/db.ts abre SQLite (data/tasks.db por defecto), aplica PRAGMAs (WAL, FK, etc.) y migraciones (src/db/migrations).
4) Observabilidad
   - src/services/metrics.ts expone contadores/gauges; /metrics en src/server.ts.

Glosario
- JID: identificador completo de WhatsApp (p.ej., 12345@s.whatsapp.net, 999@g.us).
- user_id: número normalizado (solo dígitos) sin dominio.
- groupId: JID de grupo, termina en @g.us.
- Alias: identificador alternativo que mapea a user_id real (src/services/identity.ts).

Mapa rápido
- Entrada HTTP: src/server.ts
- DB y migraciones: src/db.ts, src/db/migrations/index.ts
- Servicios: src/services/*.ts (command, contacts, group-sync, identity, maintenance, metrics, rate-limit, reminders, response-queue, webhook-manager)
- Utilidades: src/utils/*.ts (whatsapp, formatting, etc.)
- Tareas: src/tasks/*.ts (modelo y servicio)
- Tests: tests/unit/**/*.test.ts

Siguientes lecturas
- architecture.md para responsabilidades por módulo.
- database.md para entender tablas y PRAGMAs.
- operations.md para variables de entorno, métricas y schedulers.
- tests-map.md para ver qué se valida y dónde extender cobertura.