Arquitectura del Backend CRM

Fases 22.0–48. Estado: DESPLEGADO (VPS en vivo, 68+ endpoints, arquitectura modular). Última actualización: 2026-04-28 (Fase 48 — Descomposición de Arquitectura)

Resumen

Browser (:18888)
  │
  ├── Archivos estáticos ──► Nginx ──► Docker frontend (React + Nginx)
  │
  ├── /api/crm/* ────► Nginx ──► Bun Master Bot (:19210)
  │                                 ├── crmAuthMiddleware (HMAC-SHA256)
  │                                 └── shared/routes/router.ts → 17 módulos de dominio
  │
  ├── /api/auth/* ───► Nginx ──► Bun (:19210) → master-bot/routes/auth.ts
  ├── /api/cli/*  ───► Nginx ──► Bun (:19210) → master-bot/routes/cli.ts
  ├── /api/internal/* ► Bun (:19210, solo loopback) → master-bot/routes/internal.ts
  │
  ├── /api/sse/* ────► Nginx (sin buffer) ──► Bun (:19210)
  │
  └── /ws/terminal/* ► Nginx (upgrade) ──► Bun (:19210) → master-bot/routes/websocket.ts

Estructura de Módulos (Fase 48)

API Server (master-bot/api-server.ts, 196 líneas) — dispatcher delgado:

• master-bot/routes/auth.ts (562) — OAuth, login, registro, 2FA, device code
• master-bot/routes/internal.ts (282) — chat/save, bridge-event, relay, descargas binarias
• master-bot/routes/cli.ts (293) — ARC CLI + integración MCP
• master-bot/routes/websocket.ts (303) — terminal, event-stream, local-bridge

Rutas CRM (shared/routes/router.ts, 512 líneas) — tabla de dispatch para 17 módulos de dominio:

• projects.ts (723), workers.ts (636), skills.ts (665), chat.ts (862)
• sage.ts (757), onboarding.ts (601), files.ts (381), wiki.ts (258)
• system.ts, pins.ts, learnings.ts, docs.ts, specs.ts, restart.ts, analytics.ts
• _utils.ts (343) — tipos compartidos, seguridad de rutas, helpers de auth

Flujo de Autenticación

Usuario ──► LoginOverlay (frontend)
         │
         ├── Email/contraseña → POST /api/auth/login
         └── OAuth → /api/auth/{google,github} → callback
         │
         ▼
    Auth exitosa → token HMAC-SHA256
         │
         ├── payload = { sub: userId, iat, exp: +24h }
         ├── signature = HMAC-SHA256(base64url(payload), CRM_SECRET)
         └── token = base64url(payload) + "." + signature
         │
         ▼
    localStorage('crm-token') → Todas las llamadas API: Authorization: Bearer <token>
         │
         ▼
    Token vence → 401 → se requiere login

Archivos Clave

Propiedades de Seguridad

• CRM_SECRET: 32 bytes hex aleatorio, cifrado en vault (AES-256-GCM)
• TTL del token: 24 horas, no renovable
• Firma: HMAC-SHA256, codificación base64url (sin padding)
• CORS: Echo de origen, limitado a headers Authorization + Content-Type
• Verificación de email requerida antes del login para cuentas nuevas
• La autenticación básica de nginx permanece como capa exterior de defensa en profundidad

Rutas de CRM API

Todas las rutas bajo /api/crm/ requieren Authorization: Bearer <token>.

GET /api/crm/projects

Lista todos los proyectos registrados con estado de salud en vivo. Incluye master como pseudo-proyecto (DEBT-6).

El master siempre se antepone como primera entrada en el array de respuesta.

GET /api/crm/projects/:name

Tarjeta de detalle completo del proyecto.

GET /api/crm/projects/:name/logs

Tail de logs JSONL estructurados.

Fuente: /var/log/citadel/<name>/<category>-YYYY-MM-DD.log

Lee los archivos de log más recientes primero, parsea JSONL, devuelve en orden cronológico.

GET /api/crm/projects/:name/files

Listado de directorio con protección contra path traversal.

Seguridad: resolve(base, requested) debe startsWith(resolve(base)). Violación → 403.

Entradas de respuesta: { name, type: "file"|"directory", size?, modified }, ordenadas con directorios primero.

GET /api/crm/projects/:name/skills

Skills instalados con atribución de fuente.

Deduplicado: la fuente de archivo tiene prioridad sobre el manifest.

POST /api/crm/projects/:name/restart (Fase 22.3)

Reiniciar un child bot via watchdog.

GET /api/crm/projects/:name/metrics (Fase 22.1)

Timeseries de métricas de calidad para gráficos sparkline.

Fuente: /var/log/citadel/<name>/quality-events.log → conteos de éxito/fallo por día.

WS /ws/terminal/:name (Fase 22.3)

Terminal WebSocket que transmite contenido del panel tmux.

Seguridad: Protección contra Path Traversal (Fase 22.3, DEBT-7)

Todos los endpoints validan nombres de proyectos antes de procesar:

const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
export function isValidProjectName(name: string): boolean {
  return name.length > 0 && name.length <= 64 && SAFE_NAME_RE.test(name);
}

Aplicado en 3 puntos de entrada: routeCrmRequest(), routeSseRequest(), manejador de upgrade WebSocket en bot.ts. Nombres inválidos → 403 Forbidden.

Integridad de Datos: Escrituras Atómicas (Fase 22.3, DEBT-2)

Las escrituras de registro en onboarding.ts usan un patrón atómico:

async function atomicWriteJson(filePath: string, data: unknown): Promise<void> {
  const tmp = `${filePath}.tmp.${process.pid}`;
  await Bun.write(tmp, JSON.stringify(data, null, 2));
  Bun.spawn(["mv", tmp, filePath]); // rename atómico POSIX
}

Archivos Clave

Proxy Nginx

Archivo: infra/nginx/citadel-crm.conf — reemplaza la configuración legacy citadel-os.

Tres upstreams:

Todas las locations reenvían X-Real-IP, X-Forwarded-For, X-Forwarded-Proto.

Rutas bloqueadas: /.* (dotfiles), /config/, /state/, /scripts/.

Nota: La prioridad de locations de Nginx asegura que /api/crm/ y /api/sse/ coincidan antes del catch-all /api/ (MCP legacy).

Integración en Master Bot

master-bot/bot.ts Bun.serve (:19210):

async fetch(req) {
  /api/master/health  →  público, sin auth
  /api/crm/*          →  preflight CORS → crmAuthMiddleware → routeCrmRequest()
  *                   →  404
}

El router despacha a funciones handler de shared/crm-routes.ts. Los headers CORS se inyectan en cada respuesta CRM (incluidos errores 401).

Resumen de Endpoints (Todas las Fases)

| 40.14 | Roadmap (contenido) | GET /api/mcp/roadmap/:project (+ campo content) | DONE |

Total: 46+ endpoints (REST + SSE + WebSocket + CLI/MCP)

NotebookLM Bridge (Fase 36.3)

Servicio Python FastAPI separado en :19213 (solo localhost). No forma parte de la CRM API de Bun.

El CRM de Bun dispara llamadas fire-and-forget al bridge en:

• handleUpdateIssue (cierre/apertura de issue) → /sync
• handleMcpWikiUpdate (guardado de wiki) → /sync
• handleCreateProject / handleOnboardingSetup → /notebooks/init
• executeAskNotebooklm → /query (timeout 15s, fallback a local)

Deuda Técnica

Ver docs/backlog/technical-debt.md para el registro completo. Elementos clave:

Mantenido por Rick (Orquestrador). Actualizado tras la finalización de cada fase.