Architecture du backend CRM

Phase 22.0–48. Statut : DÉPLOYÉ (VPS en ligne, 68+ endpoints, architecture modulaire). Dernière mise à jour : 2026-04-28 (Phase 48 — Décomposition architecture)

Vue d'ensemble

Navigateur (:18888)
  │
  ├── Fichiers statiques ──► Nginx ──► Docker frontend (React + Nginx)
  │
  ├── /api/crm/* ────► Nginx ──► Bun Master Bot (:19210)
  │                                 ├── crmAuthMiddleware (HMAC-SHA256)
  │                                 └── shared/routes/router.ts → 17 modules domaine
  │
  ├── /api/auth/* ───► Nginx ──► Bun (:19210) → master-bot/routes/auth.ts
  ├── /api/cli/*  ───► Nginx ──► Bun (:19210) → master-bot/routes/cli.ts
  ├── /api/internal/* ► Bun (:19210, loopback uniquement) → master-bot/routes/internal.ts
  │
  ├── /api/sse/* ────► Nginx (non bufférisé) ──► Bun (:19210)
  │
  └── /ws/terminal/* ► Nginx (upgrade) ──► Bun (:19210) → master-bot/routes/websocket.ts

Structure des modules (Phase 48)

Serveur API (master-bot/api-server.ts, 196 lignes) — dispatcher léger :

• master-bot/routes/auth.ts (562) — OAuth, login, register, 2FA, device code
• master-bot/routes/internal.ts (282) — chat/save, bridge-event, relay, téléchargements binaires
• master-bot/routes/cli.ts (293) — ARC CLI + intégration MCP
• master-bot/routes/websocket.ts (303) — terminal, event-stream, local-bridge

Routes CRM (shared/routes/router.ts, 512 lignes) — table de dispatch pour 17 modules domaine :

• 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) — types partagés, sécurité des chemins, helpers auth

Flux d'authentification

Utilisateur ──► LoginOverlay (frontend)
         │
         ├── Email/mot de passe → POST /api/auth/login
         └── OAuth → /api/auth/{google,github} → callback
         │
         ▼
    Auth réussie → token HMAC-SHA256
         │
         ├── payload = { sub: userId, iat, exp: +24h }
         ├── signature = HMAC-SHA256(base64url(payload), CRM_SECRET)
         └── token = base64url(payload) + "." + signature
         │
         ▼
    localStorage('crm-token') → Tous les appels API : Authorization: Bearer <token>
         │
         ▼
    Token expiré → 401 → reconnexion requise

Fichiers clés

Propriétés de sécurité

• CRM_SECRET : 32 octets hex aléatoire, chiffré par vault (AES-256-GCM)
• TTL du token : 24 heures, non renouvelable
• Signature : HMAC-SHA256, encodage base64url (sans padding)
• CORS : echo d'origine, limité aux headers Authorization + Content-Type
• Vérification email requise avant connexion pour les nouveaux comptes
• L'authentification basique nginx reste comme couche de défense en profondeur externe

Routes API CRM

Toutes les routes sous /api/crm/ requièrent Authorization: Bearer <token>.

GET /api/crm/projects

Liste tous les projets enregistrés avec statut de santé en direct. Inclut master comme pseudo-projet (DEBT-6).

Master est toujours ajouté en première entrée dans le tableau de réponse.

GET /api/crm/projects/:name

Fiche détaillée complète du projet.

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

Tail des logs JSONL structurés.

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

Lit les fichiers de log les plus récents en premier, parse le JSONL, retourne en ordre chronologique.

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

Listing de répertoire avec protection contre le path traversal.

Sécurité : resolve(base, requested) doit startsWith(resolve(base)). Violation → 403.

Entrées de réponse : { name, type: "file"|"directory", size?, modified }, triées répertoires en premier.

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

Skills installés avec attribution de source.

Dédupliqué : la source fichier a priorité sur le manifest.

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

Redémarre un child bot via le watchdog.

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

Séries temporelles de métriques qualité pour les graphiques sparkline.

Source : /var/log/citadel/<name>/quality-events.log → décomptes succès/échecs par jour.

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

Streaming de contenu de pane tmux via WebSocket.

Sécurité : Protection contre le path traversal (Phase 22.3, DEBT-7)

Tous les endpoints valident les noms de projet avant traitement :

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);
}

Appliqué à 3 points d'entrée : routeCrmRequest(), routeSseRequest(), handler d'upgrade WebSocket dans bot.ts. Noms invalides → 403 Forbidden.

Intégrité des données : Écritures atomiques (Phase 22.3, DEBT-2)

Les écritures de registry dans onboarding.ts utilisent le pattern atomique :

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]); // renommage atomique POSIX
}

Fichiers clés

Proxy Nginx

Fichier : infra/nginx/citadel-crm.conf — remplace la config legacy citadel-os.

Trois upstreams :

Tous les emplacements transmettent X-Real-IP, X-Forwarded-For, X-Forwarded-Proto.

Chemins bloqués : /.* (dotfiles), /config/, /state/, /scripts/.

Note : La priorité des locations nginx assure que /api/crm/ et /api/sse/ correspondent avant le catch-all /api/ (MCP legacy).

Intégration dans le Master Bot

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

async fetch(req) {
  /api/master/health  →  public, sans auth
  /api/crm/*          →  preflight CORS → crmAuthMiddleware → routeCrmRequest()
  *                   →  404
}

Le routeur dispatche vers les fonctions handler de shared/crm-routes.ts. Les headers CORS sont injectés sur chaque réponse CRM (y compris les erreurs 401).

Résumé des endpoints (toutes phases)

| 40.14 | Roadmap (contenu) | GET /api/mcp/roadmap/:project (+ champ content) | DONE |

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

NotebookLM Bridge (Phase 36.3)

Service Python FastAPI séparé sur :19213 (localhost uniquement). Pas partie de l'API CRM Bun.

Le CRM Bun déclenche des appels fire-and-forget vers le bridge lors de :

• handleUpdateIssue (fermeture/ouverture de ticket) → /sync
• handleMcpWikiUpdate (sauvegarde wiki) → /sync
• handleCreateProject / handleOnboardingSetup → /notebooks/init
• executeAskNotebooklm → /query (timeout 15s, fallback local)

Dette technique

Voir docs/backlog/technical-debt.md pour le registre complet. Éléments clés :

Maintenu par Rick (Orchestrateur). Mis à jour après chaque phase terminée.