Arquitetura do Backend CRM

Phase 22.0–48. Status: DEPLOYED (VPS ao vivo, 68+ endpoints, arquitetura modular). Última atualização: 2026-04-28 (Phase 48 — Decomposição de Arquitetura)

Visão Geral

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

Estrutura de Módulos (Phase 48)

API Server (master-bot/api-server.ts, 196 linhas) — dispatcher enxuto:

• 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 + integração MCP
• master-bot/routes/websocket.ts (303) — terminal, event-stream, local-bridge

Rotas CRM (shared/routes/router.ts, 512 linhas) — tabela de dispatch para 17 módulos de domínio:

• 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) — tipos compartilhados, segurança de path, helpers de auth

Fluxo de Autenticação

User ──► LoginOverlay (frontend)
         │
         ├── Email/password → POST /api/auth/login
         └── OAuth → /api/auth/{google,github} → callback
         │
         ▼
    Auth bem-sucedida → token HMAC-SHA256
         │
         ├── payload = { sub: userId, iat, exp: +24h }
         ├── signature = HMAC-SHA256(base64url(payload), CRM_SECRET)
         └── token = base64url(payload) + "." + signature
         │
         ▼
    localStorage('crm-token') → Todas as chamadas de API: Authorization: Bearer <token>
         │
         ▼
    Token expirado → 401 → login necessário

Arquivos-Chave

Propriedades de Segurança

• CRM_SECRET: hex aleatório de 32 bytes, criptografado no vault (AES-256-GCM)
• TTL do token: 24 horas, não renovável
• Assinatura: HMAC-SHA256, codificação base64url (sem padding)
• CORS: echo de Origin, limitado aos headers Authorization + Content-Type
• Verificação de email obrigatória antes do login para novas contas
• Autenticação básica do nginx permanece como camada de defesa em profundidade

Rotas da API CRM

Todas as rotas sob /api/crm/ exigem Authorization: Bearer <token>.

GET /api/crm/projects

Lista todos os projetos registrados com status de health ao vivo. Inclui o master como pseudo-projeto (DEBT-6).

O master é sempre adicionado como primeira entrada no array de resposta.

GET /api/crm/projects/:name

Card de detalhes completo do projeto.

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

Tail de logs estruturados JSONL.

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

Lê os arquivos de log mais recentes primeiro, faz parse do JSONL e retorna em ordem cronológica.

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

Listagem de diretório com proteção contra path traversal.

Segurança: resolve(base, requested) deve resultar em startsWith(resolve(base)). Violação → 403.

Entradas da resposta: { name, type: "file"|"directory", size?, modified }, ordenadas com diretórios primeiro.

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

Skills instaladas com atribuição de fonte.

Deduplicado: a fonte file tem prioridade sobre o manifest.

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

Reinicia um child bot via watchdog.

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

Série temporal de métricas de qualidade para gráficos sparkline.

Fonte: /var/log/citadel/<name>/quality-events.log → contagens de sucesso/falha por dia.

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

Terminal WebSocket transmitindo conteúdo do painel tmux.

Segurança: Proteção contra Path Traversal (Phase 22.3, DEBT-7)

Todos os endpoints validam nomes de projeto antes de processar:

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

Aplicado em 3 pontos de entrada: routeCrmRequest(), routeSseRequest(), handler de upgrade WebSocket em bot.ts. Nomes inválidos → 403 Forbidden.

Integridade de Dados: Escritas Atômicas (Phase 22.3, DEBT-2)

Escritas no registry em onboarding.ts usam padrão atômico:

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
}

Arquivos-Chave

Proxy Nginx

Arquivo: infra/nginx/citadel-crm.conf — substitui a config legada citadel-os.

Três upstreams:

Todos os locations encaminham X-Real-IP, X-Forwarded-For, X-Forwarded-Proto.

Paths bloqueados: /.* (dotfiles), /config/, /state/, /scripts/.

Nota: A prioridade de location do Nginx garante que /api/crm/ e /api/sse/ correspondam antes do catch-all /api/ (MCP legado).

Integração no 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
}

O roteador despacha para funções handler de shared/crm-routes.ts. Headers CORS são injetados em toda resposta CRM (incluindo erros 401).

Resumo de Endpoints (Todas as Phases)

| 40.14 | Roadmap (conteúdo) | GET /api/mcp/roadmap/:project (+ campo content) | DONE |

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

NotebookLM Bridge (Phase 36.3)

Serviço Python FastAPI separado em :19213 (somente localhost). Não faz parte da API CRM Bun.

O CRM Bun dispara chamadas fire-and-forget para o bridge ao:

• handleUpdateIssue (issue close/open) → /sync
• handleMcpWikiUpdate (salvar wiki) → /sync
• handleCreateProject / handleOnboardingSetup → /notebooks/init
• executeAskNotebooklm → /query (timeout 15s, fallback para local)

Dívida Técnica

Veja docs/backlog/technical-debt.md para o registry completo. Itens-chave:

Mantido por Rick (Orchestrator). Atualizado após a conclusão de cada phase.