Architektura backendu CRM

Phase 22.0–48. Status: DEPLOYED (VPS aktywny, 68+ endpointów, architektura modułowa). Ostatnia aktualizacja: 2026-04-28 (Phase 48 — Dekompozycja Architektury)

Ogólny opis

Przeglądarka (:18888)
  │
  ├── Pliki statyczne ──► Nginx ──► Docker frontend (React + Nginx)
  │
  ├── /api/crm/* ────► Nginx ──► Bun Master Bot (:19210)
  │                                 ├── crmAuthMiddleware (HMAC-SHA256)
  │                                 └── shared/routes/router.ts → 17 modułów domenowych
  │
  ├── /api/auth/* ───► Nginx ──► Bun (:19210) → master-bot/routes/auth.ts
  ├── /api/cli/*  ───► Nginx ──► Bun (:19210) → master-bot/routes/cli.ts
  ├── /api/internal/* ► Bun (:19210, tylko loopback) → master-bot/routes/internal.ts
  │
  ├── /api/sse/* ────► Nginx (bez buforowania) ──► Bun (:19210)
  │
  └── /ws/terminal/* ► Nginx (upgrade) ──► Bun (:19210) → master-bot/routes/websocket.ts

Struktura modułów (Phase 48)

Serwer API (master-bot/api-server.ts, 196 linii) — cienki dispatcher:

• master-bot/routes/auth.ts (562) — OAuth, logowanie, rejestracja, 2FA, kod urządzenia
• master-bot/routes/internal.ts (282) — chat/save, bridge-event, relay, pobieranie binarek
• master-bot/routes/cli.ts (293) — integracja ARC CLI + MCP
• master-bot/routes/websocket.ts (303) — terminal, strumień zdarzeń, local-bridge

Trasy CRM (shared/routes/router.ts, 512 linii) — tabela dispatchingu do 17 modułów domenowych:

• 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) — wspólne typy, bezpieczeństwo ścieżek, helpery auth

Przepływ uwierzytelniania

Użytkownik ──► LoginOverlay (frontend)
         │
         ├── Email/hasło → POST /api/auth/login
         └── OAuth → /api/auth/{google,github} → callback
         │
         ▼
    Pomyślne uwierzytelnienie → token HMAC-SHA256
         │
         ├── payload = { sub: userId, iat, exp: +24h }
         ├── signature = HMAC-SHA256(base64url(payload), CRM_SECRET)
         └── token = base64url(payload) + "." + signature
         │
         ▼
    localStorage('crm-token') → Wszystkie wywołania API: Authorization: Bearer <token>
         │
         ▼
    Token wygasł → 401 → wymagane zalogowanie

Kluczowe pliki

Właściwości bezpieczeństwa

• CRM_SECRET: 32-bajtowy losowy hex, zaszyfrowany w vault (AES-256-GCM)
• TTL tokenu: 24 godziny, nieodnawialny
• Sygnatura: HMAC-SHA256, kodowanie base64url (bez paddingu)
• CORS: echo origin, ograniczone do nagłówków Authorization + Content-Type
• Wymagana weryfikacja email przed logowaniem dla nowych kont
• Basic auth nginx pozostaje jako zewnętrzna warstwa obrony wgłębnej

Trasy CRM API

Wszystkie trasy pod /api/crm/ wymagają Authorization: Bearer <token>.

GET /api/crm/projects

Lista wszystkich zarejestrowanych projektów ze statusem zdrowia na żywo. Zawiera mastera jako pseudo-projekt (DEBT-6).

Master jest zawsze dołączany jako pierwszy element tablicy odpowiedzi.

GET /api/crm/projects/:name

Pełna karta szczegółów projektu.

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

Ogon logów strukturalnych JSONL.

Źródło: /var/log/citadel/<nazwa>/<kategoria>-YYYY-MM-DD.log

Odczytuje najnowsze pliki logów jako pierwsze, parsuje JSONL, zwraca w kolejności chronologicznej.

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

Listing katalogu z ochroną przed path traversal.

Bezpieczeństwo: resolve(base, requested) musi mieć startsWith(resolve(base)). Naruszenie → 403.

Elementy odpowiedzi: { name, type: "file"|"directory", size?, modified }, posortowane — katalogi pierwsze.

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

Zainstalowane skille z atrybucją źródła.

Deduplikowane: źródło plikowe ma priorytet nad manifestem.

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

Restartuj child bota przez watchdoga.

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

Szereg czasowy metryk jakości dla wykresów sparkline.

Źródło: /var/log/citadel/<nazwa>/quality-events.log → liczby sukces/porażka per dzień.

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

Terminal WebSocket streamujący zawartość panelu tmux.

Bezpieczeństwo: ochrona przed Path Traversal (Phase 22.3, DEBT-7)

Wszystkie endpointy walidują nazwy projektów przed przetworzeniem:

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

Stosowane w 3 punktach wejścia: routeCrmRequest(), routeSseRequest(), handler upgrade WebSocket w bot.ts. Nieprawidłowe nazwy → 403 Forbidden.

Integralność danych: Atomiczne zapisy (Phase 22.3, DEBT-2)

Zapisy do rejestru w onboarding.ts stosują wzorzec atomiczny:

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

Kluczowe pliki

Proxy Nginx

Plik: infra/nginx/citadel-crm.conf — zastępuje starszy config citadel-os.

Trzy upstream:

Wszystkie lokalizacje przekazują X-Real-IP, X-Forwarded-For, X-Forwarded-Proto.

Zablokowane ścieżki: /.* (dotfiles), /config/, /state/, /scripts/.

Uwaga: Priorytet lokalizacji nginx zapewnia, że /api/crm/ i /api/sse/ są dopasowane przed catch-all /api/ (legacy MCP).

Integracja w Master Bocie

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

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

Router dispatchuje do funkcji handlerów z shared/crm-routes.ts. Nagłówki CORS są wstrzykiwane do każdej odpowiedzi CRM (włącznie z błędami 401).

Podsumowanie endpointów (wszystkie Phase)

| 40.14 | Roadmapa (treść) | GET /api/mcp/roadmap/:project (+ pole content) | DONE |

Łącznie: 46+ endpointów (REST + SSE + WebSocket + CLI/MCP)

NotebookLM Bridge (Phase 36.3)

Osobna usługa Python FastAPI na :19213 (tylko localhost). Nie jest częścią Bun CRM API.

Bun CRM wywołuje fire-and-forget do bridge przy:

• handleUpdateIssue (zamknięcie/otwarcie zgłoszenia) → /sync
• handleMcpWikiUpdate (zapis wiki) → /sync
• handleCreateProject / handleOnboardingSetup → /notebooks/init
• executeAskNotebooklm → /query (timeout 15s, fallback do lokalnego)

Dług techniczny

Pełny rejestr: docs/backlog/technical-debt.md. Kluczowe pozycje:

Prowadzone przez Ricka (Orkiestratora). Aktualizowane po ukończeniu każdej phase.