CRM Backend Architecture

Phase 22.0–48. Статус: DEPLOYED (VPS live, 68+ эндпоинтов, модульная архитектура). Последнее обновление: 2026-04-28 (Phase 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 доменных модулей
  │
  ├── /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) → master-bot/routes/internal.ts
  │
  ├── /api/sse/* ────► Nginx (unbuffered) ──► Bun (:19210)
  │
  └── /ws/terminal/* ► Nginx (upgrade) ──► Bun (:19210) → master-bot/routes/websocket.ts

Структура модулей (Phase 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) — терминал, 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) — общие типы, path safety, auth-хелперы

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

Пользователь ──► LoginOverlay (фронтенд)
                 │
                 ├── Email/password → POST /api/auth/login
                 └── OAuth → /api/auth/{google,github} → callback
                 │
                 ▼
    Успешная аутентификация → HMAC-SHA256 токен
                 │
                 ├── payload = { sub: userId, iat, exp: +24h }
                 ├── signature = HMAC-SHA256(base64url(payload), CRM_SECRET)
                 └── token = base64url(payload) + "." + signature
                 │
                 ▼
    localStorage('crm-token') → Все API-вызовы: Authorization: Bearer <token>
                 │
                 ▼
    Токен истёк → 401 → требуется вход

Ключевые файлы

Свойства безопасности

• CRM_SECRET: 32-байтный случайный hex, зашифрован через vault (AES-256-GCM)
• TTL токена: 24 часа, не обновляется
• Подпись: HMAC-SHA256, кодирование base64url (без padding)
• CORS: origin echo, ограничен заголовками Authorization + Content-Type
• Верификация email обязательна перед входом для новых аккаунтов
• nginx basic auth остаётся как внешний слой защиты в глубину

CRM API Routes

Все маршруты под /api/crm/ требуют Authorization: Bearer <token>.

GET /api/crm/projects

Список всех зарегистрированных проектов с live статусом health. Включает 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 (Phase 22.3)

Перезапуск дочернего бота через watchdog.

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

Временной ряд метрик качества для sparkline-графиков.

Источник: /var/log/citadel/<name>/quality-events.log → подсчёт успехов/ошибок по дням.

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

WebSocket-терминал, транслирующий содержимое tmux-панели.

Безопасность: защита от Path Traversal (Phase 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.

Целостность данных: атомарные записи (Phase 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 — заменяет legacy-конфиг citadel-os.

Три upstream-а:

Все location'ы передают 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  →  публичный, без 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 (Phase 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 (таймаут 15с, fallback на локальный)

Технический долг

Полный реестр в docs/backlog/technical-debt.md. Ключевые позиции:

Поддерживается Rick (Orchestrator). Обновляется после завершения каждой фазы.