---
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

| Diretório | Responsabilidade |
|-----------|------------------|
| `src/api/` | FastAPI app, routes (~45), middleware (rate limiting, compression, metrics, logging), auth (JWT + OAuth) |
| `src/api/v1/` | Endpoints versionados (`dados_gov`) |
| `src/services/` | Lógica de negócio. Key services: `chat_service.py`, `agent_orchestrator.py`, `investigation_service.py`, `maritaca_client.py`, `agent_lazy_loader.py` |
| `src/llm/` | Abstração de providers. `providers.py` define enum + fallback chain |
| `src/core/` | Config (`config.py` com pydantic-settings), logging, exceptions, caching, audit |
| `src/infrastructure/` | Agent pool, **CQRS**, **Event Sourcing**, health checks, observability (OpenTelemetry + Grafana), resilience patterns, WebSocket, Celery queue |
| `src/models/` | SQLAlchemy ORM (investigation, chat, entity_graph, ...) |
| `src/schemas/` | Pydantic request/response |
| `src/db/` | Sessão async (SQLAlchemy + asyncpg) |
| `src/ml/` | Pipelines (scikit-learn, Prophet, UMAP, HDBSCAN) |
| `src/memory/` | Contexto de agente |
| `src/tools/` | Integrações de tooling |
| `src/tasks/` | Celery background tasks |

## 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