Ruta(s): apps/backend (API Express + TypeScript + Mongoose, desplegada en Railway) y los route handlers de apps/web/src/app/api · Archivos principales: src/index.ts, src/routes/, src/controllers/, src/services/, src/models/, src/middleware/, src/config/ · Prioridad: P0 · Esfuerzo total: XL (≈ 36 semanas-dev de backend entre la Fase 0 y la Fase 4, de las cuales ≈ 19 corresponden a las Fases 0 y 1; detalle en Tareas)

Esta página es el plan técnico del backend. Para cada módulo dice qué hace hoy, en qué estado está y qué se decide: mantener, refactorizar, mover a un servicio aparte o eliminar. También describe los componentes nuevos que necesita el Sistema de demos: modelos, rutas, mensajería unificada, jobs, almacenamiento y configuración.

• La especificación funcional de solicitudes, accesos, estados y permisos está en Sistema de demos. Esta página no la repite: explica cómo se construye y cómo se opera.
• Las pantallas que consumen esta API están en Panel de administración y Portal del cliente.
• La wiki es pública. La seguridad se trata solo como tareas genéricas (sección 16 del plan y Seguridad y calidad).

• En una mirada
• Objetivo
• Estado actual
• Problemas detectados
• Plan detallado
  1. Arquitectura objetivo · 2. Decisiones de arquitectura · 3. Plan por módulo · 4. Componentes nuevos del sistema de demos · 5. Mensajería unificada · 6. Jobs y worker · 7. Persistencia y almacenamiento · 8. Redis · 9. Variables de entorno con zod · 10. Estructura de carpetas · 11. Convenciones de la API · 12. Swagger / OpenAPI · 13. Observabilidad, despliegue y entornos · 14. Inventario de la API objetivo · 15. Limpieza de código muerto · 16. Seguridad
• Integración con el sistema de demos
• SEO · i18n · accesibilidad · rendimiento
• Tareas
• Métricas de éxito

El backend tiene que sostener el negocio que describen Visión de producto y Flujo del cliente:

1. Sostener el funnel de la Fase 1 de punta a punta: solicitud de demo → aprobación → acceso verificado en el servidor → uso medido → propuesta. Ningún paso puede depender de un archivo en disco ni de un paso manual fuera del panel.
2. Controlar el costo de la IA. Las demos públicas (asistente RAG, "Prueba con tu documento", contenido) llaman a modelos de pago. Toda llamada pasa por cupos y por un tope mensual.
3. Poder vender por partes.
   • El chatbot RAG es el primer producto que pasa a SaaS real (Fase 4).
   • El vertical de salud se ofrece como instancia dedicada por cliente (Demo cuentas médicas).
   • El resto de soluciones a medida se demuestra con maquetas.
4. Ser operable por un equipo pequeño:
   • desplegar sin perder datos;
   • salud visible de jobs y mensajes;
   • alertas;
   • documentación generada;
   • pruebas en CI.
5. Cumplir la Ley 1581: prueba del consentimiento, retención, supresión, transmisión a proveedores declarada y registros técnicos sin datos personales.

flowchart LR
  U["Navegador"]
  subgraph VC["Vercel: web Next.js 14"]
    WP["Páginas, demos, portal y panel"]
    WR["Route handlers: proxy del chatbot heredado, LinkedIn Ads con OpenAI, TRM"]
  end
  subgraph RW["Railway: backend Express en un solo proceso"]
    IDX["index.ts: helmet, CORS, rate-limit en memoria, Swagger"]
    RT["22 archivos de rutas, 179 endpoints"]
    SV["Controladores y servicios, aprox. 65 por ciento salud"]
    FS[("Disco efímero: uploads, estado del chatbot en JSON, decisiones de IA, logs")]
    MOD["src/modules: 18 módulos en memoria sin montar"]
  end
  DB[("MongoDB")]
  RD[("Redis: tokens de refresco y de restablecimiento")]
  S3[("S3 opcional, solo documentos")]
  AI["OpenAI y Anthropic, modelos fijos en el código"]
  MSG["SMTP y WhatsApp: Twilio, Business API o UltraMsg"]
  U --> WP
  U -->|"llamadas directas con CORS"| IDX
  WP --> WR
  WR --> IDX
  WR --> AI
  IDX --> RT --> SV
  SV --> DB
  SV --> RD
  SV --> FS
  SV --> S3
  SV --> AI
  SV --> MSG

Ver diagrama como imagen

• La web llama al backend directamente desde el navegador, a la URL pública de Railway (apps/web/src/lib/backend-url.ts). Solo el chatbot heredado pasa por un proxy de Next.
• La generación de LinkedIn Ads llama a OpenAI desde Vercel (apps/web/src/app/api/linkedin-ads/generate/route.ts), por fuera del backend.

• Variables de entorno: se leen en 40 archivos con process.env.X || 'valor'. .env.example no lista varias que el código usa (JWT_REFRESH_SECRET, SMTP_*, TWILIO_*, FRONTEND_URL, ANTHROPIC_API_KEY) y sí lista otras sin uso (MONGO_URI).
• Dependencias declaradas sin uso:
  • zod: 0 importaciones, aunque Sistema de demos lo adopta como estándar de validación;
  • @pinecone-database/pinecone: solo lo usa services/embedding.service.ts, que nadie importa;
  • pdf-poppler: sin uso.
• Tres implementaciones de embeddings con dos modelos distintos:
  • document-ai.service.ts usa ada-002;
  • embeddings.service.ts usa 3-small;
  • embedding.service.ts también usa ada-002 y está muerto.
• Duplicación en salud:
  • 3 controladores de auditoría (auditoria, auditoria-medica, auditoria-modular);
  • 4 generadores de Excel;
  • 5 extractores de PDF (extraccion-dual tiene 1.017 líneas).
• TypeScript: tsconfig.json con strict: false.
• Pruebas: npm test corre Jest sin configuración para TypeScript, y los 14 archivos de prueba del backend están en src/modules/*/__tests__, que no se montan. El CI (.github/workflows/ci.yml) levanta PostgreSQL y no corre (ver Diagnóstico).
• Servidores y scripts sueltos: src/index-minimal.ts, test-db.js, test-simple.js, test-startup.js, src/test-pdf-processing.ts, src/verify-excel.ts.
• Restos de PostgreSQL: src/db/migrations/*.sql, src/db/seeds/001_sample_projects.sql, packages/database/init.sql y src/config/database.ts.

Las tres demos que dependen de APIs reales del backend se ven vacías o con error en producción:

1. El estado vive en un disco que se borra.
   • Archivos de clientes y prospectos, bots del chatbot, decisiones de la IA, exportes y logs se pierden en cada despliegue.
   • Por la misma razón, no se pueden correr dos instancias.
2. Las sesiones dependen de Redis y admiten un solo dispositivo.
   • Una clave de refresco por usuario: entrar desde el celular cierra la sesión del portátil.
   • Si Redis falla, nadie puede renovar su sesión.
3. Los permisos son gruesos.
   • Un solo filtro admin/manager para todo /api/admin.
   • No existen los roles sales, prospect ni client.
   • La verificación de pertenencia (que un recurso sea del usuario que lo pide) es irregular.
   • La autorización de todas las rutas se audita en la Fase 0 (sección 16).
4. La IA no tiene control de costo.
   • Los nombres de modelo aparecen escritos en 19 archivos.
   • El gasto no se mide por función, visitante ni acceso, así que no se ve en ningún panel.
   • Los límites de uso y de costo están repartidos y deben centralizarse (sección 16).
   • La ruta de LinkedIn Ads gasta desde Vercel, por fuera del backend.
5. El trabajo pesado corre dentro de la petición HTTP.
   • El servidor amplía los tiempos de espera a 15 minutos.
   • Un despliegue o un reinicio a mitad del proceso pierde el trabajo.
   • El navegador puede cortar la conexión antes de que termine.
6. La plataforma y el vertical de salud están mezclados.
   • Salud es ≈ 65 % del código y tiene rutas montadas en la raíz /api.
   • Muchos servicios están duplicados.
   • Hay referencias a un pagador real en el código (ver Demo cuentas médicas).
7. Hay dos APIs de chatbot y tres de embeddings. El reposicionamiento RAG necesita un núcleo de ingesta, búsqueda y citas.
8. No existe el dominio comercial.
   • Contact es un buzón.
   • Quote es un formulario sin uso.
   • No hay Lead, solicitud, acceso, bitácora ni outbox. Todo eso lo especifica Sistema de demos.
9. Los mensajes se envían "y ojalá lleguen".
   • El controlador dispara email y WhatsApp sin esperar ni reintentar.
   • No queda registro del envío.
   • Hay 3 proveedores de WhatsApp a medio configurar.
   • Resuelto para los avisos al dueño en la rama ccr-55ceecf7-dpc10i (pendiente de merge): registro por canal en Contact.notificaciones, reintentos, prueba mensual, webhook firmado de WhatsApp y un solo proveedor por canal (Resend y Meta). Ver 3.5.
   • Los registros técnicos incluyen datos personales del formulario.
10. La configuración no se valida.
    • Faltan variables en .env.example.
    • Hay valores por defecto con datos de entorno dentro del código.
    • Si falta una variable, el servidor arranca igual y falla después.
11. No hay red de seguridad de calidad: sin pruebas que corran, sin CI válido, sin strict y con dependencias desactualizadas.
12. La documentación de la API es parcial. Además, el cliente de la web (lib/api.ts, types/api.types.ts) está escrito a mano y se desalinea del backend.
13. Hay código muerto que confunde.
    • 18 módulos con 126 endpoints parecen un backend para las demos, pero no están montados.
    • Además: copias .bak, SQL, un chat de eco, rutas de prueba y servidores alternativos.
14. Las demos con backend real fallan en producción (capturas de arriba). No hay verificación de salud (/ready), ni prueba de humo, ni alerta.

flowchart LR
  U["Navegador"] --> PG["Web Next.js en Vercel: páginas, portal y panel"]
  U --> MW["Middleware de Next: pase de demo"]
  MW --> DP["Ruta /api/demo-pass"]
  DP -->|"cabecera interna"| API
  PG -->|"cookies httpOnly en el subdominio de la API"| API
  subgraph RW["Railway"]
    API["Servicio api: Express con createApp"]
    WK["Servicio worker: colas BullMQ y jobs, Fase 2"]
  end
  subgraph PL["Plataforma, en capas"]
    direction LR
    P1["Autenticación, usuarios y permisos"]
    P2["Leads, sistema de demos, privacidad, bitácora y métricas"]
    P3["Portal: proyectos, pedidos, facturas, entregables y mensajes"]
    P4["Propuestas y pagos, Fase 3"]
  end
  subgraph MD["Módulos de producto, Fase 2"]
    direction LR
    M1["rag-core: ingesta, búsqueda híbrida y citas"]
    M2["chatbot y Prueba con tu documento"]
    M3["documentos"]
    M4["content-ai"]
    M5["salud: cuentas médicas y motor de reglas"]
  end
  API --> PL
  API --> MD
  M2 --> M1
  M3 --> M1
  M5 --> M1
  API --> OB["Outbox OutboundMessage"]
  WK --> OB
  OB --> CH["Email transaccional, WhatsApp Cloud API, Slack y avisos en la app"]
  API --> GW["Pasarela de IA: cupos, tope mensual y AiUsage"]
  WK --> GW
  GW --> AI["OpenAI y Anthropic"]
  API --> DB[("MongoDB con réplica: datos, sesiones, tokens y vectores")]
  WK --> DB
  API --> RD[("Redis: rate-limit, caché y colas")]
  WK --> RD
  API --> S3[("Almacenamiento de objetos privado")]
  WK --> S3
  API --> OBS["Logs JSON, Sentry, health y ready"]

Ver diagrama como imagen

Principios:

1. El servidor decide. Toda regla de acceso, permiso, cupo y vigencia se evalúa en la API. La web solo oculta botones.
2. Nada importante en disco. MongoDB guarda datos y estado; el almacenamiento de objetos, los archivos; el disco, solo temporales del trabajo en curso.
3. Plataforma en capas, productos en módulos.
   • La plataforma comercial sigue la convención de Sistema de demos: models/, routes/, controllers/, services/.
   • Cada producto vive en src/modules/<producto>/, con sus rutas, modelos, esquemas y pruebas, y se puede apagar con una variable.
4. Trabajo pesado fuera de la petición.
   • Fase 1: jobs programados con node-cron dentro de la API.
   • Fase 2: colas en un worker aparte.
5. Toda llamada a IA pasa por la pasarela. Así hay un solo lugar para cupos, topes, modelos y registro de costo.
6. Todo mensaje sale por el outbox. Así hay un solo lugar para reintentos, idempotencia, horarios y bajas.
7. El contrato se genera. Los esquemas zod validan las entradas, generan el OpenAPI y, de ahí, los tipos de la web.

Cada subsección dice qué hace el módulo, su estado, la decisión y los cambios. Las tareas citadas son las de la tabla de tareas de esta página, salvo que se diga otra página.

/api/auth · routes/auth.routes.ts, controllers/auth.controller.ts, config/passport.ts, middleware/auth.ts · 9 endpoints

• Qué hace: registro local, inicio de sesión, refresco, cierre de sesión, perfil, inicio con Google, recuperar y restablecer la contraseña.
• Estado:
  • JWT de acceso de 15 min, con el rol dentro del token (middleware/auth.ts líneas 35–42).
  • Refresco JWT de 7 días guardado en Redis bajo una sola clave por usuario.
  • El restablecimiento está bien resuelto (token aleatorio en hash, 1 h, un solo uso), pero también depende de Redis.
  • Google crea las cuentas con rol user (config/passport.ts líneas 60–64).
• Decisión: refactorizar. Los endpoints se mantienen; cambian el almacenamiento de la sesión, los roles y la forma de entregar las credenciales.
• Cambios:
  1. Roles sales, prospect y client, más accountStatus, tokenVersion y la migración migrate-roles.ts. Es la tarea 1 de Sistema de demos.
  2. AuthSession en MongoDB, con rotación del refresco, detección de reutilización y máximo de sesiones por rol. Es la tarea 9 de Autenticación.
  3. Cookies httpOnly y la API en un subdominio propio del dominio principal (tarea 8 de Autenticación).
     • authenticate lee la cookie.
     • Authorization: Bearer se acepta solo en llamadas de servidor a servidor con INTERNAL_API_KEY.
  4. MagicLinkToken con los propósitos invitacion, acceso, verificacion y reset. Reemplaza las claves de Redis.
  5. Middlewares nuevos en middleware/auth.ts: optionalAuthenticate y requirePermission('<permiso>') sobre config/permissions.ts. authorize(...roles) queda como alias mientras se migran las rutas.
  6. Endpoints nuevos: POST /api/auth/logout-all, POST /api/auth/change-password, PATCH /api/me/profile y los de enlace mágico (sección 14).
  7. El callback de Google fija las cookies, sin credenciales en la URL, y activa a los invitados cuyo email coincide (tarea 10 de Autenticación).
  8. Validación con zod, respuestas uniformes para no revelar qué cuentas existen y logs sin emails en claro.

/api/admin · routes/admin.routes.ts, controllers/admin.controller.ts (535 líneas) · 13 endpoints

• Qué hace: pedidos (listar, cambiar estado, aprobar, rechazar, facturar), facturas, entregables, conversaciones, usuarios (listar y cambiar rol) y contactos.
• Estado:
  • Un solo controlador mezcla 6 recursos.
  • Todo el router usa el mismo filtro de roles, así que sales no podría ver contactos aunque se creara el rol.
• Decisión: refactorizar.
• Cambios:
  1. Partir admin.controller.ts en admin-orders, admin-billing, admin-users y admin-contacts. Cada ruta con su propio requirePermission.
  2. Los recursos comerciales nuevos van en rutas de primer nivel (/api/demo-requests, /api/leads…), no bajo /api/admin (decisión 16 de Sistema de demos).
  3. Agregados que pide Panel de administración (sección 4.7):
     • PATCH /api/admin/users/:id/status;
     • POST /api/admin/invoices y PATCH /api/admin/invoices/:id/status;
     • POST /api/admin/deliverables;
     • GET /api/metrics/admin-home;
     • conteos del outbox y del gasto de IA en GET /api/admin/jobs/health;
     • exportes CSV (Fase 2);
     • GET /api/admin/projects (Fase 3).
  4. PATCH /api/admin/users/:id/role valida contra el enum, incrementa tokenVersion y escribe en AuditLog.
  5. Validación zod, 400/404 uniformes y una sola respuesta por petición (tarea 4 de Panel de administración).
  6. La promoción a administrador sale del arranque (index.ts líneas 143–157) y queda solo en scripts/set-admin.ts, que deja registro en AuditLog.

/api/contact · routes/contact.routes.ts, controllers/contact.controller.ts, models/Contact.ts · 3 endpoints (1 real y 2 de prueba)

• Qué hace: guarda el mensaje del formulario y avisa al equipo por WhatsApp y por email.
• Estado:
  • En main, service es obligatorio, así que "Prueba con tu documento" no encaja. La rama rag-reposicionamiento (hecho, pendiente de merge) lo resuelve con services/lead.service.ts (registerLead), que comparten el formulario y la demo.
  • Los avisos se disparan sin esperar y sin reintento.
  • El log escribe nombre, email y teléfono.
  • Hay dos rutas de prueba en el mismo router.
  • Estado al 14 de octubre de 2026 (rama ccr-55ceecf7-dpc10i (pendiente de merge)): las rutas de prueba se eliminaron (cambio 5) y el aviso al dueño queda registrado por canal con reintentos (sección 3.5). El cambio 4 (outbox con plantillas) sigue pendiente: los avisos salen por services/owner-notify.service.ts, no por el outbox.
• Decisión: refactorizar. POST /api/contact pasa a ser el canal único de Leads fuera del formulario de demo.
• Cambios:
  1. Upsert del Lead por email, ConsentRecord y Contact con leadId, source (contacto o demo_rag), offeringSlug y plan. Es la tarea 4 de Sistema de demos. Hecho en la rama rag-reposicionamiento (pendiente de merge): Contact.source con los valores contact-form y demo-rag; la migración del Lead los normaliza a contacto y demo_rag.
  2. Turnstile, honeypot y tiempo mínimo de llenado (sección 15 de Sistema de demos).
  3. "Prueba con tu documento" no pasa por POST /api/contact ni usa ticket: la API /api/demo-rag recibe el email y la autorización junto con el archivo y registra el lead con el mismo servicio (sección 3.7).
  4. Los avisos al equipo salen por el outbox, con plantillas y sin datos de contacto del prospecto en WhatsApp.
  5. Se eliminan las rutas de prueba de email y WhatsApp de este router (sección 15).
  6. Los logs registran solo el id del Lead, nunca el email.

Es el bloque principal de la Fase 1 y está especificado en Sistema de demos:

• modelos: sección 5;
• estados: sección 6;
• API: sección 8;
• control de acceso: sección 10;
• tareas de backend: 1 a 15.

La sección 4 de esta página resume dónde vive cada pieza en el código y qué agrega el backend: pasarela de IA, almacenamiento y salud de los jobs.

services/email.service.ts (293 líneas), services/whatsapp.service.ts (376 líneas), utils/notifications.ts (221 líneas), models/Notification.ts

• Qué hace:
  • avisos de contacto y de pedidos;
  • email de restablecimiento de contraseña;
  • avisos dentro de la app (Notification con 7 tipos).
• Estado:
  • SMTP con valores por defecto en el código.
  • WhatsApp con 3 proveedores posibles (Twilio, Business API y UltraMsg).
  • Cada controlador llama directamente al servicio.
• Decisión: refactorizar hacia la mensajería unificada de la sección 5.
• Estado al 14 de octubre de 2026 (rama ccr-55ceecf7-dpc10i (pendiente de merge)), avisos al dueño:
  • Correo: Resend por API HTTPS (RESEND_API_KEY) para todos los correos del backend; SMTP queda como respaldo con tiempos de espera, porque Railway Free, Trial y Hobby bloquean el SMTP saliente. Destino NOTIFY_EMAIL (o ADMIN_EMAIL), remitente por defecto KopTup <[email protected]>, Idempotency-Key y reply_to.
  • WhatsApp: solo WhatsApp Cloud API de Meta con la plantilla aprobada koptup_aviso (2 variables), Graph v25.0 configurable, lectura del JSON de error de Meta y respaldo hello_world. Twilio y UltraMsg se eliminaron, también la dependencia twilio.
  • Registro y reintentos: Contact.notificaciones por canal (estado, intentos, error, id del proveedor), job de reintentos cada 5 minutos, latido mensual y estado de salud en AppSetting avisos.estado.
  • Panel y API: GET /api/admin/notifications/status, POST /api/admin/notifications/test, POST /api/admin/contacts/:id/notify y webhook firmado POST /api/webhooks/whatsapp (API › 4.15).
  • Sigue pendiente lo demás de la sección 5: outbox OutboundMessage, plantillas editables, Slack y avisos en la app.

No existen hoy. Se crean con el sistema de demos (sección 12 de Sistema de demos) y se amplían en la sección 6 de esta página.

/api/chatbot · routes/chatbot.routes.ts, services/chatbot-store.service.ts, models/ChatbotBot.ts, services/chatbot-legacy-cleanup.service.ts · estado al 14 de octubre de 2026 en la rama ccr-55ceecf7-dpc10i (pendiente de merge)

• Qué hace:
  • API de bots (los tres modos de /demo/chatbot y el widget /embed/chatbot/<id>): crear y configurar bots, subir documentos en base64 (TXT, MD, CSV, PDF y DOCX), indexar páginas web públicas (POST /bots/:id/urls), preguntar y ver conversaciones.
    • Recupera fragmentos con BM25 simplificado.
    • Si hay clave de OpenAI y presupuesto, genera la respuesta con cita; si no, responde en modo extractivo con una nota que lo explica (en español o inglés según lang o el idioma del bot).
  • Bots de ejemplo compartidos (POST /sample-bots): «Prueba el asistente» pide el bot de cada empresa de ejemplo; el servidor lo identifica por la huella de su contenido, lo crea una sola vez y lo reutiliza. GET /models lo anuncia con sharedSampleBots: true.
  • API heredada "por sesión" (/session, /upload, /message, /info, /config, /messages, /documents): retirada (responde 404). Al arrancar, el backend borra lo que dejó: la colección chatbots (guardaba preguntas y documentos sin vencimiento) y uploads/chatbot.
• Estado:
  • Bots, documentos, fragmentos y conversaciones en MongoDB (chatbot_bots, chatbot_bot_chunks, chatbot_turns); las conversaciones del widget vencen a los 30 días (índice TTL). El archivo heredado state.json se migra una vez y se borra.
  • Propiedad por token del navegador (X-Bot-Owner-Token), tope de gasto mensual (CHATBOT_MONTHLY_BUDGET_USD) y cupos por IP: 180 consultas por minuto (sin contar GET /models), 60 preguntas por minuto y 30 bots nuevos por hora.
  • Reglas de respuesta con fuente (GROUNDING_RULES) y la API /api/demo-rag de "Prueba con tu documento", con el pipeline compartido en services/rag-pipeline.ts.
  • Los modelos están en una constante del archivo.
  • Es el producto principal del reposicionamiento (Sistemas RAG, Reposicionamiento RAG).
• Decisión: refactorizar la API de bots y eliminar la heredada (eliminada el 14 de octubre de 2026).
• Cambios:
  1. Persistencia (Fase 0, tarea 10). Hecha en MongoDB (ChatbotBot, ChatbotBotChunks, ChatbotTurn); los archivos no se guardan, solo su texto en fragmentos.
     • Migración idempotente desde state.json.
     • Los bots de demo anónimos llevan expiresAt.
  2. Pasarela de IA (Fase 0, tarea 5). Cupos por visitante (IP en hash y sessionId), por grant y tope mensual de la demo (DEMO_MONTHLY_BUDGET_USD). El modelo se elige por variable de entorno.
  3. "Prueba con tu documento" (Fase 1, tarea 15). Hecho en la rama rag-reposicionamiento (pendiente de merge) como API propia en /api/demo-rag. Contrato del backend, más abajo.
  4. Núcleo RAG (Fase 2, tarea 16).
     • Ingesta real de PDF y DOCX con pdf-parse y mammoth, que ya son dependencias.
     • Fragmentos con número de página.
     • Un solo modelo de embeddings.
     • Búsqueda híbrida con Atlas Vector Search.
     • Citas con página y fragmento.
     • Ingesta de URLs con límites de tamaño, tiempo y tipo de contenido, y lista de dominios permitidos.
  5. Grants (Fase 2). Un DemoGrant del chatbot amplía el cupo y crea un bot personalizado con el logo y el sector del prospecto (DemoGrant.customization).
  6. Retiro de la API heredada (Fase 2). Hecho: se eliminaron las 7 rutas, chatbot.controller.ts, chatbot.service.ts, models/Chatbot.ts, los proxies de Next y la página /preview, con una limpieza única al arrancar (chatbot-legacy-cleanup.service.ts).
  7. SaaS real (Fase 4, tarea 25). Organization y tenantId en todas las consultas, medición de conversaciones y cobro recurrente.

Modelo de datos del chatbot (Fase 0, ampliado en la Fase 2):

erDiagram
  Bot ||--o{ BotDocument : "tiene"
  BotDocument ||--o{ BotChunk : "se divide en"
  Bot ||--o{ BotMessage : "registra"
  DemoGrant |o--o{ Bot : "personaliza"
  Lead |o--o{ BotDocument : "sube en la demo"
  Bot {
    string botId UK
    string ownerType "demo grant org"
    objectid grantId FK
    objectid orgId FK
    string name
    date expiresAt
  }
  BotDocument {
    objectid id PK
    string botId FK
    string storageKey
    number pages
    string status "procesando listo error"
    objectid leadId FK
    date expiresAt
  }
  BotChunk {
    objectid id PK
    objectid docId FK
    string botId FK
    number page
    string text
    vector embedding "Fase 2"
  }
  BotMessage {
    objectid id PK
    string botId FK
    string sessionId
    string role
    number costUsd
    date createdAt
  }
  AiUsage {
    objectid id PK
    string feature
    string actorKey
    string model
    number costUsd
    date at
  }

Ver diagrama como imagen

Contrato de "Prueba con tu documento".

El comportamiento lo define el dueño: PDF, DOCX o TXT de hasta 5 MB y 30 páginas; solo email y autorización Ley 1581; 10 preguntas por documento; 3 documentos por IP al día; borrado a la hora; tope mensual; respuestas con cita.

Está hecho en la rama rag-reposicionamiento (pendiente de merge) como una API propia montada en /api/demo-rag (routes/demo-rag.routes.ts y services/demo-rag.service.ts), con el pipeline del chatbot movido a services/rag-pipeline.ts. No usa ticket, cuenta ni POST /api/contact: el email y la autorización viajan con el archivo, y el lead se registra con services/lead.service.ts, el mismo servicio del formulario de contacto (Contact.source = demo-rag). La misma rama agregó a chatbot.routes.ts las reglas para responder solo con los documentos y citar (GROUNDING_RULES).

• Encendido (falla cerrada): solo funciona con DEMO_UPLOAD_ENABLED=true, OPENAI_API_KEY y Redis conectado. Si falta algo, o si el gasto del mes llegó a DEMO_MONTHLY_BUDGET_USD, la subida y las preguntas responden 503 y la web muestra "Agenda una demo con nosotros".
• Almacenamiento: el archivo se recibe en memoria y nunca va a disco. El documento, sus fragmentos y su índice viven en un mapa en memoria con TTL de 1 hora y un barrido periódico; nada va a MongoDB ni al almacenamiento de objetos. Redis guarda solo el cupo diario por IP (con hash) y el gasto del mes.
• Modelo y costo: gpt-4o-mini fijo. El costo de cada respuesta se calcula con el uso que informa OpenAI y se suma al gasto del mes (mes UTC).
• Límites extra: además del cupo diario, hay un límite de solicitudes por IP cada 10 minutos en la subida y en las preguntas. La IP real depende de TRUST_PROXY_HOPS.

sequenceDiagram
  autonumber
  participant V as Visitante
  participant W as Web Next
  participant A as API demo-rag
  participant R as Redis
  participant O as OpenAI
  participant D as MongoDB
  W->>A: GET /api/demo-rag/status
  A->>R: Lee el gasto del mes
  A-->>W: Encendida o motivo, sin montos
  V->>W: Archivo, email y autorización Ley 1581
  W->>A: POST /api/demo-rag/documents con file, email y consent
  A->>A: Encendido, formato, tamaño, email y autorización
  A->>R: Reserva el cupo diario por IP
  A->>A: Extrae el texto, cuenta páginas y arma el índice en memoria
  alt Fuera de los límites
    A->>R: Devuelve el cupo si el documento se rechaza
    A-->>W: 4xx con un código estable y un mensaje claro
  else Dentro de los límites
    A->>D: Lead demo-rag por el servicio del formulario de contacto
    A-->>W: 201 con docId, páginas, preguntas disponibles y vencimiento
  end
  V->>W: Pregunta
  W->>A: POST /api/demo-rag/documents/:docId/questions
  A->>A: Reserva la pregunta y busca los fragmentos
  A->>O: Pregunta y fragmentos relevantes
  O-->>A: Respuesta y uso de tokens
  A->>R: Suma el costo al gasto del mes
  A-->>W: Respuesta con citas por página o fragmento y preguntas restantes
  Note over A: Un barrido periódico borra de memoria los documentos vencidos a la hora

Ver diagrama como imagen

Los errores responden {success: false, code, message} con códigos estables que la web traduce (por ejemplo invalid_format, file_too_large, too_many_pages, daily_limit, question_limit, budget_exhausted y demo_disabled).

Los eventos demo_upload y demo_start los emite la web con GA4, solo con consentimiento. Con la Fase 0, la pasarela de IA registra además el uso en AiUsage (feature = demo_doc) y el rate-limit pasa al almacén compartido; con la Fase 2, la demo usa el núcleo RAG (embeddings y búsqueda híbrida). El documento sigue sin guardarse fuera de la memoria.

/api/documents · routes/document.routes.ts, controllers/document.controller.ts (633 líneas), services/document-ai.service.ts, services/storage.service.ts, models/Document.ts · 11 endpoints

• Qué hace:
  • subir documentos, con análisis de IA (resumen, etiquetas, entidades) y embedding;
  • listar, buscar por similitud, explicar, carpetas, favoritos, papelera y estadísticas.
• Estado:
  • S3 es opcional y, sin credenciales, el archivo queda en disco.
  • La similitud se calcula en memoria sobre todos los documentos.
  • Usa ada-002, un modelo distinto del de CUPS.
  • En producción la demo muestra "Error al cargar documentos".
• Decisión: refactorizar. Sigue Gestor documental, tareas 1–4 y 8.
• Cambios:
  1. Separar por espacio (ownerType: muestra, grant, usuario) y verificar la pertenencia en cada consulta (Fase 0).
  2. Modo muestra público, de solo lectura, sobre un corpus sembrado con análisis y embeddings precalculados. Subir, OCR y "explicar" exigen un DemoGrant y respetan cupos (Fase 1).
  3. Almacenamiento de objetos obligatorio (Fase 0). Los documentos de un grant revocado o vencido se borran en ≤ 1 h con el job grant-cleanup.
  4. La búsqueda pasa al núcleo RAG con un solo modelo de embeddings (Fase 2). tenantId y la escala de 50.000 documentos por cliente llegan en la Fase 4 (tarea 15 de Gestor documental).
  5. En la semilla del catálogo, gestor-documentos debe llevar hasRealBackend = true (sección de integración).

/api/projects, /api/orders, /api/invoices, /api/deliverables, /api/messages, /api/notifications · 37 endpoints · services/project.service.ts (594 líneas) y 10 modelos

• Qué hace: es el portal del cliente que ya existe:
  • proyectos con miembros, tareas y actividad (ActivityLog);
  • pedidos con adjuntos y aprobación;
  • facturas con descarga y registro de pago;
  • entregables con aprobación y rechazo;
  • conversaciones y avisos.
• Estado:
  • Todas las rutas exigen sesión.
  • La regla de pertenencia por rol (cliente, equipo) no está centralizada.
  • Los adjuntos de pedidos van a uploads/orders.
  • El estado shipped de Order no aplica a software.
  • El pago de facturas no tiene pasarela detrás.
• Decisión: mantener y refactorizar.
• Cambios:
  1. Política de pertenencia común: client ve lo suyo, el equipo según su permiso. Con prueba de integración por recurso (Fase 1, tarea 22).
  2. Adjuntos y entregables en el almacenamiento de objetos, con descarga por URL firmada de 5 minutos.
  3. Campos Project.quoteId y Project.leadId para trazar la conversión (sección 5.2 de Sistema de demos). Notification.type suma demo, lead y quote.
  4. Hasta la Fase 3, el estado de pago de una factura lo registra el equipo (PATCH /api/admin/invoices/:id/status).
  5. Fase 3: adaptador de pagos (Wompi o PayU en COP, Stripe en USD) con webhooks firmados (tarea 24).
  6. Migración de Order.status: shipped pasa a completed, y se quita del enum.
  7. Quién crea proyectos y qué ve un prospect en el portal se define en Portal del cliente. El backend lo aplica con permisos.

/api/quotes · routes/quote.routes.ts, controllers/quote.controller.ts, models/Quote.ts · 1 endpoint

• Qué hace: un POST público que guarda nombre, email, servicio y descripción.
• Estado: ninguna página lo usa. El modelo no sirve para una propuesta real: no tiene ítems, montos, moneda ni vigencia.
• Decisión:
  • Fase 0, eliminar el POST público. Antes se confirma con 30 días de logs que nadie lo llama. La colección se conserva para la migración.
  • Fase 3, reconstruir como módulo de propuestas: Quote ampliado, rutas de equipo y enlace público con token (sección 8.5 de Sistema de demos), PDF, aceptación y anticipo (tarea 24).
  • En la Fase 1, "Solicitar propuesta" solo crea una tarea (decisión 14 de Sistema de demos).

/api/auditoria (21), /api raíz con /cuentas, /ley100, /process, /export (20), /api/cups (9), /api/liquidacion (8), /api/reglas-facturacion (8), /api/documentos-conocimiento (4) · 70 endpoints · ≈ 20.000 líneas

• Qué hace: auditoría de cuentas médicas.
  • Ingesta de PDF, extracción con IA (texto y visión), validaciones, motor de reglas y cálculo de glosas.
  • Auditoría paso a paso, decisión asistida por un modelo grande y retroalimentación para el aprendizaje.
  • Consulta de catálogos (CUPS, CIE-10, medicamentos, tarifarios).
  • Liquidación de radicados y exportes en Excel.
• Estado:
  • Es el mayor activo técnico, pero:
    • está fragmentado (3 controladores de auditoría, 5 extractores, 4 generadores de Excel);
    • procesa dentro de la petición;
    • guarda archivos en disco;
    • tiene referencias a un pagador real;
    • no tiene pruebas.
  • La demo /demo/cuentas-medicas solo usa /auditoria/* y /documentos-conocimiento/*.
  • /cuentas, /ley100, /process y /export no las llama ninguna página de la web (la página interna /test se retiró).
  • /liquidacion y /reglas-facturacion solo las llaman las páginas huérfanas /liquidacion.
  • Hay seeds (≈ 2.600 líneas en db/seeds/) y scrapers de catálogos oficiales (≈ 2.100 líneas) que ningún script de package.json ejecuta.
• Decisión: mover a un servicio aparte, por etapas. Se mantiene como producto vertical (Demo cuentas médicas).
• Cambios por fase:

Además:

• Seeds y scrapers pasan a apps/backend/tools/salud/ (fuera del build), con npm run seed:salud documentado.
• models/CUPSEquivalencia.ts (sin uso) se elimina.
• Los modelos maestros que hoy solo usan las seeds (EPSMaestro, IPSMaestro, ConvenioTarifa, CuotaModeradora, Autorizacion) se conservan para la tarea 7 de Demo cuentas médicas.

/api/expert · routes/expert-system.routes.ts, controllers/expert-system.controller.ts, services/expert-system.service.ts (596), expert-rules.service.ts (450), excel-expert.service.ts (393) · 6 endpoints

• Qué hace: procesa facturas con reglas, genera Excel, lee y actualiza la configuración del motor y da estadísticas. Su demo también usa la búsqueda semántica de CUPS.
• Estado:
  • La configuración no se guarda por espacio.
  • Las reglas están repartidas entre el código, ReglaAuditoria y ReglaFacturacion.
  • En producción la demo muestra todo en 0.
• Decisión: mover al módulo de salud como pestaña "Motor de reglas" (Demo sistema experto, tareas 4–6).
• Cambios:
  • Fase 1: requireDemoGrant('sistema-experto') en /api/expert/* y en /api/cups/estadisticas, /estadisticas-vectorizacion y /buscar-semantica.
  • Fase 2: catálogo único de reglas versionado, configuración persistente por espacio con historial, y migración de los accesos a cuentas-medicas.
  • Las rutas de importación y vectorización de CUPS (/importar-*, /vectorizar, /revectorizar) son tareas de operación: solo admin.

/api/content · routes/content-manager.routes.ts, services/content-manager.service.ts · 5 endpoints (improve, change-tone, adjust-length, generate-versions, generate)

• Qué hace: mejora, cambia el tono, ajusta la longitud y genera textos y versiones para la demo /demo/gestor-contenido, oferta cms-headless (ver CMS headless).
• Estado: valida con express-validator. El modelo se elige por variable o queda gpt-4o-mini. Sus límites de uso pasan a la pasarela de IA.
• Decisión: mantener, detrás de la pasarela de IA.
• Cambios:
  • Fase 0: pasarela de IA con cupo anónimo por IP (por defecto 10 acciones al día, configurable), cupo por grant (quotas.aiActionsPerDay) y tope mensual por función (tarea 5).
  • Fase 1: zod, límite de longitud de entrada y hasRealBackend = true en la semilla del catálogo (tarea 18).
  • Fase 2: mover a src/modules/content-ai/.

18 carpetas: automation, code-review, crm, delivery, e-invoicing, e-signature, erp, helpdesk, hrms, lms, loyalty, moderation, pos, saas-platform, scraping, telemedicine, voice-ai, wms · 125 archivos · ≈ 3.440 líneas · 126 endpoints · 14 pruebas

• Qué hace: CRUD sobre arreglos en memoria con datos de ejemplo (_shared/crud.ts).
• Estado:
  • Ninguno está montado en index.ts, y ninguna demo los llama: todas usan datos simulados en el frontend.
  • Sus 14 pruebas no corren.
• Decisión: eliminar en la Fase 0.
  • Se crea la etiqueta archivo/modulos-en-memoria antes de borrar.
  • Cuando una de esas soluciones se vuelva producto real (Fase 4 o por proyecto), se construye sobre el núcleo multi-tenant y no sobre estos arreglos.
  • La carpeta src/modules/ queda libre para los módulos de producto de la Fase 2.

Son parte de la Fase 1 (Sistema de demos, secciones 5, 13 y 14). En el backend agregan:

• AuditLog y services/audit.service.ts. Solo se agregan registros; ningún endpoint los edita ni los borra.
• PrivacyRequest, controllers/privacy.controller.ts y el job privacy-retention.
• controllers/metrics.controller.ts, con GET /api/metrics/demo-funnel y GET /api/metrics/admin-home.
  • Las consultas de agregación usan índices.
  • El inicio del panel guarda una caché de 30 s en Redis o, si no hay Redis, en memoria.

Dónde vive cada pieza. Los nombres y archivos son los de Sistema de demos, sección 17.

Pasarela de IA (services/ai-gateway.service.ts).

• Interfaz: ai.complete({feature, actor, model?, messages, maxTokens}), ai.embed({feature, actor, texts}) y ai.vision(...).
  • feature puede ser chatbot, demo_doc, content, documents, salud, linkedin o rules.
  • actor es {userId?, grantId?, ipHash?}.
• Antes de llamar al proveedor:
  • Verifica el cupo del actor, el tope mensual de la función y el global, y el interruptor de la función.
  • Si algo no alcanza, lanza AppError(429, 'presupuesto_agotado') o limite_excedido.
• Después de llamar: registra AiUsage con los tokens, el costo en USD (tabla de precios en config/ai-pricing.ts), el modelo y la latencia.
• Modelos por variable de entorno:
  • AI_MODEL_FAST (respuestas de demo, contenido);
  • AI_MODEL_SMART (auditoría, reglas);
  • AI_MODEL_VISION;
  • AI_EMBEDDING_MODEL (uno solo para todo).
• Alertas: el job ai-budget-watch avisa al admin al 80 % y al 100 % del tope. GET /api/admin/jobs/health muestra el gasto del mes por función.
• Ruta de LinkedIn Ads: se queda en Next con el pase de demo (Demo LinkedIn Ads, tarea 1), pero reporta su consumo con POST /api/internal/ai-usage, con la cabecera interna. Así el tope mensual es uno solo.

flowchart TD
  E1["Controladores y servicios"] -->|"enqueue con idempotencyKey"| OB[("OutboundMessage")]
  J1["Jobs: secuencias, recordatorios, resumen diario"] --> OB
  OB --> D["outbox-dispatcher cada minuto"]
  D --> R{"Reglas: horario, 1 comercial por día, baja, condición de parada"}
  R -->|"omitir o reprogramar"| OB
  R -->|"enviar"| T["Render de plantilla con escape"]
  T --> C1["Adaptador email: proveedor transaccional"]
  T --> C2["Adaptador WhatsApp: Cloud API o Twilio"]
  T --> C3["Adaptador in-app: Notification"]
  T --> C4["Adaptador Slack: webhook"]
  C1 --> ST["Estado: enviado, fallido con reintento, cancelado"]
  C2 --> ST
  C3 --> ST
  C4 --> ST
  WH["Webhooks de rebote y entrega, Fase 2"] --> ST

Ver diagrama como imagen

• Una sola entrada. notify.enqueue({channel, templateKey, to, vars, leadId?, userId?, grantId?, scheduledAt?, idempotencyKey}).
  • Ningún controlador vuelve a llamar a emailService o whatsappService directamente.
  • Se migran los envíos actuales: contacto, pedidos y restablecimiento de contraseña.
• Adaptadores en services/channels/, con la misma interfaz send(message) → {providerMessageId}. Son intercambiables por variable de entorno (EMAIL_PROVIDER, WHATSAPP_PROVIDER).
• Reglas (sección 11 de Sistema de demos):
  • horario de 8:00 a 19:00, hora de Bogotá;
  • máximo un mensaje comercial por Lead al día;
  • condiciones de parada de las secuencias;
  • lista de supresión: bajas y correos rebotados.
• Datos personales:
  • El WhatsApp al equipo nunca lleva el email ni el teléfono del prospecto. (La implementación de la rama ccr-55ceecf7-dpc10i (pendiente de merge) se aparta de esta regla a pedido del dueño: el aviso por WhatsApp lleva nombre, empresa, servicio, email y un extracto del mensaje, nunca el teléfono. /privacy lo declara y nombra a Meta como encargado.)
  • El WhatsApp al prospecto solo sale con su autorización (whatsappOptIn) y con una plantilla aprobada.
• Webhooks de proveedores (Fase 2): POST /api/webhooks/email y POST /api/webhooks/whatsapp, con firma verificada. Marcan rebotes y entregas, y suprimen direcciones inválidas. (Hecho para WhatsApp en la rama ccr-55ceecf7-dpc10i (pendiente de merge): firma X-Hub-Signature-256 sobre el cuerpo crudo, estados entregado, leído y fallido por wamid y alerta por correo si falla; sin tabla WebhookEvent. El de correo sigue pendiente.)
• Salud: conteos de programado, fallido y enviado en las últimas 24 h, en GET /api/admin/jobs/health, con alerta si hay más de 5 fallidos en una hora.
• Plantillas en el código, en español con "tú" e inglés cuando el Lead tenga locale = en. En la Fase 2 se pueden editar desde el panel (MessageTemplate).

Fase 1: dentro de la API.

• node-cron arranca después de conectar a MongoDB y solo si JOBS_ENABLED=true.
• Cada job toma un lease en JobRun, así que es seguro con varias instancias.
• Son los 8 jobs de la sección 12 de Sistema de demos, más estos:

Fase 2: worker aparte con colas.

flowchart TD
  subgraph APIS["Servicio api"]
    R1["POST de procesamiento: lote de facturas, ingesta RAG, exporte"] --> Q1["Encola el trabajo y responde 202 con jobId"]
    R2["GET del estado del trabajo"]
  end
  subgraph RDS["Redis"]
    Q["Colas BullMQ: rag-ingest, salud-process, exports"]
  end
  subgraph WRK["Servicio worker"]
    C1["Consumidores con concurrencia limitada y reintentos"]
    C2["Jobs programados con node-cron y lease en JobRun"]
    C3["outbox-dispatcher"]
  end
  Q1 --> Q
  Q --> C1
  C1 --> DB[("MongoDB: estado y resultado del trabajo")]
  C1 --> S3[("Almacenamiento: archivos y exportes")]
  R2 --> DB
  C2 --> DB
  C3 --> DB
  C3 --> P["Proveedores de email y WhatsApp"]

Ver diagrama como imagen

• Arranque. src/worker.ts comparte modelos y servicios con la API. En Railway es un segundo servicio desde la misma imagen (node dist/worker.js), con JOBS_ENABLED=true. La API pasa a JOBS_ENABLED=false.
• Colas:
  • rag-ingest: documentos de bots y del gestor documental;
  • salud-process: lotes de facturas;
  • exports: Excel y PDF.
• Comportamiento: cada trabajo guarda su estado en ProcessingJob (encolado, procesando, listo, fallido, más progreso y resultado). Se reintenta 3 veces con espera creciente y tiene un tiempo máximo por tipo.
• Efecto en la API: al terminar la migración, server.timeout vuelve a los valores por defecto (index.ts líneas 264–269). Ninguna petición HTTP dura más de 30 s.

MongoDB.

• Réplica obligatoria para las transacciones. En desarrollo, docker-compose.dev.yml levanta mongo:7 con --replSet rs0 y un script de inicio.
• Copias de seguridad diarias y restauración a un punto en el tiempo. La restauración se prueba una vez por trimestre y queda documentada en la página de operación.
• Un usuario de base por entorno, con permisos mínimos.
• Índices de Sistema de demos (sección 5), más:
  • AuthSession {userId, revokedAt} y TTL en expiresAt;
  • AiUsage {feature, at} y {actorKey, at}, con TTL de 13 meses;
  • BotChunk {botId} e índice vectorial de Atlas sobre embedding (Fase 2);
  • Document {ownerType, ownerId, is_deleted};
  • WebhookEvent {provider, eventId} único.
• Retenciones con TTL, alineadas con la sección 14 de Sistema de demos: DemoEvent 13 meses, BotMessage de demo 90 días y AiDecision 24 meses. Los documentos de "Prueba con tu documento" no llegan a MongoDB: viven solo en memoria 1 hora (sección 3.7).
• Migraciones:
  • archivos scripts/migrations/NNN-nombre.ts, registrados en la colección Migration;
  • se ejecutan con npm run migrate como comando previo al despliegue en Railway;
  • todas idempotentes y con --dry-run.

Almacenamiento de objetos (services/storage.service.ts ampliado).

• Bucket privado:
  • acceso público bloqueado;
  • cifrado del lado del servidor;
  • versión desactivada para los prefijos temporales.
• API del servicio: put({prefix, key, body, contentType, expiresAt?}), getSignedUrl(key, 300), delete(key) y deletePrefix(prefix).
• Validaciones de los archivos subidos:
  • extensión y firma real del contenido;
  • tamaño máximo por ruta;
  • nombre generado por el servidor, nunca el del usuario.
• Variables: se conservan las variables AWS_* actuales, más S3_ENDPOINT (opcional) para un proveedor compatible.
• Datos de salud de clientes reales: bucket dedicado por cliente (instancia dedicada).

Qué sale del disco:

• En Railway: el plugin de Redis en la misma red privada, con una contraseña que solo conoce el entorno.
• En desarrollo: el redis:7-alpine de docker-compose.dev.yml.
• Cliente: config/redis.ts se reescribe para que no esconda los errores en silencio.
  • Expone isAvailable().
  • Usa la conexión de ioredis que comparte BullMQ.
  • Cada uso declara su respaldo.

src/config/env.ts es el único lugar donde se lee process.env. Hay una regla de ESLint (no-restricted-properties) que impide usarlo en otros archivos. En producción, el servidor no arranca si falta una variable obligatoria o si una variable tiene un formato inválido. El mensaje de error nombra la variable, nunca su valor.

// apps/backend/src/config/env.ts (esqueleto)
import { z } from 'zod';

const list = z.string().default('').transform((s) => s.split(',').map((x) => x.trim()).filter(Boolean));
const flag = z.enum(['true', 'false']).default('false').transform((v) => v === 'true');

const EnvSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  PORT: z.coerce.number().int().default(3001),
  API_URL: z.string().url(),
  FRONTEND_URL: z.string().url(),
  CORS_ORIGIN: list,
  TRUST_PROXY: z.coerce.number().int().default(1),
  MONGODB_URI: z.string().min(1),
  REDIS_URL: z.string().optional(),
  JWT_SECRET: z.string().min(32),
  COOKIE_DOMAIN: z.string().optional(),
  INTERNAL_API_KEY: z.string().min(32),
  TURNSTILE_SECRET_KEY: z.string().min(1),
  OPENAI_API_KEY: z.string().optional(),
  ANTHROPIC_API_KEY: z.string().optional(),
  AI_MODEL_FAST: z.string().min(1),
  AI_MODEL_SMART: z.string().min(1),
  AI_EMBEDDING_MODEL: z.string().min(1),
  AI_MONTHLY_BUDGET_USD: z.coerce.number().positive(),
  DEMO_MONTHLY_BUDGET_USD: z.coerce.number().positive(),
  JOBS_ENABLED: flag,
  SALUD_ENABLED: flag,
  API_DOCS_ENABLED: flag,
  // ... almacenamiento, email, WhatsApp, avisos comerciales y observabilidad (tabla de abajo)
});

export type Env = z.infer<typeof EnvSchema>;

export function loadEnv(source: NodeJS.ProcessEnv = process.env): Env {
  const parsed = EnvSchema.safeParse(source);
  if (!parsed.success) {
    const names = parsed.error.issues.map((i) => i.path.join('.')).join(', ');
    throw new Error(`Configuración inválida o incompleta: ${names}`);
  }
  return parsed.data;
}

export const env = loadEnv();

Además:

• npm run env:example genera .env.example desde el esquema, solo con nombres y descripciones.
• CI falla si el archivo no coincide con el esquema.
• Las variables de la web (DEMO_PASS_SECRET, DEMO_GATE_ENABLED, NEXT_PUBLIC_BOOKING_URL, NEXT_PUBLIC_TURNSTILE_SITE_KEY) tienen su propio esquema en apps/web/src/config/env.ts.

Las variables que la rama rag-reposicionamiento (hecho, pendiente de merge) agrega al backend (DEMO_UPLOAD_ENABLED, DEMO_MONTHLY_BUDGET_USD, TRUST_PROXY_HOPS y DEMO_RAG_TTL_SECONDS, esta última solo para pruebas locales) y dónde se configura cada una están en Reposicionamiento RAG. El esquema zod las incorpora; como TRUST_PROXY_HOPS cumple la función de TRUST_PROXY, se deja un solo nombre.

apps/backend/
├── src/
│   ├── app.ts                  # createApp(): middlewares, rutas, 404 y errores (sin listen)
│   ├── server.ts               # conecta MongoDB, escucha el puerto y arranca jobs si JOBS_ENABLED
│   ├── worker.ts               # Fase 2: consumidores BullMQ y jobs programados
│   ├── config/                 # env.ts, permissions.ts, scoring.ts, ai-pricing.ts, openapi.ts, cors.ts
│   ├── middleware/             # auth, requireDemoGrant, rateLimiter, validate, requestId, internalApiKey, upload, errorHandler
│   ├── schemas/                # esquemas zod por recurso; fuente de la validación y del OpenAPI
│   ├── models/                 # plataforma: User, AuthSession, Lead, DemoRequest, DemoGrant, Project, Order...
│   ├── routes/                 # un archivo por recurso de plataforma (demo-requests, leads, me, webhooks...)
│   ├── controllers/            # un controlador por recurso; sin lógica de negocio
│   ├── services/               # demo-access, demo-state, magic-link, audit, ai-gateway, storage, notification-dispatcher...
│   │   └── channels/           # adaptadores email, whatsapp, inapp, slack
│   ├── jobs/                   # outbox-dispatcher, grant-lifecycle, grant-cleanup, ai-budget-watch...
│   ├── templates/              # demo/ y cuenta/ (ES y EN)
│   ├── modules/                # Fase 2: productos autocontenidos
│   │   ├── rag-core/           # ingesta, fragmentos, embeddings, búsqueda híbrida, citas
│   │   ├── chatbot/            # bots, demo-rag, conversaciones
│   │   ├── documents/          # gestor documental
│   │   ├── content-ai/         # asistente de contenido
│   │   └── salud/              # cuentas médicas, auditoría, CUPS, Ley 100, liquidación, reglas, motor de reglas
│   ├── scripts/                # set-admin, seed-demo-catalog, notify-smoke, migrations/NNN-*.ts
│   ├── utils/                  # business-hours (festivos CO), email-risk, hash, money
│   └── __tests__/              # integración con supertest, factories y fixtures
├── tools/                      # fuera del build: scrapers de catálogos oficiales y seeds de salud
├── openapi.json                # generado en CI
└── jest.config.ts

Reglas:

• Cada módulo de modules/ expone un register(app, deps) que monta sus rutas.
• Un módulo no importa los internos de otro; solo su index.ts.
• Los controladores no tocan modelos: llaman a servicios.
• Las pruebas viven junto al código (*.test.ts) o en __tests__/.
• tsconfig.json pasa a strict: true para routes/, controllers/, services/, schemas/ y modules/. Para el código heredado de salud se usa un tsconfig.legacy.json hasta su consolidación.

flowchart TD
  A["Petición"] --> B["requestId y logger"]
  B --> C["helmet y CORS con lista de orígenes"]
  C --> D["Parser JSON con límite de 1 MB"]
  D --> E["rate-limit con almacén compartido"]
  E --> F["authenticate u optionalAuthenticate"]
  F --> G["requirePermission o requireDemoGrant"]
  G --> H["validate con esquema zod"]
  H --> I["Controlador"]
  I --> J["Servicio de dominio"]
  J --> K["Modelos y adaptadores"]
  I --> L["Respuesta success y data"]
  G -->|"401 o 403"| X["errorHandler: success false, message y code"]
  H -->|"400"| X
  J -->|"409 o 422"| X

Ver diagrama como imagen

• Hoy: swagger-jsdoc lee comentarios de src/routes/*.ts y swagger-ui-express los sirve desde el mismo backend. Solo 9 de 22 archivos tienen anotaciones, sin los esquemas de respuesta. El cliente de la web se escribe a mano.
• Objetivo:
  1. Esquemas zod en src/schemas/. Cada ruta nueva declara body, query, params y la respuesta. El middleware validate(schema) los usa para validar.
  2. Registro OpenAPI (config/openapi.ts, con @asteasolutions/zod-to-openapi).
     • Cada esquema se registra con su ruta, método, permiso requerido (extensión x-permission) y ejemplos.
     • Esquemas de seguridad: cookie de sesión y cabecera interna.
  3. npm run openapi escribe openapi.json.
     • CI lo regenera y falla si hay diferencias sin confirmar.
     • CI también falla si una ruta montada no tiene esquema (scripts/check-routes.ts compara el inventario de Express con el OpenAPI).
  4. Documentación interactiva en /api/docs, solo si API_DOCS_ENABLED=true (desarrollo y staging). En producción la puede ver solo el equipo, con sesión de admin o developer.
  5. Cliente tipado para la web:
     • openapi-typescript genera apps/web/src/types/api.generated.ts.
     • lib/api.ts usa esos tipos y types/api.types.ts se retira por etapas.
     • Empieza por las rutas del sistema de demos (Fase 1).
  6. Retiro de swagger-jsdoc cuando todas las rutas vivas tengan esquema (Fase 2). Las rutas de salud se documentan al consolidarse en modules/salud.

Logs.

• winston con formato JSON a la salida estándar; se eliminan los 4 archivos de logs/.
• morgan se reemplaza por un middleware de registro que guarda requestId, método, ruta (patrón, no la URL con datos), estado, duración, userId en hash y feature.
• Destino externo con 30 días de retención, configurado como log drain de Railway.

Errores. @sentry/node en la API y en el worker, con requestId, sin cuerpos de petición y con beforeSend que limpia los datos personales.

Salud del servicio.

• Railway usa /ready como healthcheckPath en railway.json.
• Un monitor externo revisa /ready cada minuto.

Alertas (email y Slack del equipo):

• más de 2 % de respuestas 5xx en 5 minutos;
• /ready caído durante 2 minutos;
• un job atrasado el doble de su intervalo;
• más de 5 mensajes fallidos en una hora;
• gasto de IA al 80 %.

Despliegue.

• Node.js LTS activo (24) en el CI, en Railway (engines y .nvmrc) y en Docker. Hoy el CI declara 18, que ya no recibe soporte.
• Build: tsc y npm run openapi. Antes de desplegar se corre npm run migrate.
• Dos servicios desde la misma imagen: api con node dist/server.js y worker con node dist/worker.js (Fase 2).
• Reversión: si /ready falla después de desplegar, Railway vuelve a la versión anterior.

Entornos.

Estado: Nuevo, Modificado, Se mantiene o Se elimina. El detalle de cuerpos, permisos y reglas de los endpoints del sistema de demos está en Sistema de demos (sección 8). La página que propone cada agregado aparece en la última columna.

Públicos

Autenticación y cuenta

Portal (prospecto y cliente)

Equipo

En Next (apps/web/src/app/api)

Antes de borrar, se crea la etiqueta archivo/antes-de-limpieza. Después se comprueba que tsc, las pruebas y el build pasan, y que el inventario de rutas no perdió ninguna con consumidor.

Resultado esperado: ≈ 5.300 líneas menos en la Fase 0. En la Fase 2, ≈ 30 % menos de código en salud por consolidación, y ninguna herramienta offline dentro del build.

La revisión detallada no se publica porque la wiki es pública. Estas son las tareas del backend. El plan completo está en Seguridad y calidad.

• Auditar y exigir autenticación y autorización en el servidor en todas las rutas de la API:
  • matriz de permisos;
  • verificación de pertenencia;
  • prueba de tabla rol × ruta en CI (tarea 4).
• Límites de costo y rate-limit en todos los endpoints de IA, con la pasarela de IA y un almacén compartido (tareas 5 y 6).
• Rotar credenciales. Ningún secreto ni dato personal en el código, en la documentación ni en el historial que se publique. Los secretos viven solo en las variables de cada entorno (tarea 7).
• Actualizar dependencias y quitar las que no se usan. Auditoría de dependencias en CI (tarea 7).
• Proteger webhooks y retirar las rutas de prueba en producción. Webhooks con firma verificada e idempotencia (tareas 7 y 23).
• Archivos subidos:
  • tipo verificado por contenido;
  • tamaño máximo por ruta;
  • nombres generados por el servidor;
  • descarga solo por URL firmada (tarea 9).
• Sesiones y origen:
  • cookies httpOnly;
  • verificación de Origin en las escrituras;
  • lista de orígenes CORS desde la configuración;
  • trust proxy correcto (tarea 1 y Autenticación, tarea 8).
• Registros técnicos sin datos personales; errores sin detalles internos hacia el cliente (tarea 11).
• Documentación interactiva solo para el equipo (sección 12).
• Ingesta de URLs y documentos con límites de tamaño, tiempo, tipo y destino (sección 3.7).

Qué protege cada guardia del backend. Estas son las rutas reales que consume cada demo, verificadas en el código de apps/web:

Precisiones sobre Sistema de demos:

1. Sección 10.4. La búsqueda de CUPS la consume la demo del sistema experto, no la de cuentas médicas: esta usa un catálogo estático en el bundle (contenido-cups-completo.ts). Por eso la guardia de CUPS acepta los dos slugs.
2. cuentas.routes.ts y liquidacion.routes.ts. Se confirmó que ninguna demo del catálogo las usa. Quedan solo para el equipo, que es lo que la sección 10.4 dejaba pendiente de confirmar.
3. Semilla del catálogo.
   • gestor-documentos y gestor-contenido deben llevar hasRealBackend = true, porque llaman a /api/documents y /api/content.
   • quotas.aiActionsPerDay debe definirse también para gestor-contenido y chatbot.
   • El modo de acceso no cambia: siguen siendo publico.

Cómo se comunica la web con el backend en el control de acceso:

• GET /api/demo-access/:demoSlug acepta la sesión del usuario (cookie) o, desde /api/demo-pass, el token del usuario más la cabecera INTERNAL_API_KEY.
  • Con la cabecera interna, el rate-limit se aplica por usuario, no por IP, porque todas las llamadas llegan desde Vercel.
  • La respuesta es la misma en los dos casos.
• GET /api/demo-catalog/modes responde con Cache-Control: public, max-age=60, que coincide con la caché del middleware.
  • Si el backend no responde en 300 ms, la web usa el mapa estático de lib/demo-access.ts, generado desde la misma semilla.
  • Para solicitud y privado, falla cerrada.
• requireDemoGrant reutiliza evaluateAccess (sección 10.1 de Sistema de demos).
  • Para staff, permite el paso sin registrar el evento.
  • Para prospectos, registra key_action cuando la ruta está marcada como acción clave del catálogo.
• PATCH /api/demo-catalog/:slug invalida la caché de modos en Redis. En ≤ 60 s el cambio llega a todas las instancias de la API y al middleware.

• SEO:
  • el dominio de la API envía X-Robots-Tag: noindex;
  • GET /api/demo-catalog/modes alimenta el sitemap.ts de la web: las demos solicitud y privado quedan fuera;
  • /health, /ready y /api/docs nunca aparecen en el sitemap.
• i18n:
  • La API responde códigos estables (sección 11) y la web los traduce a ES y EN.
  • Las plantillas de mensajes existen en español (con "tú") y en inglés.
  • El idioma se toma de User.locale o Lead.locale, con español por defecto.
  • Fechas en UTC en la API y formateadas por la web. Plazos hábiles con festivos de Colombia (utils/business-hours.ts).
• Accesibilidad (emails):
  • cada plantilla tiene versión en texto plano;
  • botones con texto descriptivo ("Activar mi acceso", nunca "clic aquí");
  • imágenes con alt;
  • contraste suficiente.
• Rendimiento:
  • Metas (p95, medidas con los logs de duración):
    • lecturas del panel < 300 ms;
    • GET /api/demo-access < 150 ms;
    • POST /api/demo-requests < 800 ms (incluye Turnstile y MX con tiempo máximo);
    • respuesta de "Prueba con tu documento" < 6 s.
  • Técnicas:
    • consultas con .lean() y proyección;
    • índices de la sección 7;
    • paginación con máximo 100;
    • caché de modos y del inicio del panel;
    • JSON limitado a 1 MB (hoy 10 MB) y archivos solo por multipart;
    • compresión activa;
    • pool de conexiones de MongoDB según el número de instancias;
    • nada pesado dentro de la petición desde la Fase 2.

Tallas para 1 dev senior: S ≤ 2 días · M 3–5 días · L 1–2 semanas · XL más de 2 semanas. Las tareas de backend del sistema de demos ya están detalladas en Sistema de demos (tareas 1–15) y aquí aparecen agrupadas en la tarea 13.

Total: ≈ 180 días-dev de backend (≈ 36 semanas con 1 dev). Con 2 devs, las Fases 0 y 1 caben en ≈ 10–11 semanas de calendario.

• Sistema de demos · Flujo del cliente · Panel de administración · Portal del cliente
• Autenticación · Contacto · Legal
• Sistemas RAG · Gestor documental · CMS headless · Demo cuentas médicas · Demo sistema experto · Demo LinkedIn Ads
• Diagnóstico · Visión de producto · Catálogo de productos · Seguridad y calidad · Comercial, marketing y legal · Roadmap