# turicas/eleicoes-brasil architecture

> Architecture diagram of the GitHub repository turicas/eleicoes-brasil, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/turicas/eleicoes-brasil
- Repository: https://github.com/turicas/eleicoes-brasil

## Overview

Eleições Brasil downloads TSE election data, extracts and normalizes it, then writes consolidated CSV outputs. Its documented datasets are candidacies, declared assets, voting by electoral zone, and campaign-finance revenue and expenses. Separate capabilities cover current party-affiliation data, 2022 vote-counting utilities, and candidate links for DivulgaCandContas. The graph shows only relationships visible in the README or sampled source; it does not infer connections among independent scripts or unsampled modules.

Main entry points: [`tse.py`](https://github.com/turicas/eleicoes-brasil/blob/develop/tse.py) (TSE CLI), [`data`](https://github.com/turicas/eleicoes-brasil/tree/develop/data) (CSV data files), [`extractors.py`](https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py) (Download and normalize), [`filiacao.py`](https://github.com/turicas/eleicoes-brasil/blob/develop/filiacao.py) (Affiliation spider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extract["Election data extraction"]
  node_tse_cli["TSE CLI<br/>[tse.py]"]
  node_extractor["Download and normalize<br/>[extractors.py]"]
  node_candidacies["Candidacies<br/>[extractors.py]"]
  node_assets["Declared assets<br/>[extractors.py]"]
  node_zone_votes["Zone voting<br/>[extractors.py]"]
  node_campaign_finance["Campaign finance<br/>[extractors.py]"]
  node_storage_settings["Data paths<br/>[settings.py]"]
  node_csv_outputs["CSV data files"]
  node_shared_utils["CSV and text utilities<br/>[utils.py]"]
end

subgraph group_affiliation["Party affiliation"]
  node_filia_spider["Affiliation spider<br/>[filiacao.py]"]
  node_legacy_affiliation["Legacy ZIP tools"]
  node_legacy_parser["Legacy ZIP parser<br/>[filiacao_parse.py]"]
end

subgraph group_counting["Vote counting"]
  node_counting_summary["Apuração summary<br/>[apuracao.py]"]
  node_municipality_codes["Municipality codes<br/>[municipios_tse.py]"]
  node_municipal_votes["Municipal vote export"]
end

subgraph group_extras["Candidate links"]
  node_candidate_links["Candidate links"]
end

node_user(("CLI user"))
node_tse_source["TSE data repository"]
node_filia_api["TSE affiliation API"]

node_user -->|"runs"| node_tse_cli
node_tse_cli -->|"calls extraction"| node_extractor
node_extractor -->|"downloads archives"| node_tse_source
node_extractor -->|"uses download paths"| node_storage_settings
node_extractor -->|"writes results"| node_csv_outputs
node_tse_cli -->|"selects dataset"| node_candidacies
node_tse_cli -->|"selects dataset"| node_assets
node_tse_cli -->|"selects dataset"| node_zone_votes
node_tse_cli -->|"selects dataset"| node_campaign_finance
node_filia_spider -->|"requests data"| node_filia_api
node_filia_spider -->|"exports records"| node_csv_outputs
node_legacy_affiliation -.->|"uses retired source"| node_filia_api
node_legacy_parser -->|"parses downloaded ZIPs"| node_legacy_affiliation
node_municipality_codes -->|"downloads results archive"| node_tse_source
node_municipality_codes -->|"writes municipality list"| node_csv_outputs
node_municipal_votes -->|"reads municipality list"| node_csv_outputs
node_municipal_votes -->|"writes vote summary"| node_csv_outputs
node_counting_summary -.->|"downloads results"| node_tse_source
node_candidate_links -->|"normalizes text"| node_shared_utils

click node_tse_cli "https://github.com/turicas/eleicoes-brasil/blob/develop/tse.py"
click node_extractor "https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py"
click node_candidacies "https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py"
click node_assets "https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py"
click node_zone_votes "https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py"
click node_campaign_finance "https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py"
click node_storage_settings "https://github.com/turicas/eleicoes-brasil/blob/develop/settings.py"
click node_csv_outputs "https://github.com/turicas/eleicoes-brasil/tree/develop/data"
click node_filia_spider "https://github.com/turicas/eleicoes-brasil/blob/develop/filiacao.py"
click node_legacy_affiliation "https://github.com/turicas/eleicoes-brasil/blob/develop/filiacao_download.py"
click node_legacy_parser "https://github.com/turicas/eleicoes-brasil/blob/develop/filiacao_parse.py"
click node_counting_summary "https://github.com/turicas/eleicoes-brasil/blob/develop/apuracao/apuracao.py"
click node_municipality_codes "https://github.com/turicas/eleicoes-brasil/blob/develop/apuracao/municipios_tse.py"
click node_municipal_votes "https://github.com/turicas/eleicoes-brasil/blob/develop/apuracao/votacao_municipio.py"
click node_candidate_links "https://github.com/turicas/eleicoes-brasil/blob/develop/divulgacandcontas.py"
click node_shared_utils "https://github.com/turicas/eleicoes-brasil/blob/develop/utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tse_cli,node_extractor,node_candidacies,node_assets,node_zone_votes,node_campaign_finance,node_storage_settings,node_csv_outputs,node_shared_utils,node_user toneBlue
class node_filia_spider,node_legacy_affiliation,node_legacy_parser toneAmber
class node_counting_summary,node_municipality_codes,node_municipal_votes,node_filia_api toneMint
class node_candidate_links toneRose
class node_tse_source toneIndigo
```

## Components

### Election data extraction

- [TSE CLI](https://github.com/turicas/eleicoes-brasil/blob/develop/tse.py): `tse.py`
- [Download and normalize](https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py): `extractors.py`
- [Candidacies](https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py): `extractors.py`
- [Declared assets](https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py): `extractors.py`
- [Zone voting](https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py): `extractors.py`
- [Campaign finance](https://github.com/turicas/eleicoes-brasil/blob/develop/extractors.py): `extractors.py`
- [Data paths](https://github.com/turicas/eleicoes-brasil/blob/develop/settings.py): `settings.py`
- [CSV data files](https://github.com/turicas/eleicoes-brasil/tree/develop/data): `data`
- [CSV and text utilities](https://github.com/turicas/eleicoes-brasil/blob/develop/utils.py): `utils.py`

### Party affiliation

- [Affiliation spider](https://github.com/turicas/eleicoes-brasil/blob/develop/filiacao.py): `filiacao.py`
- [Legacy ZIP tools](https://github.com/turicas/eleicoes-brasil/blob/develop/filiacao_download.py): `filiacao_download.py`
- [Legacy ZIP parser](https://github.com/turicas/eleicoes-brasil/blob/develop/filiacao_parse.py): `filiacao_parse.py`

### Vote counting

- [Apuração summary](https://github.com/turicas/eleicoes-brasil/blob/develop/apuracao/apuracao.py): `apuracao/apuracao.py`
- [Municipality codes](https://github.com/turicas/eleicoes-brasil/blob/develop/apuracao/municipios_tse.py): `apuracao/municipios_tse.py`
- [Municipal vote export](https://github.com/turicas/eleicoes-brasil/blob/develop/apuracao/votacao_municipio.py): `apuracao/votacao_municipio.py`

### Candidate links

- [Candidate links](https://github.com/turicas/eleicoes-brasil/blob/develop/divulgacandcontas.py): `divulgacandcontas.py`

### Other components

- **CLI user**
- **TSE data repository**
- **TSE affiliation API**

## Connections

- CLI user → TSE CLI: runs (evidence: `README.md`)
- TSE CLI → Download and normalize: calls extraction (evidence: `tse.py`)
- Download and normalize → TSE data repository: downloads archives (evidence: `extractors.py`)
- Download and normalize → Data paths: uses download paths (evidence: `extractors.py`)
- Download and normalize → CSV data files: writes results (evidence: `README.md`)
- TSE CLI → Candidacies: selects dataset (evidence: `README.md`)
- TSE CLI → Declared assets: selects dataset (evidence: `README.md`)
- TSE CLI → Zone voting: selects dataset (evidence: `README.md`)
- TSE CLI → Campaign finance: selects dataset (evidence: `README.md`)
- Affiliation spider → TSE affiliation API: requests data (evidence: `filiacao.py`)
- Affiliation spider → CSV data files: exports records (evidence: `filiacao.py`)
- Legacy ZIP tools → TSE affiliation API: uses retired source
- Legacy ZIP parser → Legacy ZIP tools: parses downloaded ZIPs (evidence: `filiacao_parse.py`)
- Municipality codes → TSE data repository: downloads results archive (evidence: `apuracao/municipios_tse.py`)
- Municipality codes → CSV data files: writes municipality list (evidence: `apuracao/municipios_tse.py`)
- Municipal vote export → CSV data files: reads municipality list (evidence: `apuracao/votacao_municipio.py`)
- Municipal vote export → CSV data files: writes vote summary (evidence: `apuracao/votacao_municipio.py`)
- Apuração summary → TSE data repository: downloads results
- Candidate links → CSV and text utilities: normalizes text (evidence: `divulgacandcontas.py`)