Marlin - Investigacao Corporativa

Plataforma OSINT de Investigacao Corporativa - consulte CNPJs, CPFs, processos e mapeie teias societarias com grafo interativo. Finalizado, passivel de melhorias.

✅ Status: Finalizado - pronto para uso, evolucoes futuras como melhorias incrementais
Pipeline funcional em modo demo (docs/images/, api.exemplo.com mock, 1 empresa, 2 socios, grafo societario), com arquitetura limpa, 9 transforms BR e 4 routers. Mantido como portfolio principal, com melhorias planejadas mas sem bloqueios. Veja ## Roadmap.

---

Indice

• Visao Executiva
• Overview Detalhado
• Demo
• Features
• Arquitetura
• Transforms BR (9)
• API Reference (4 routers)
• Frontend
• Tech Stack & Linguagens
• Estrutura do Projeto
• Instalacao
• Configuracao
• Uso
• Testes
• Decisoes Tecnicas
• Limitacoes & Melhorias
• Roadmap
• O que este projeto demonstra
• Licenca

---

Visao Executiva

Metrica	Valor	Fonte
Entidades	CNPJ, CPF, Processos, Telefone, Email, Endereco	OSINT Graph
Empresa demo	Agro Brasil Importacoes Ltda (11222333000181)	ATIVA, R$ 5M, 4621500
Socios	2 (Joao Carlos Silva - SOCIO-ADMINISTRADOR, Maria Fernanda Costa - SOCIA)	Quadro Societario
Grafo	Teia societaria com cadeia de decisores	routers/graph.py:1
Backend	4 routers, 9 transforms, 6 utils	backend/app/main.py:1
Frontend	Investigacao, Grafo, Historico	frontend/app.py:1
Linhas	~2.1k linhas Python	31 arquivos

Em uma frase: Marlin e um OSINT Graph que transforma CNPJ em grafo de pessoas, empresas, processos e contatos - e prova isso com codigo, arquitetura e demo.

---

Overview Detalhado

Contexto

Due diligence corporativa no Brasil exige cruzar CNPJs com QSA, processos judiciais (DataJud), enderecos, telefones e cadeias societarias - dados dispersos em BrasilAPI, MinhaReceita, ReceitaWS, DataJud, OpenCNPJ e ViaCEP. Fazer isso manualmente e mapear a teia societaria para encontrar decisores leva horas.

Problema

Como, a partir de um CNPJ ou CPF, (1) consultar dados cadastrais, (2) extrair quadro societario, (3) mapear cadeia de empresas por CPF, (4) buscar processos no DataJud, e (5) visualizar tudo em grafo interativo - de forma rapida, com transformacoes reutilizaveis e frontend simples?

Solucao

Backend FastAPI (backend/app/main.py:1) - 4 routers (entities, graph, insights, transforms) + 9 transforms em transforms/br/ (cnpj_cadeia, cnpj_datajud, cnpj_minhareceita, cnpj_receitaws, cnpj_socios, cpf_empresas, email_rede, nome_cpf, telefone_cpf) + 6 utils (brasil_api, minha_receita, receita_ws, datajud, radar_elite).

Frontend Streamlit (frontend/app.py:1) - 3 paginas (Investigacao, Grafo, Historico) com entity_card e graph_component, consulta por CNPJ (00.000.000/0001-00) e CPF, exibindo DADOS DA EMPRESA, QUADRO SOCIETARIO, ENDERECO e CONTATO, com acao Buscar Decisores (Cadeia Societaria).

Resultado Finalizado: fluxo completo CNPJ -> QSA -> CPF -> empresas -> processos -> grafo, tudo mockado com api.exemplo.com, pronto para uso e passivel de melhorias incrementais.

---

Demo

Interface demo (Marlin OSINT Graph - modo api.exemplo.com mock):

Investigacao - CNPJ 00.000.000/0001-00 com dados completos

O que prova: DADOS DA EMPRESA (Razao, Fantasia, CNPJ, Situacao ATIVA, Capital R$ 5M, CNAE 4621500), QUADRO SOCIETARIO (Joao Carlos Silva 41-50, CPF *.456.789-, Maria Fernanda Costa 31-40), ENDERECO (Sao Paulo, SP), CONTATO ((11) 3456-7890), com 1 empresa, 2 socios, 1 endereco, 1 telefone, 1 email. Botao Buscar Decisores expande a cadeia.

---

Features

• ✅ Consulta CNPJ/CPF com 9 transforms BR
• ✅ Quadro societario com cargo, data e faixa etaria
• ✅ Cadeia societaria (CPF -> empresas)
• ✅ Processos DataJud por CNPJ/CPF
• ✅ Grafo interativo de teia societaria
• ✅ Frontend com Investigacao, Grafo e Historico

---

Arquitetura

flowchart LR
    A["Streamlit - Investigacao"] --> B["FastAPI - entities, graph"]
    B --> C["Transforms BR - 9 modulos"]
    C --> D["Utils mock - BrasilAPI, MinhaReceita, ReceitaWS, DataJud"]
    D --> E["Graph - teia societaria"]

Loading

Componentes: backend/app/main.py:1, backend/app/routers/*, backend/app/transforms/br/*, frontend/app.py:1.

---

Transforms BR (9)

Transform	Arquivo	Fonte mock	Uso
cnpj_cadeia	cnpj_cadeia.py	api.exemplo.com	Cadeia societaria
cnpj_datajud	cnpj_datajud.py	api.exemplo.com/datajud	Processos por CNPJ
cnpj_minhareceita	cnpj_minhareceita.py	api.exemplo.com/minhareceita	Dados RFB
cnpj_receitaws	cnpj_receitaws.py	api.exemplo.com/receitaws	Dados RFB alt
cnpj_socios	cnpj_socios.py	api.exemplo.com	QSA
cpf_empresas	cpf_empresas.py	api.exemplo.com	CPF -> empresas
email_rede	email_rede.py	api.exemplo.com	Email -> rede
nome_cpf	nome_cpf.py	api.exemplo.com	Nome -> CPF
telefone_cpf	telefone_cpf.py	api.exemplo.com	Telefone -> CPF

---

API Reference (4 routers)

Swagger em http://localhost:8000/docs:

Router	Prefixo	Exemplo
entities	/entities	GET /entities?cnpj=11222333000181
graph	/graph	GET /graph?cnpj=11222333000181
insights	/insights	GET /insights?cnpj=...
transforms	/transforms	GET /transforms/br/cnpj_cadeia?cnpj=...

---

Frontend

frontend/app.py:1 com 3 paginas, entity_card, graph_component, consulta por CNPJ/CPF, exibicao de QSA e grafo.

---

Tech Stack & Linguagens

Camada	Tecnologia	Linguagem	Uso
Backend	FastAPI	Python 3.11	4 routers, 9 transforms
Frontend	Streamlit	Python	Investigacao, Grafo
APIs	api.exemplo.com (mock)	HTTP/JSON	BrasilAPI, MinhaReceita, etc.

Linguagens no repositorio: Python 100% (backend/**/*.py, frontend/**/*.py). Shell auxiliar.

Nota: todas as URLs externas sao https://api.exemplo.com por padrao (mock). Aponte .env para endpoints reais quando necessario.

---

Estrutura do Projeto

marlin/
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── routers/ (entities, graph, insights, transforms)
│   │   ├── transforms/br/ (9)
│   │   └── utils/ (brasil_api, minha_receita, receita_ws, datajud)
│   └── tests/
├── frontend/
│   ├── app.py
│   └── components/ (entity_card, graph_component)
├── docs/
│   ├── images/ (01-investigacao.png)
│   └── architecture.md
├── .github/workflows/ci.yml + cd.yml
├── .env.example
├── requirements.txt
└── README.md

---

Instalacao

git clone https://github.com/PIRANGUEIRO/marlin.git
cd marlin
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env

# Backend
uvicorn backend.app.main:app --reload --port 8000
# Frontend
streamlit run frontend/app.py

---

Configuracao

Variavel	Descricao	Obrigatoria
BRASILAPI_URL	BrasilAPI mock	nao
MINHA_RECEITA_URL	MinhaReceita mock	nao
RECEITAWS_URL	ReceitaWS mock	nao
DATAJUD_URL	DataJud mock	nao

---

Uso

Acesse http://localhost:8501, digite CNPJ 00.000.000/0001-00 ou CPF, veja DADOS DA EMPRESA, QUADRO SOCIETARIO e clique Buscar Decisores.

---

Testes

python -m py_compile backend/app/main.py
find . -name "*.py" -exec python -m py_compile {} \\;

---

Decisoes Tecnicas

Decisao	Motivo	Trade-off
FastAPI + transforms	Reuso por CNPJ/CPF/entidade	Muitos arquivos
Streamlit	Prototipacao rapida	Nao escala
api.exemplo.com mock	Portfolio sem chaves	Sem dados reais

---

Limitacoes & Melhorias

Passivel de melhorias (finalizado, nao bloqueado):

• Adicionar testes E2E (CNPJ -> grafo)
• Cache Redis para DataJud
• Paginacao em graph.py
• Rate limiting nos transforms

---

Roadmap

• v1.0.0 (atual): Finalizado, 4 routers, 9 transforms, 1 print, docs completas
• v1.1: Testes E2E + cache + melhorias de grafo

---

O que este projeto demonstra

• Python (FastAPI, Streamlit, 2.1k linhas)
• OSINT & Graph (teia societaria, transforms)
• API Integration (4 APIs BR, mock)
• Finalizado com qualidade, passivel de evolucao

---

Licenca

MIT - ver LICENSE.