CRM-Backend-Architektur

Phase 22.0–48. Status: DEPLOYED (VPS live, 68+ Endpunkte, modulare Architektur). Zuletzt aktualisiert: 2026-04-28 (Phase 48 — Architektur-Dekomposition)

Überblick

Browser (:18888)
  │
  ├── Static files ──► Nginx ──► Docker frontend (React + Nginx)
  │
  ├── /api/crm/* ────► Nginx ──► Bun Master Bot (:19210)
  │                                 ├── crmAuthMiddleware (HMAC-SHA256)
  │                                 └── shared/routes/router.ts → 17 Domain-Module
  │
  ├── /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 only) → master-bot/routes/internal.ts
  │
  ├── /api/sse/* ────► Nginx (unbuffered) ──► Bun (:19210)
  │
  └── /ws/terminal/* ► Nginx (upgrade) ──► Bun (:19210) → master-bot/routes/websocket.ts

Modulstruktur (Phase 48)

API-Server (master-bot/api-server.ts, 196 Zeilen) — schlanker Dispatcher:

• master-bot/routes/auth.ts (562) — OAuth, Login, Register, 2FA, Device Code
• master-bot/routes/internal.ts (282) — chat/save, bridge-event, relay, Binary Downloads
• master-bot/routes/cli.ts (293) — ARC CLI + MCP-Integration
• master-bot/routes/websocket.ts (303) — Terminal, Event-Stream, Local Bridge

CRM-Routen (shared/routes/router.ts, 512 Zeilen) — Dispatch-Tabelle für 17 Domain-Module:

• 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) — gemeinsame Typen, Pfadsicherheit, Auth-Helfer

Authentifizierungsfluss

User ──► LoginOverlay (frontend)
         │
         ├── E-Mail/Passwort → POST /api/auth/login
         └── OAuth → /api/auth/{google,github} → callback
         │
         ▼
    Erfolgreiche Auth → HMAC-SHA256-Token
         │
         ├── payload = { sub: userId, iat, exp: +24h }
         ├── signature = HMAC-SHA256(base64url(payload), CRM_SECRET)
         └── token = base64url(payload) + "." + signature
         │
         ▼
    localStorage('crm-token') → Alle API-Aufrufe: Authorization: Bearer <token>
         │
         ▼
    Token läuft ab → 401 → Login erforderlich

Wichtige Dateien

Sicherheitseigenschaften

• CRM_SECRET: 32-Byte zufälliges Hex, vault-verschlüsselt (AES-256-GCM)
• Token-TTL: 24 Stunden, nicht erneuerbar
• Signatur: HMAC-SHA256, Base64url-Encoding (ohne Padding)
• CORS: Origin-Echo, beschränkt auf Authorization + Content-Type-Header
• E-Mail-Verifizierung für neue Accounts vor dem Login erforderlich
• Nginx Basic Auth bleibt als äußere Defense-in-Depth-Schicht

CRM API-Routen

Alle Routen unter /api/crm/ erfordern Authorization: Bearer <token>.

GET /api/crm/projects

Listet alle registrierten Projekte mit Live-Health-Status auf. Master ist als Pseudo-Projekt enthalten (DEBT-6).

Master ist immer als erster Eintrag im Response-Array vorangestellt.

GET /api/crm/projects/:name

Vollständige Projektdetailkarte.

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

JSONL-strukturierte Logs tailing.

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

Liest die neuesten Log-Dateien zuerst, parst JSONL, gibt in chronologischer Reihenfolge zurück.

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

Verzeichnis-Listing mit Path-Traversal-Schutz.

Sicherheit: resolve(base, requested) muss startsWith(resolve(base)). Verletzung → 403.

Response-Einträge: { name, type: "file"|"directory", size?, modified }, sortiert Verzeichnisse zuerst.

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

Installierte Skills mit Quellzuordnung.

Dedupliziert: Datei-Quelle hat Vorrang vor Manifest.

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

Startet einen Child Bot über den Watchdog neu.

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

Qualitätsmetriken-Zeitreihen für Sparkline-Diagramme.

Quelle: /var/log/citadel/<name>/quality-events.log → tägliche Erfolgs-/Fehleranzahlen.

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

WebSocket-Terminal, streamt tmux-Pane-Inhalt.

Sicherheit: Path-Traversal-Schutz (Phase 22.3, DEBT-7)

Alle Endpunkte validieren Projektnamen vor der Verarbeitung:

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

Angewendet an 3 Einstiegspunkten: routeCrmRequest(), routeSseRequest(), WebSocket-Upgrade-Handler in bot.ts. Ungültige Namen → 403 Forbidden.

Datenintegrität: Atomare Schreibvorgänge (Phase 22.3, DEBT-2)

Registry-Schreibvorgänge in onboarding.ts nutzen atomares Muster:

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]); // POSIX atomic rename
}

Wichtige Dateien

Nginx-Proxy

Datei: infra/nginx/citadel-crm.conf — ersetzt Legacy-Konfiguration citadel-os.

Drei Upstreams:

Alle Locations leiten X-Real-IP, X-Forwarded-For, X-Forwarded-Proto weiter.

Blockierte Pfade: /.* (Dotfiles), /config/, /state/, /scripts/.

Hinweis: Die Nginx-Location-Priorität stellt sicher, dass /api/crm/ und /api/sse/ vor dem Catch-All /api/ (Legacy MCP) abgeglichen werden.

Integration im Master Bot

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

async fetch(req) {
  /api/master/health  →  öffentlich, keine Auth
  /api/crm/*          →  CORS Preflight → crmAuthMiddleware → routeCrmRequest()
  *                   →  404
}

Der Router dispatcht zu Handler-Funktionen aus shared/crm-routes.ts. CORS-Header werden bei jeder CRM-Antwort eingefügt (einschließlich 401-Fehler).

Endpunkt-Übersicht (Alle Phasen)

Gesamt: 46+ Endpunkte (REST + SSE + WebSocket + CLI/MCP)

NotebookLM Bridge (Phase 36.3)

Separater Python FastAPI-Service unter :19213 (nur localhost). Kein Bestandteil der Bun CRM API.

Der Bun CRM löst Fire-and-forget-Aufrufe an die Bridge aus bei:

• handleUpdateIssue (Issue schließen/öffnen) → /sync
• handleMcpWikiUpdate (Wiki speichern) → /sync
• handleCreateProject / handleOnboardingSetup → /notebooks/init
• executeAskNotebooklm → /query (15s Timeout, Fallback auf lokal)

Technische Schulden

Vollständige Registry unter docs/backlog/technical-debt.md. Wichtige Einträge:

Gepflegt von Rick (Orchestrator). Nach jeder Phasen-Fertigstellung aktualisiert.