Transparencia

Transparencia é uma ferramenta abrangente para coletar, transformar e visualizar dados de transparência pública municipal. Ela agiliza o processo desde a extração dos dados brutos dos portais públicos até a modelagem analítica (dbt) e a exploração em um dashboard web interativo.

Funcionalidades

• Pipeline de Extração e Carga (ELT): Extração e carga automatizadas de dados brutos de portais de transparência pública, por portal (ex: porciuncula_prefeitura).
• Transformação Analítica (dbt): Modelagem em camadas (staging → marts) sobre PostgreSQL, com testes de dados e documentação geradas via dbt.
• Análise de Dados: Módulos para posição fiscal, execução orçamentária, lacunas em licitações, anomalias contratuais, concentração de fornecedores, folha vs. serviços, fontes de receita, CAPREM, saúde e tendências ano a ano.
• Dashboard Web: Aplicação Next.js interativa para explorar os dados dos marts dbt, com componentes e queries compartilhados entre pacotes do monorepo.

Arquitetura

Monorepo com pipeline Python (ELT + dbt) e frontend TypeScript (Next.js):

• elt/ — extração, carga e transformação (dbt) dos dados públicos; projeto Python gerenciado com uv.
• apps/web/ — dashboard Next.js (App Router).
• packages/db/ — camada de queries Kysely sobre os marts dbt (schema public), consumida pelo apps/web.
• packages/ui/ — componentes de visualização compartilhados.

Pré-requisitos

• uv: gerenciador e instalador de pacotes Python (Python 3.13).
• pnpm: gerenciador de pacotes do monorepo TypeScript (Node conforme .nvmrc).
• Docker: para subir o PostgreSQL local usado pelo ELT/dbt e pelo dashboard.

Configuração

1. Clone o repositório.
2. Suba o PostgreSQL local:

docker compose up -d postgres

3. Instale as dependências:

make install   # dependências Python (elt/)
pnpm install   # dependências do monorepo TypeScript

4. Copie .env.example para .env e ajuste DATABASE_URL/PORTAL_SLUG conforme necessário.

Uso

O projeto utiliza um Makefile para gerenciar as tarefas do ELT/dbt e scripts pnpm/turbo para o monorepo TypeScript.

Pipeline ELT (extração e carga)

make elt/extract PORTAL=porciuncula_prefeitura [YEARS="2024 2025"] [ONLY=DespesasGerais]
make elt/load PORTAL=porciuncula_prefeitura [DIR=data/raw_runs/20250101_120000]

Transformação (dbt)

make dbt/deps    # instala pacotes dbt
make dbt/seed    # carrega seeds
make dbt/run     # roda os models [SELECT=...]
make dbt/test    # roda os testes de dados [SELECT=...]
make dbt/docs    # gera e serve a documentação dbt

Dashboard Web (Next.js + TypeScript)

Para iniciar o servidor de desenvolvimento do portal web:

pnpm dev
# ou
make dev

Para compilar e testar os pacotes do monorepo:

pnpm build
pnpm test

Desenvolvimento

• Executar testes Python (ELT/dbt): make test
• Lint e formatar código Python: make check
• Executar testes TS (Kysely, web): make test/ts (ou pnpm test)
• Skills do BMad (não versionados): os skills bmad-*, wds-* e bmod-* em .claude/skills/ e o diretório _bmad/ são gerados pelo instalador (BMad 6.12.4) e ficam fora do git. Em um clone novo, rode npx bmad-method install na raiz e selecione os módulos core, bmm, bmb, cis, tea e wds.

Licença

Este projeto é distribuído sob a GNU Affero General Public License v3.0. Uso, modificação e distribuição (incluindo como serviço web) são permitidos, desde que a atribuição seja mantida e, no caso de versões modificadas rodando como serviço, o código-fonte correspondente seja disponibilizado.