README.md

# Observatório do Senado — IDS

Iniciativa cidadã independente de transparência parlamentar. O projeto
calcula e publica o Índice de Desempenho Senatorial (IDS) com base em dados
abertos oficiais do Senado Federal.

- Site: https://observasenado.org
- API pública: https://api.observasenado.org
- Código auditável: https://observasenado.org/codigo
- Metodologia: `docs/ANALISE_METODOLOGIA_v2.md`

## Escopo

O IDS avalia a atividade parlamentar mensurável durante a 57ª Legislatura. O
indicador combina seis dimensões: produtividade, efetividade, participação,
fiscalização, eficiência CEAP e transparência. Os resultados não constituem
juízo moral, ideológico ou eleitoral sobre os parlamentares.

O Observatório não possui vínculo institucional com o Senado Federal,
partidos, mandatos, campanhas eleitorais ou grupos de interesse.

## Arquitetura

```text
apps/web       Next.js 15, App Router, exportação estática e Tailwind CSS
apps/worker    Hono, TypeScript, SQLite e coleta das APIs oficiais
docs           documentação e análise metodológica
```

O frontend é publicado no Cloudflare Pages. A API executa em runtime Node.js
próprio e é exposta pelo domínio institucional. O cálculo completo é executado
semanalmente, com cache das fontes oficiais entre atualizações.

## Desenvolvimento local

Pré-requisitos: Node.js 22 ou superior e pnpm 9 ou superior.

```bash
pnpm install
pnpm dev:worker
```

Em outro terminal:

```bash
NEXT_PUBLIC_API_URL=http://localhost:8787 pnpm dev:web
```

Verificações principais:

```bash
pnpm --filter worker lint
pnpm --filter web build
```

Segredos e dados de runtime devem permanecer fora do repositório. Arquivos
`.env`, bancos, caches, logs e backups não integram a publicação auditável.

## API pública

Base: `https://api.observasenado.org`

| Endpoint | Descrição |
|---|---|
| `GET /health` | Estado da API |
| `GET /api/ranking` | Ranking e filtros |
| `GET /api/ranking/meta` | Partidos, UFs e blocos |
| `GET /api/senador/:codigo` | Perfil e dimensões de um senador |
| `GET /api/ceap/:codigo?ano=2026` | Gastos CEAP por período |

## Auditoria

O portal `/codigo` publica uma cópia sanitizada do código necessário para
examinar a coleta, as fórmulas e a apresentação dos resultados. Cada arquivo e
o pacote completo possuem hash SHA-256. Histórico de desenvolvimento,
credenciais e material operacional interno não são publicados.

Questionamentos metodológicos podem ser enviados para
`[email protected]`. Divergências de dados devem ser encaminhadas
para `[email protected]` com o link da fonte oficial correspondente.

## Fontes oficiais

- LEGIS: https://legis.senado.leg.br/dadosabertos
- ADM: https://adm.senado.gov.br/adm-dadosabertos

## Licença

O software é disponibilizado sob a licença MIT descrita em `LICENSE`. Os dados
parlamentares pertencem às respectivas fontes públicas oficiais.