Архітектура CRM Backend

Фаза 22.0–48. Статус: DEPLOYED (живе на VPS, 68+ ендпоінтів, модульна архітектура). Останнє оновлення: 2026-04-28 (Фаза 48 — Architecture Decomposition)

Огляд

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 modules
  │
  ├── /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

Структура модулів (Фаза 48)

API Server (master-bot/api-server.ts, 196 рядків) — тонкий диспетчер:

• master-bot/routes/auth.ts (562) — OAuth, login, register, 2FA, device code
• master-bot/routes/internal.ts (282) — chat/save, bridge-event, relay, завантаження бінарників
• master-bot/routes/cli.ts (293) — інтеграція з ARC CLI + MCP
• master-bot/routes/websocket.ts (303) — terminal, event-stream, local-bridge

CRM Routes (shared/routes/router.ts, 512 рядків) — таблиця диспетчеризації для 17 доменних модулів:

• 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) — спільні типи, безпека шляхів, auth-хелпери

Потік аутентифікації

User ──► LoginOverlay (frontend)
         │
         ├── Email/password → POST /api/auth/login
         └── OAuth → /api/auth/{google,github} → callback
         │
         ▼
    Successful auth → HMAC-SHA256 token
         │
         ├── payload = { sub: userId, iat, exp: +24h }
         ├── signature = HMAC-SHA256(base64url(payload), CRM_SECRET)
         └── token = base64url(payload) + "." + signature
         │
         ▼
    localStorage('crm-token') → All API calls: Authorization: Bearer <token>
         │
         ▼
    Token expires → 401 → login required

Ключові файли

Властивості безпеки

• CRM_SECRET: 32-байтний випадковий hex, зашифрований у vault (AES-256-GCM)
• Token TTL: 24 години, без поновлення
• Підпис: HMAC-SHA256, base64url encoding (без padding)
• CORS: Origin-echo, обмежено заголовками Authorization + Content-Type
• Верифікація email обов'язкова перед входом для нових акаунтів
• Базова авторизація nginx залишається як зовнішній шар defense-in-depth

Маршрути CRM API

Усі маршрути під /api/crm/ вимагають Authorization: Bearer <token>.

GET /api/crm/projects

Список усіх зареєстрованих проєктів з актуальним статусом здоров'я. Включає master як псевдо-проєкт (DEBT-6).

Master завжди ставиться першим записом у масиві відповіді.

GET /api/crm/projects/:name

Повна детальна картка проєкту.

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

Tail структурованих JSONL-логів.

Джерело: /var/log/citadel/<name>/<category>-YYYY-MM-DD.log

Спочатку читає найсвіжіші лог-файли, парсить JSONL, повертає у хронологічному порядку.

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

Список вмісту директорії із захистом від path traversal.

Безпека: resolve(base, requested) має startsWith(resolve(base)). Порушення → 403.

Записи відповіді: { name, type: "file"|"directory", size?, modified }, відсортовані директоріями вперед.

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

Встановлені скіли з атрибуцією джерела.

Дедуплікація: джерело file має пріоритет над manifest.

POST /api/crm/projects/:name/restart (Фаза 22.3)

Рестарт child-бота через watchdog.

GET /api/crm/projects/:name/metrics (Фаза 22.1)

Часовий ряд метрик якості для sparkline-графіків.

Джерело: /var/log/citadel/<name>/quality-events.log → лічильники success/failure по днях.

WS /ws/terminal/:name (Фаза 22.3)

WebSocket-термінал, що стрімить вміст tmux-панелі.

Безпека: захист від Path Traversal (Фаза 22.3, DEBT-7)

Усі ендпоінти валідують імена проєктів перед обробкою:

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

Застосовується в 3 точках входу: routeCrmRequest(), routeSseRequest(), WebSocket upgrade handler у bot.ts. Невалідні імена → 403 Forbidden.

Цілісність даних: атомарні записи (Фаза 22.3, DEBT-2)

Записи в реєстр у onboarding.ts використовують атомарний патерн:

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
}

Ключові файли

Nginx Proxy

Файл: infra/nginx/citadel-crm.conf — заміняє застарілий конфіг citadel-os.

Три upstreams:

Усі locations прокидають X-Real-IP, X-Forwarded-For, X-Forwarded-Proto.

Заблоковані шляхи: /.* (dotfiles), /config/, /state/, /scripts/.

Примітка: Пріоритет location'ів у nginx гарантує, що /api/crm/ і /api/sse/ мапляться раніше, ніж catch-all /api/ (legacy MCP).

Інтеграція в Master Bot

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

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

Роутер диспетчеризує виклики у функції-хендлери з shared/crm-routes.ts. CORS-заголовки інжектяться у кожну CRM-відповідь (включно з помилками 401).

Зведення ендпоінтів (усі фази)

| 40.14 | Roadmap (контент) | GET /api/mcp/roadmap/:project (+ поле content) | DONE |

Всього: 46+ ендпоінтів (REST + SSE + WebSocket + CLI/MCP)

NotebookLM Bridge (Фаза 36.3)

Окремий Python FastAPI-сервіс на :19213 (тільки localhost). Не є частиною Bun CRM API.

Bun CRM тригерить fire-and-forget виклики до Bridge у таких місцях:

• handleUpdateIssue (закриття/відкриття задачі) → /sync
• handleMcpWikiUpdate (збереження вікі) → /sync
• handleCreateProject / handleOnboardingSetup → /notebooks/init
• executeAskNotebooklm → /query (timeout 15с, fallback на локальний пошук)

Технічний борг

Повний реєстр дивись у docs/backlog/technical-debt.md. Ключові пункти:

Підтримується Rick (Orchestrator). Оновлюється після завершення кожної фази.