Skip to content

AI Copilot + Documentation Engine Architecture

Visão geral

Esta fase introduz uma arquitetura com AI Orchestrator desacoplado, Copilot lateral no dashboard, integração de documentação via MkDocs, mecanismo de busca interno de docs, handoff para PR de código e preparação para GPT-5.2 e ElevenLabs TTS.

Componentes

  • services/ai-orchestrator/: classifica intenção, aplica políticas de execução, expõe PATCH PLAN e faz roteamento para tools permitidas.
  • routes/adminCopilotRoutes.js: endpoints de chat/histórico (/admin/copilot/messages, /admin/copilot/history).
  • sql/0014_ai_action_logs.sql: trilha de auditoria central (ai_action_logs) com suporte a undo.
  • scripts/buildDocsSearchIndex.js: gera docs/docs-search-index.json.
  • GET /internal/docs/search: busca semântica simplificada no índice de docs.
  • Integração de TTS centralizada na API Express via ElevenLabs.

Fluxo do Copilot

  1. UI lateral envia mensagem + modo (suggest ou execute_with_confirmation).
  2. Orchestrator detecta intenção (docs_lookup, content_generation, code_change, etc.).
  3. Se necessário, gera PATCH PLAN para handoff Codex (PR-first).
  4. Ação e resposta são registradas em ai_action_logs.

Fluxo Docs interno

  1. Dashboard consulta metadata (/admin/docs/metadata) com versão e commit hash.
  2. Visualizador interno continua carregando conteúdo diretamente de docs/.
  3. Busca de docs ocorre por /internal/docs/search usando índice gerado automaticamente.

Fluxo de PR automático (docs editor)

  1. Editor envia path + markdown para /admin/docs/editor/save.
  2. Backend cria branch, commit automático e retorna instruções de próximo passo (open_pr).
  3. Pipeline de docs é o validador obrigatório antes de merge.

LLM Provider

  • Layer de provider via providerConfig.js com:
  • provider/model
  • timeout/retry
  • orçamento mensal
  • uso restrito a admins

Segurança e governança

  • Acesso admin-only via requireAdmin.
  • Rate limit aplicado nos endpoints sensíveis.
  • Tool registry em allowlist.
  • Banco acessado apenas por APIs existentes (sem bypass direto via Copilot).

Diagrama (alto nível)

Dashboard Copilot UI -> /admin/copilot/messages -> ai-orchestrator -> tools/API -> ai_action_logs Dashboard Docs -> /admin/docs/metadata + /admin/system/docs -> docs/ Copilot -> /internal/docs/search -> docs-search-index.json