Pular para conteúdo

ADR 0002: Arquitetura da API FastAPI com Streaming SSE, Persistência pgvector e Relatórios PDF

  • Status: Aceito
  • Data: 2026-08-30
  • Decisores: Usuário, Gemini / Antigravity, Claude Code

1. Contexto

Após a validação do motor core de deliberação antissicofancia (Fase 1), o sistema necessitava de uma camada de exposição e interação completa (Fase 2) para atender aos seguintes requisitos: 1. Interação em Tempo Real: Permitir que o usuário acompanhe o fluxo cognitivo das 3 fases (Crítica Cega, Debate Adversarial e Arbitragem) conforme os conselheiros emitem seus pareceres. 2. Persistência Relacional e Vetorial: Armazenar propostas, pareceres, debates e vereditos no PostgreSQL com suporte a busca semântica vetorial (pgvector) para correlacionar novas teses com atas de decisões anteriores. 3. Interface Visual Imersiva: Proporcionar uma experiência de "Mesa Redonda de Conselho" em Single Page Application (SPA). 4. Exportação Executiva em PDF: Gerar relatórios corporativos de alta resolução para apresentação formal a investidores e comitês.

2. Decisões Arquiteturais

2.1 API FastAPI com Streaming SSE (Server-Sent Events)

  • Adotamos FastAPI (src/api/main.py e src/api/routes/council.py) com protocolo Server-Sent Events (SSE) via StreamingResponse para streaming unidirecional em tempo real.
  • O protocolo SSE foi escolhido em detrimento de WebSockets pela menor complexidade operacional sobre HTTP/2 e facilidade de reconexão e buffering nativo em navegadores.

2.2 Persistência Híbrida e Resiliente (PostgreSQL + pgvector com Fallback em Memória)

  • O schema relacional (src/storage/schema.sql) define tabelas tipadas (proposals, council_opinions, debate_feedbacks, verdicts) com integridade referencial em cascata e vetor vector(1536) indexado por HNSW (vector_cosine_ops).
  • Para garantir que a aplicação e a suíte de testes automatizados rodem em qualquer ambiente sem dependência obrigatória de um PostgreSQL externo rodando durante desenvolvimento/testes, o DatabaseManager implementa fallback transparente para armazenamento thread-safe em memória com cálculo exato de similaridade de cosseno.

2.3 Frontend SPA com React, Vite e TailwindCSS

  • App modular em frontend/ com componentes semânticos (CouncilTable, MemberOpinionCard, DebateTimeline, VerdictSummary).
  • Suporte a modo simulado (offline mock) e conexão em tempo real à API.

2.4 Exportador Executivo em PDF via ReportLab

  • src/exporters/pdf_exporter.py implementa geração vetorial em PDF com paleta corporativa executiva, box de veredito, termômetro visual de Score de Risco (0-100), numeração de páginas em duas passadas e hash SHA-256 de integridade.

3. Consequências

Positivas:

  • Cobertura de testes automatizados com 100% de aprovação (28 testes passando no backend e build limpo no frontend).
  • Isolamento estrito de responsabilidades entre orquestração de IA, API, armazenamento e visualização.
  • Conformidade integral com a Matriz de 11 Itens do _framework/ corporativo.

Mitigações:

  • As chaves de API externas continuam opcionais no desenvolvimento graças ao modo de simulação embutido em todas as camadas.