Arquitetura Técnica — ProspectaBR | Luminvs Tecnologia

Arquitetura Técnica — ProspectaBR

Versão: 2025.3 • Desenvolvido por: Luminvs Tecnologia

1. Visão Geral

O ProspectaBR é um sistema on-premises de inteligência empresarial desenvolvido em Python + Flask. Ele combina um núcleo API REST local com uma interface web integrada (HTML + Bootstrap + Jinja), permitindo busca, atualização e extração de leads diretamente na base oficial da Receita Federal (CNPJs), sem dependência de servidores externos.

Componentes principais

Flask — servidor local e API REST.
DuckDB — banco analítico embarcado (~9 GB da base RFB).
Frontend local — interface web em HTML/Jinja com Bootstrap.
APIs integradas — Google Maps, Receita Federal e módulos internos.
Execução offline — 100% local, sem SaaS nem coleta de dados.

2. Arquitetura do Sistema

Modelo API + UI integrados, com Flask servindo endpoints REST e páginas HTML. DuckDB é acessado por SQL otimizado.

├── app/
│   ├── main.py                 # servidor Flask principal
│   ├── routes/
│   │   ├── api.py              # endpoints REST (JSON)
│   │   ├── views.py            # páginas HTML renderizadas
│   ├── services/
│   │   ├── duckdb_service.py   # consultas SQL
│   │   ├── maps_scraper.py     # raspagem Google Maps
│   ├── static/                 # CSS, JS e assets locais
│   └── templates/              # páginas Jinja
└── data/
    ├── empresas.duckdb         # base consolidada CNPJ (RFB)
    └── logs/                   # registros locais

3. API REST Local

Endpoints REST retornam JSON para consumo interno/externo.

GET  /api/busca_cnpj?uf=TO&atividade=6201-5/01
GET  /api/atualiza_cnpj?cnpj=12345678000199
GET  /api/maps?cidade=Palmas&termo=academia

4. Banco de Dados

import duckdb
con = duckdb.connect('data/empresas.duckdb')
df = con.execute("SELECT uf, COUNT(*) FROM estabelecimentos GROUP BY uf").df()

Vantagens do DuckDB

Armazenamento local colunar com alta compressão.
Sem servidor dedicado (embedded).
Consultas rápidas em milhões de registros.
Integração com Pandas/Polars/Parquet.

5. Segurança e Privacidade

Execução 100% offline.
Sem uso de SaaS para dados da RFB.
Controle de acesso local + logs.
Pacotes assinados e verificados pela Luminvs.

6. Deploy e Execução

# Instalação (modo dev)
pip install -r requirements.txt

# Execução local
python app/main.py
# ou
flask run --host=0.0.0.0 --port=5000

7. Variáveis de Ambiente

PROSPECTABR_DB=data/empresas.duckdb
PROSPECTABR_PORT=5000
PROSPECTABR_ENV=production
LOG_LEVEL=INFO

8. Licenciamento

Software proprietário da Luminvs Tecnologia, licenciado para uso individual ou corporativo sob modelo self-hosted. Código-fonte fechado e auditável mediante contrato.

9. Distribuição e Execução Local

Distribuído como aplicativo compilado em C a partir do código-fonte Python (Nuitka standalone), garantindo execução autônoma sem acesso ao código-fonte.

Instalação padrão em Windows: C:\ProspectaBR.
Estrutura de pastas:
- C:\ProspectaBR\app\ — sistema principal e binários.
- C:\ProspectaBR\bd\ — base da Receita Federal (consulta local).
Raspagem do Google Maps: módulo próprio em %AppData%\ProspectaBR, armazenado como binário criptografado, aberto apenas pelo sistema.

Modo servidor de rede local: libere o IP da máquina hospedeira na porta 5000 e acesse via navegador.

# Exemplo
http://192.168.0.10:5000

Para usar outra porta, ajuste no .env:

PROSPECTABR_PORT=8080

Requisitos: Windows 10/11, permissões para leitura/escrita em C:\ProspectaBR e no AppData do usuário.