Arc OS — Arquitetura

Visão Geral

O Arc OS substitui 11.321 linhas de infraestrutura customizada em Python/JS pelas ferramentas nativas do Claude Code. O agente de IA É o backend.

Arquitetura do Sistema (Phase 52.1)

graph TB
    User[👤 User Browser :18888]
    TG[📱 Telegram]
    Local[💻 Local IDE]

    subgraph "Edge"
      Nginx[Nginx :18888<br/>basic-auth + deny-list]
      FE[React CRM + Phaser<br/>frontend container]
    end

    subgraph "Master Bot Bun :19210 — 127.0.0.1 only"
      ApiSrv[api-server.ts<br/>196 LOC]
      Routes[master-bot/routes/<br/>auth · internal · cli · websocket]
      Router[shared/routes/router.ts<br/>373 LOC dispatcher]

      subgraph "19 Domain Modules — Phase 48"
        D1[auth · projects · workers]
        D2[skills · sage · chat]
        D3[wiki · files · onboarding]
        D4[billing · invites · analytics]
        D5[+ 7 more]
      end
    end

    subgraph "Federated Bots"
      Master[Master Bot<br/>orchestrator]
      Child[Child Bots<br/>per-project]
      Claude[claude -p CLI]
    end

    subgraph "Intelligence Layer"
      Eval[Binary Evals]
      Ctx[Context Router top-5]
      Learn[Learnings inject]
      Karp[Karpathy nightly loop]
    end

    NB[NotebookLM Bridge<br/>FastAPI :19213 localhost]
    Google[(Google NotebookLM)]

    DB[(SQLite WAL<br/>30+ tables<br/>migrations 001-035)]
    Vault[(AES-256-GCM Vault<br/>config/vault.json)]
    Bridge[Local Bridge CLI<br/>WebSocket relay]

    User -->|HTTPS| Nginx
    Nginx --> FE
    Nginx -->|/api/crm/*| ApiSrv
    Nginx -->|/api/sse/*| ApiSrv
    Nginx -->|/ws/terminal| ApiSrv
    ApiSrv --> Routes
    Routes --> Router
    Router --> D1 & D2 & D3 & D4 & D5

    TG --> Master
    TG --> Child
    Master -.spawns via tmux.-> Child
    Child --> Claude
    Claude --> Eval & Ctx & Learn

    Router -.queries.-> NB
    Child -.auto-sync.-> NB
    NB --> Google

    Router --> DB
    Router --> Vault
    Child --> Vault

    Local --> Bridge
    Bridge -.ws relay.-> ApiSrv
    Karp -.nightly.-> DB

Principais características:

• 70+ endpoints REST (Phase 52.1) distribuídos em 19 módulos de domínio em shared/routes/
• Bind em 127.0.0.1 — o Bun nunca é exposto externamente; o nginx faz proxy pelo loopback
• Gate de multi-tenancy — canAccessProject(registry, chatId, project) em cada rota protegida
• Zero-Knowledge E2EE (Phase 45) — WebCrypto PBKDF2 + chave mestre AES-256-GCM em sessionStorage

LEGADO (v1):
User → Telegram Bot (Python 111KB) → HybridEngine → command_queue.json
       → bridge_processor.sh → Claude → command_responses.json
       → FastAPI EventBus → WebSocket → Phaser UI

V2 (NATIVE-FIRST):
User → Official Telegram Channel → Claude Code Session
       ↓                                ↓
       reply/edit_message          Agent Teams (TaskCreate/SendMessage)
                                        ↓
                                   Write state → JSON files
                                        ↓
                                   Arc OS Bridge MCP → HTTP/SSE → Phaser UI

Redução: 11.321 linhas → ~3.700 linhas (67% menos código)

Componentes

1. Claude Code Session (O Cérebro)

A sessão Claude Code substitui:

• Backend FastAPI (15 serviços)
• HybridEngine (39KB)
• bridge_processor.sh (19,6KB)
• response_watcher.py (14KB)
• event_bus.py
• supply_chain.py (13KB)

Toda a orquestração acontece nativamente via Agent Teams.

2. Arc OS Bridge MCP Server (Adaptador de Estado)

Servidor MCP em TypeScript (Bun) que faz ponte entre o estado do Claude Code e o frontend.

MCP Tools (lado Claude Code):

HTTP API (lado Frontend):

3. Phaser Frontend (Camada Visual)

Phaser 3.80 + Vite. Conecta-se ao servidor MCP via HTTP/SSE.

Diferença-chave em relação à v1: sem WebSocket — substituído por SSE do servidor MCP. Sem UI de entrada de comandos — o Telegram é a interface de comando.

4. Interface de Comando Telegram (Camada Tática de UI — Phase 21.0)

O Telegram é o painel de controle principal de todo o Arc OS. Duas camadas de bots:

Master Bot (@citadel_ceo_bot):

• Teclado de resposta persistente: Мої Проєкти / Новий Проєкт / Watchdog / Web UI
• Cards inline por child: Reiniciar, Excluir, Ver MANIFEST, Skills Ativas
• Botões de URL do CRM: Projeto, Tarefas, Arquivos, Configurações (links stub para o frontend)
• Roteador de callback query para todas as ações inline
• Fluxo de confirmação de exclusão: teclado inline → SIM/CANCELAR → edita a mensagem
• Registro de setMyCommands na inicialização

Child Bots (@cv2_pt_bot, etc.):

• Cada resposta do Claude recebe botões inline no último chunk:
  • STOP (SIGKILL) / PAUSE (SIGSTOP) / RESUME (SIGCONT) — controle de subprocesso
  • BTW — enfileira contexto adicional para a próxima chamada Claude
  • Fix It — gera automaticamente um prompt de correção a partir da última resposta do bot
• Botão de label de skills mostrando as competências do projeto carregado
• Roteador de callback query para todas as ações de sinal/contexto

Integração CRM (desenvolvimento):

CRM_BASE_URL = http://62.171.128.248:18888  (dev)
               https://crm.citadel.v2       (future prod)

Todos os layouts de teclado definidos em shared/ui_templates.ts — fonte única para mudanças de UI.

Protocolo de dados de callback: action:target (máx. 64 bytes)

• Master: restart:pt, delete:pt, confirm_del:pt, cancel_del:pt, manifest:pt, skills:pt
• Child: stop, pause, resume, btw, fixit, skills_info

Fluxo de Dados

1. Usuário envia "/status" via Telegram
2. Sessão Claude Code recebe via Telegram Channel
3. Rick lê state/office-state.json + TaskList()
4. Rick responde via Telegram (edit_message para atualizações ao vivo)
5. Rick chama update_agent_state() via MCP
6. Servidor MCP escreve em state/office-state.json
7. File watcher detecta a mudança → envia evento SSE
8. Frontend recebe SSE → atualiza sprites dos agentes

Gerenciamento de Estado

Todo o estado reside em arquivos JSON sob state/:

Tarefas do Agent Teams gerenciadas nativamente pelo Claude Code em ~/.claude/tasks/citadel-v2/.

Agentes (6)

Supply Chain

CEO → Rick (decompõe) → Agent Team (executa)
                       → Cross-Review (Summer valida)
                       → Rick (sintetiza)
                       → CEO (resultado final)

Garantida por meio de:

• Blueprints: Configurações de departamento que definem papéis dos agentes
• Skills: Expertise carregada dinamicamente
• Protocolo HANDOFF: Passagem de contexto estruturada entre agentes

Stack Tecnológico

Lifecycle Hooks

Hooks do Claude Code (~/.claude/settings.json) sincronizam automaticamente o estado dos agentes:

SubagentStop event → subagent-stop.sh → office-state.json (agent=idle)
                                              ↓
                                   StateManager (fs.watch) → SSE → Phaser UI

Stop event → session-end.sh → latest_wrapup.txt + all agents=idle

Scripts: scripts/citadel-hooks/subagent-stop.sh, scripts/citadel-hooks/session-end.sh

Campos-chave: subagentName (SubagentStop), stopReason (Stop), cwd (ambos).

NotebookLM Bridge (Phase 36.3)

Busca semântica real via Google NotebookLM, substituindo uploads manuais de arquivos:

Cloud PM Chat → Bun Master Bot (:19210)
                    │
         executeAskNotebooklm()
                    │
         HTTP → FastAPI Bridge (:19213, localhost only)
                    │
              notebooklm-py async client
                    │
              Google NotebookLM (free semantic search)

         Fallback: local keyword search (existing code)

• Um notebook por projeto — mapeamento armazenado em notebook_mapping.json
• Auto-sync — issue close/open + atualização de wiki → POST fire-and-forget para /sync
• SyncWorker — asyncio.Queue(200), delay de 2s, backoff exponencial (3 tentativas)
• Cache de queries — LRU, TTL 5min, máx. 100 entradas
• systemd — citadel-notebooklm-bridge.service, auto-restart, somente localhost
• Auth — Cookies Google em /root/.notebooklm/storage_state.json

Exportação baseada em arquivos legada (/citadel-wrapup, /citadel-recall) ainda funcional como fallback.

Política de Roteamento de Dados e Tarefas

Sistema de três camadas. Cada camada tem um propósito estrito. Misturar camadas = caos.

┌─────────────────────────────────────────────────────────────────┐
│  TIER 1: Working Memory (Quente)                                │
│  office-state.json + state/tasks/                               │
│  CLI: /citadel-task, /citadel-status                            │
│                                                                 │
│  Tarefas diárias dos agentes. Vive durante a sessão. Morre ao  │
│  final. Tarefa concluída → /citadel-wrapup → Tier 3.           │
├─────────────────────────────────────────────────────────────────┤
│  TIER 2: Backlog Estratégico (Morno)                            │
│  GitHub Issues (repos Claude-CEO + citadel-v2)                  │
│                                                                 │
│  Apenas épicos: Phase 20, Phase 21, bugs globais.               │
│  Sem tarefas diárias. Sem issues "corrigir typo".               │
│  Um issue = uma iniciativa multissemanal ou defeito crítico.    │
├─────────────────────────────────────────────────────────────────┤
│  TIER 3: Memória de Longo Prazo (Frio)                          │
│  docs/library-export/ → Google Drive → NotebookLM              │
│  CLI: /citadel-wrapup, /citadel-recall                          │
│                                                                 │
│  Enciclopédia. Resultados de sessão, decisões arquiteturais,    │
│  RAG. Arquivo somente-leitura. Sem tarefas ativas.              │
└─────────────────────────────────────────────────────────────────┘

Regras de Roteamento

Ciclo de Vida

CEO dá tarefa → Tier 1 (agente trabalha nela)
                     ↓ concluída
                 /citadel-wrapup → Tier 3 (arquivada)
                     ↓ se estratégica
                 gh issue create → Tier 2 (rastreada a longo prazo)

Anti-padrões (NÃO FAÇA)

• NÃO crie GitHub Issues para tarefas diárias ("fix typo", "update config")
• NÃO armazene status de tarefas ativas em arquivos library-export/
• NÃO use office-state.json para decisões de longo prazo ou notas de arquitetura
• NÃO duplique: uma tarefa vive em exatamente uma camada por vez

Infraestrutura (Phase 20.5)

Logging Estruturado (shared/logger.ts)

Formato JSONL, saída dupla (arquivo + console), divisão diária de arquivos por categoria.

/var/log/citadel/
├── master/
│   ├── system-2026-04-02.log   ← ciclo de vida, config, health
│   ├── dialog-2026-04-02.log   ← (não usado pelo master)
│   └── error-2026-04-02.log    ← erros (também em system)
├── citadel-v2/
│   ├── system-2026-04-02.log
│   ├── dialog-2026-04-02.log   ← mensagens usuário ↔ Claude
│   └── error-2026-04-02.log
└── <project-name>/             ← por projeto integrado

Rotação de logs: config/logrotate-citadel.conf → /etc/logrotate.d/citadel (diária, retenção de 7 dias).

Vault de Secrets (shared/vault.ts)

Armazenamento criptografado com AES-256-GCM para tokens de bot.

Key source: SECRET_ENCRYPTION_KEY env → config/vault-key file → auto-generated
Storage:    config/vault.json (atomic writes: tmp + mv)
Cache:      In-memory after initVault() — no disk I/O per getSecret()
Fallback:   getSecret("FOO") → vault cache → process.env.FOO
Naming:     child:<project-name>:token

O próprio token do master permanece no .env (o vault carrega dentro do processo master).

Watchdog Auto-Recuperável (master-bot/watchdog.ts)

Monitor em segundo plano para child bots. Roda dentro do processo do master bot.

A cada 30s: HTTP health check → /api/child/health (timeout 5s)
  Saudável → zera falhas
  Não saudável → incrementa falhas
  3+ falhas + backoff expirado → auto-restart (mata tmux → inicia novo com token do vault)
  Backoff: 30s → 1m → 5m → 15m → 60m (cap)
  10 falhas consecutivas → desativa permanentemente + notifica o CEO

Estado persistido em config/watchdog-state.json (sobrevive ao restart do master). Notificações ao CEO via Telegram: primeiro restart, falha de restart, desativação permanente. Comando /watchdog: status em tempo real de todos os children.

Protocolo de Remoção de Projeto (Phase 20.4 + 21.0)

/remove_project <name> → tripla confirmação → limpeza completa:

1. Mata sessão tmux: child-<name>
2. Kill em massa de fantasmas: ps aux | grep child-<name> → kill -9 todos os PIDs
3. Verificação de porta: ss -tlnp | grep :<port> → libera à força se ocupada
4. Remove de bot_registry.json + recarga em memória
5. Exclui /opt/repos/<name>/ (segurança: path deve estar sob /opt/repos/, mín. 3 segmentos)
6. Exclui /var/log/citadel/<name>/

Nomes protegidos: citadel-v2, citadel, claude-ceo, claude-CEO — remoção bloqueada.

Problema de processo fantasma (lição aprendida): após o kill do tmux, processos órfãos bun podem segurar portas. Kill em massa + verificação de porta evita "bots fantasma" que respondem a health checks mas ignoram o Telegram.

Gerenciamento de Skills (Phase 21.0)

Os child bots carregam skills de duas fontes na inicialização, com deduplicação via Set:

Fonte 1: MANIFEST.md (JSON)
  → manifest.skills[]          (correspondidos durante o onboarding)
  → manifest.library_skills[]  (arquivos .md da library correspondidos)

Fonte 2: diretório skills/
  → arquivos *.md → nome do arquivo sem extensão

Merge: Set<string>(manifest.skills + manifest.library_skills + skills/*.md)

Exemplo (projeto PT): 5 do manifest + 7 de skills/ = 12 skills únicas.

Skills aparecem como:

• Label de botão inline nas respostas do child: 🏷️ odoo-expert, docker-ops, ...
• Callback skills_info: toast com a lista completa
• Comando /skills no master: lista o conteúdo do diretório skills

Segurança (Phase 42 — Auditoria Sentinel 2026-04-23, 4 passagens, 13 patches)

Visão geral completa: SECURITY.md. Relatório de auditoria: security/audit-2026-04-23.md.

Secrets e armazenamento:

• Nenhuma credencial no repositório; arquivos de estado não contêm secrets
• Tokens de bot no vault criptografado (config/vault.json, AES-256-GCM). getSecret() com fallback para process.env
• Chave de criptografia gerada automaticamente em config/vault-key (chmod 600). vault.json, vault-key, watchdog-state.json, data/citadel.db* no gitignore

Autenticação:

• JWT HMAC-SHA256, TTL 24h, comparação de assinatura com crypto.timingSafeEqual
• OAuth Google + GitHub com CSRF state (10min, uso único)
• Email/senha com verificação obrigatória antes do login (TTL 24h), reset de senha (TTL 30min), entregue via Resend
• Extração de token — extractChatId() lê o header Bearer OU a query ?token= (para browser EventSource), alinhado ao crmAuthMiddleware

Multi-tenancy (Phase 42):

• Gate canAccessProject(registry, chatId, project) em todas as rotas protegidas
• CEO (ceo_chat_id) e user.role === 'admin' no DB enxergam tudo; os demais são filtrados por correspondência de owner_id (DB SSOT)
• Rotas SSE, terminal WebSocket, /api/cli/*, /api/mcp/*, /api/crm/projects/:name/* todas com gate
• /ws/terminal/:name?mode=interactive exige CEO ou admin

Perímetro de rede:

• Bun faz bind somente em 127.0.0.1:19210 — nginx faz proxy pelo loopback
• /api/internal/* rejeita qualquer requisição com headers de proxy (X-Forwarded-For, X-Real-IP, Forwarded) como canário de misconfig do nginx
• Allowlist de SSRF em handleScoutAnalyze — HTTPS + correspondência exata de hostname + redirect:"manual" (bloqueia bypass por cadeia de redirecionamentos)
• UFW bloqueia :19210, :19213, :19200 externamente

Segurança de entrada / path:

• isValidProjectName() regex em todos os pontos de entrada (incluindo endpoints internos)
• safePath() em todos os caminhos de arquivo controlados pelo usuário — handleSaveSkill encontrado e corrigido na Phase 42.6
• Lista de negação do Nginx: /.*, /(state|scripts|config|data|knowledge-base|issues|skills|blueprints|mcp-server)/
• Whitelist de CORS (CRM_ALLOWED_ORIGINS), headers também em erros
• Escritas atômicas para mutações no registry (tmp.${pid} + mv)
• Descriptografia do token do vault para inicialização do child: use bun -e com node:crypto (NÃO Python)

Cobertura de regressão: scripts/vps-sync.sh executa 7+ smoke tests pós-deploy a cada deploy (bind no loopback, path traversal, validação chat/save, canário de proxy, SSE ?token=, validação fail-closed, bloqueio de SSRF se CEO_TOKEN definido).

Módulos do Master Bot (Phase 25 — Resolução DEBT-1)

O master bot é organizado em módulos focados:

master-bot/
├── bot.ts               ← Bootstrap: vault, registry, context, conecta tudo (106 linhas)
├── context.ts           ← Tipo MasterContext + interfaces de domínio
├── api-server.ts        ← Bun.serve() — HTTP, WebSocket, SSE, rotas CRM
├── tg-api.ts            ← Wrapper da Telegram Bot API (sendMessage, getUpdates, etc.)
├── child-state.ts       ← Lê estado do child bot, health, heartbeat, tmux, bridge
├── telegram-commands.ts ← Todos os handlers /command, handler de callback query, roteador de mensagens
├── telegram.ts          ← Loop de polling simplificado + re-exports para compat. com versões anteriores
├── watchdog.ts          ← Monitor auto-recuperável de child bot
└── onboarding.ts        ← Wizard interativo de criação de projeto

bot.ts importa apenas de telegram.ts e api-server.ts. Todos os outros módulos são detalhes de implementação interna.

Bridge CLI (Phase 25 — Local Gateway)

bridge/
├── bin/citadel-bridge.ts    ← Entrada CLI (commander.js): connect, pull, push, status, disconnect
├── src/
│   ├── auth.ts              ← Validação JWT contra CRM
│   ├── config.ts            ← Persistência em ~/.citadel/bridge.json
│   ├── inject.ts            ← Marcadores <!-- CITADEL:START/END --> no CLAUDE.md
│   ├── sync.ts              ← Pull de skills-bundle + learnings, push de learnings locais
│   └── heartbeat.ts         ← Repórter de atividade de sessão
├── package.json
└── tsconfig.json

Endpoints da API CRM (50+ no total)

CRM Principal (Phase 22)

Dashboard e Wiki (Phase 32)

Multi-Tenant (Phase 33)

MCP e CLI (Phase 34)

Terminal ao Vivo (Phase 35)

Cloud PM e Conhecimento (Phase 36)

Auth e OAuth (Phase 37)

Notas Fixadas (Phase 41.8)

Backend: migration 009 (tabela pinned_notes), pinnedNoteQueries em shared/db.ts. Frontend: ContextRail.jsx busca no mount, escuta CustomEvent crm-pin-created, DELETE otimista.

Camada de Proteção de Dados (Phase 45)

Criptografia híbrida em repouso — base de criptografia client-side + criptografia vault server-side.

Client-Side (Browser)

• frontend/src/crm/crypto/e2ee.ts — wrapper WebCrypto (214 linhas)
• PBKDF2 (100k iterações, SHA-256) → chave mestre AES-256-GCM
• Ciclo de vida da chave: initMasterKey(password) no login → sessionStorage → clearMasterKey() no logout/401
• Recuperação: generateRecoveryKey() → formato 1Password (XXXX-XXXX-XXXX-XXXX-XXXX)

Server-Side (Bun + SQLite)

• shared/vault.ts — encryptField()/decryptField() usando chave vault AES-256-GCM (formato prefixo v1:)
• Chaves de API: criptografadas ao salvar, descriptografadas ao carregar (transparente para o frontend) — routes/system.ts
• Mensagens de chat: auto-criptografia no INSERT, auto-descriptografia no SELECT — db.ts + migration 015
• Recovery keys: tabela recovery_keys (migration 016), 4 endpoints de API

Security Headers

• CSP: default-src 'self'; script-src 'self' em todas as respostas CRM
• X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin

Sanitização de PII

• shared/pii-sanitizer.ts — redige emails, chaves de API (sk-ant-*, sk-*), JWTs, números de cartão
• Aplicado na ingestão de logs JSONL do terminal (routes/chat.ts)

Endpoints de Recovery Key

Detalhes completos de segurança: docs/SECURITY.md, docs/architecture/PHASE_45_E2EE.md.