cidadao-ai-architecture

name: cidadao-ai-architecture description: Use ao tocar arquitetura do Cidadão.AI backend — request flow, services layer, LLM providers, infraestrutura. Carrega padrões críticos como fallback Maritaca→Anthropic, lazy loading, semantic routing, CQRS+Event Sourcing, OpenTelemetry. Ative quando mexer em src/api, src/services, src/infrastructure, src/llm, ou ao desenhar fluxos novos.

Cidadão.AI Architecture

Backend FastAPI + Python 3.11+ no Railway. Arquitetura por camadas com lazy loading de agentes e fallback automático entre LLMs.

Request Flow

Client
  ↓
FastAPI app (src/api/app.py)
  ↓
Routes (src/api/routes/, ~45 modules)
  ↓
Services (src/services/, business logic)
  ↓
Agents (src/agents/, 20 agentes via lazy loader)
  ↓
LLM Providers (src/llm/providers.py)
  ↓
Maritaca AI (primary, PT-BR optimized) → Anthropic Claude (auto-fallback)

Camadas e responsabilidades

Padrões críticos

1. LLM Fallback chain

• Primary: Maritaca AI (Sabiá, otimizado para Português brasileiro)
• Fallback: Anthropic Claude (auto-switch quando Maritaca falha ou rate-limit)
• Configurado via LLM_PROVIDER env var
• Outros providers no enum: GROQ, TOGETHER, HUGGINGFACE (não usados em produção atual)

2. Agent Lazy Loading

• Agentes NÃO são importados no startup
• Carregados sob demanda via services/agent_lazy_loader.py
• Pooled em infrastructure/agent_pool.py (reuso entre requests)
• Nunca fazer from src.agents.zumbi import Zumbi em uma route

3. Semantic Routing

• ayrton_senna.py recebe a query e decide qual agente especialista invocar
• Lógica de roteamento centralizada — não duplicar em routes ou services

4. Master Orchestration

• abaporu.py coordena workflows multi-agente complexos
• Quando uma investigação precisa de múltiplos especialistas (ex.: análise textual + detecção de anomalia + geração de relatório), Abaporu orquestra a sequência

5. Context Memory

• nana.py é a única fonte de verdade para contexto conversacional
• Não persistir contexto em outros lugares (Redis, sessions, etc.) — sempre via Nanã

6. CQRS + Event Sourcing

• infrastructure/cqrs/ separa Command/Query
• infrastructure/events/ mantém event store para fluxos de investigação
• Use quando o fluxo passar por múltiplos agentes/estados — não para CRUD simples

7. Migrations no startup

• Alembic com asyncpg
• Migrations rodam na lifespan function de app.py, não no Procfile release phase
• Deploy é zero-downtime mas migrations precisam ser backwards-compatible

8. Observabilidade

• OpenTelemetry para tracing
• Grafana + Prometheus para métricas
• infrastructure/observability.py é o ponto único de integração

Endpoints principais (em src/api/routes/)

Chat / Investigação

• chat.py, chat_drummond_factory.py, chat_investigative.py, chat_zumbi_integration.py — interface conversacional
• websocket_chat.py — chat real-time
• investigations.py — workflows de investigação

Análise

• analysis.py, agents.py, agent_metrics.py — disparar/monitorar agentes
• orchestration.py — controle direto do Abaporu

Dados governamentais

• transparency.py, transparency_coverage.py — Portal da Transparência
• federal_apis.py — APIs federais brasileiras
• geographic.py — dados geográficos

Operacional

• auth.py, oauth.py, api_keys.py — autenticação
• health.py, monitoring.py, observability.py — saúde
• chaos.py — chaos engineering
• resilience.py — circuit breakers / retries

Especialização

• academy.py — programa educacional
• dashboard.py, dashboard_view.py — dashboards
• voice.py — interface de voz
• webhooks.py, notifications.py — integrações externas
• graphql.py — endpoint GraphQL alternativo
• ml_pipeline.py — pipelines ML
• cqrs.py — endpoints CQRS
• export.py, reports.py — exportação
• network.py, visualization.py — visualização de redes/grafos
• llm_costs.py — controle de custo

Anti-patterns

• ❌ Importar agente direto em route — usa lazy loader
• ❌ Persistir contexto fora do nana.py
• ❌ Roteamento de query fora do ayrton_senna.py
• ❌ Migrations em Procfile release phase — fica em lifespan
• ❌ Lógica de fallback LLM duplicada — sempre via llm/providers.py
• ❌ Adicionar provider novo sem registrar no enum LLMProvider
• ❌ CRUD simples passando por CQRS — use SQLAlchemy direto