Rede CNPJ - Engine Nacional de Grafos

Sistema de analise de redes de relacionamento entre empresas brasileiras a partir dos dados publicos de CNPJ da Receita Federal. Permite visualizar e explorar conexoes entre empresas e socios atraves de uma interface web interativa com grafos.

Baseado no projeto original rede-cnpj por rictom, reescrito com FastAPI, motor de grafos em memoria e formato Parquet para performance em escala nacional.

Requisitos

• Python 3.11+
• ~16 GB de RAM (o grafo completo e carregado em memoria)
• ~50 GB de espaco em disco para os dados brutos

Instalacao

git clone https://git.pop.coop/pop/rede-cnpj.git
cd rede-cnpj
python -m venv .venv
source .venv/bin/activate
make install

Baixar e processar os dados

O pipeline de dados consiste em etapas sequenciais. Execute cada uma a partir da raiz do projeto.

1. Baixar os dados da Receita Federal

Baixa os arquivos ZIP dos dados abertos de CNPJ direto do portal da Receita Federal (~5 GB compactados):

cd rede_cria_tabelas
python dados_cnpj_baixa.py

Os arquivos serao salvos em rede_cria_tabelas/dados-publicos-zip/.

Fonte dos dados: https://arquivos.receitafederal.gov.br/dados/cnpj/dados_abertos_cnpj/ Os dados sao atualizados mensalmente pela Receita Federal.

2. Converter para SQLite

Descompacta os CSVs e gera o banco cnpj.db com dados de empresas, estabelecimentos, socios e tabelas auxiliares:

python dados_cnpj_para_sqlite.py

O banco sera gerado em rede_cria_tabelas/dados-publicos/cnpj.db.

3. Gerar tabela de relacionamentos (rede.db)

Cria o banco rede.db com as ligacoes entre empresas e socios:

python rede_cria_tabela_rede.db.py

4. Gerar indice de links ETE (cnpj_links_ete.db)

Cria o banco cnpj_links_ete.db que mapeia enderecos, telefones e emails compartilhados entre empresas (opcional):

python rede_cria_tabela_cnpj_links_ete.py
cd ..

5. Mover bancos SQLite e migrar para Parquet

# Mover bancos para a pasta bases
mkdir -p rede/bases
cp rede_cria_tabelas/dados-publicos/cnpj.db rede/bases/
cp rede_cria_tabelas/dados-publicos/rede.db rede/bases/
cp rede_cria_tabelas/dados-publicos/cnpj_links_ete.db rede/bases/

# Migrar tabela de ligacoes para Parquet (otimizado para carregamento em memoria)
mkdir -p data/processed
python -m scripts.migrate_sqlite_to_parquet rede/bases/rede.db data/processed --table ligacao

Apos a migracao, os arquivos em rede_cria_tabelas/dados-publicos/ e rede_cria_tabelas/dados-publicos-zip/ podem ser apagados.

Executar o servidor

uvicorn app.main:app --host 0.0.0.0 --port 8000

Acesse a interface web em http://localhost:8000

Endpoints da API

Metodo	Endpoint	Descricao
GET	/health	Health check
POST	/api/v1/graph/expand	Expandir no do grafo por profundidade
POST	/api/v1/graph/paths	Encontrar caminhos entre dois nos
GET	/api/v1/graph/neighbors/{node_id}	Vizinhos de um no
POST	/api/v1/graph/ete-links	Links por endereco/telefone/email
POST	/api/v1/nodes/info	Informacoes de nos (nome, status, etc.)
GET	/api/v1/nodes/{node_id}/actions	Acoes externas (JusBrasil, Google)

Desenvolvimento

make install   # instalar dependencias (inclui dev)
make test      # rodar testes com cobertura
make lint      # verificar estilo com ruff
make type      # verificar tipos com mypy
make all       # lint + type + test

Estrutura do projeto

rede-cnpj/
├── app/                  # Backend FastAPI
│   ├── main.py           # Ponto de entrada, carrega grafo no startup
│   ├── routes/           # Endpoints da API (graph, nodes)
│   └── schemas/          # Modelos Pydantic
├── engine/               # Motor de grafos em memoria
│   ├── graph_engine.py   # Classe principal GraphEngine
│   ├── algorithms.py     # BFS, busca de caminhos
│   ├── loaders.py        # Carga de Parquet
│   └── models.py         # Dataclasses Node e Edge
├── etl/                  # Utilitarios de normalizacao (CNPJ/CPF)
├── actions/              # Provedores de acoes externas
├── scripts/              # Migracao SQLite -> Parquet
├── frontend/             # Interface web (HTML/JS com grafos interativos)
├── rede_cria_tabelas/    # ETL: download e conversao dos dados da Receita
├── rede/                 # Aplicativo desktop legado (Tkinter)
└── tests/                # Testes unitarios e de integracao