Tributário 360 — Plataforma de Inteligência Tributária e Empresarial

Arquitetura & Roadmap de Consolidação

Domínio de referência: painel.tributario360.com.br Atualizado: 2026-06-18 · v4 (ecossistema + multi-tenant + integrações certificadas)

Documento de referência viva. Define onde estamos, a arquitetura-alvo (multiusuário, multi-tenant e segura) e o roadmap de consolidação.

O painel é a camada de inteligência de dados que se integra aos módulos já existentes do ecossistema — Business Plan (bp.tributario360.com.br) e Diagnóstico Estratégico (diagnostico.tributario360.com.br) — adotando a mesma identidade visual e o mesmo padrão de qualidade.

1. Onde estamos — Fase 0 concluída ✅

• Base CNPJ (Receita Federal) em produção no CT105 — PostgreSQL 16, database receita_cnpj.
• ETL mensal blue/green (download → import → validação → publicação atômica → limpeza), rollback por schema + snapshot ZFS.
• Camada de consulta (api): views enriquecidas + agregações materializadas (UF, município, CNAE, porte, natureza, situação, Simples/MEI, setor).
• Schemas para crescimento: crossref (cruzamentos), etl, api.
• painel.tributario360.com.br no ar (Caddy CT101, HTTPS) com /arquitetura.

Decisões fechadas: domínio único painel.tributario360.com.br; dados no CT105 (isolado); aplicação na VM103; entrada/TLS no Caddy CT101.

2. Ecossistema Tributário 360 — sistemas de referência

Análise feita com leitura do código e do schema na VM103 (2026-06-18). Os dois sistemas e o painel formam um ecossistema único — e o Diagnóstico já prevê a nossa base como sua "Fase B".

Business Plan — bp.tributario360.com.br

• Plano de negócios investidor do Tributário 360: 68 capítulos / 9 blocos / 3 fases. Descreve a visão da plataforma: AI Tax Intelligence Platform com 5 camadas, AI Tax Copilot, Decision Engine (cérebro orquestrador), Tax Transition Engine (Reforma — EC 132/2023, LC 214/2025) e certificado A1/A3.
• Stack: PHP 8.3 + SQLite (bp.db); auth + NDA + tracking (sessions, slide_views, events) + workflow de aprovação (pending→approved).
• Papel: define a VISÃO. Nossa base CNPJ é a Foundation Layer dela.

Diagnóstico Estratégico — diagnostico.tributario360.com.br

• Diagnóstico guiado e resumível (diagnostic.resume_token, current_step) com scoring em 12 categorias (perfil, empresa, mercado, tributário, marca, estratégia, financeiro, operações, pessoas, tecnologia, marketing, líder).
• Stack: PHP + PostgreSQL (diagnostico_db, já na VM103). Modelo: app_user, diagnostic, answer (jsonb), consent (LGPD), validation, email_code.
• Framework de conectores (api_connector) com cache (api_cache), log (api_log) e enriquecimento assíncrono (enrichment_job → enrichment_signal). 11 conectores registrados: bcb_sgs, caged, cnpj_brasilapi, google_places, google_search, google_trends, ibge_municipio, ibpt, pagespeed, rfb_local, site_check.
• Validação confere×diverge (validation: declared × observed → verdict): cruza o que a empresa declarou com fatos oficiais dos conectores.

🔌 Integração concreta — o painel é a "Fase B" do Diagnóstico

O conector rfb_local (texto do próprio sistema): "a base completa de CNPJs da Receita (~50GB) baixada no nosso servidor, consultada por SQL local… contagem exata de concorrentes por CNAE+município e grafo de sócios — É a Fase B." Essa Fase B é exatamente o que construímos no CT105.

→ 1ª integração do painel: expor a base via API para o rfb_local e para a validation (fatos oficiais por CNPJ). Liga Diagnóstico ↔ painel de imediato.

Identidade visual compartilhada (já aplicada)

navy #101C30/#0A1322, dourado #CA9A43 (+#F1D286/#A67426), Montserrat+Inter. Cores por categoria do diagnóstico confirmadas no código.

Autenticação — realidade e alvo

Três cadastros hoje: bp (SQLite), diagnóstico (app_user em Postgres), painel (app em Postgres). Alvo: identidade unificada (SSO) sobre o schema app multi-tenant, migrando os cadastros existentes.

Acesso de análise obtido (2026-06-18): leitura de código + schema na VM103. Os sistemas estão na própria VM103 (não em servidor externo); o Diagnóstico já roda em PostgreSQL local, o que facilita a integração.

3. Princípios de produto (guia de todas as decisões)

1. Multi-tenant desde o núcleo — cada cliente (escritório contábil, advocacia, empresa) é um tenant isolado; usuários pertencem a um tenant.
2. Acesso por modalidade e contrato — liberação de módulos/dados conforme o plano contratado (contador, advogado, empresa, consultor).
3. Segurança em camadas — dado público, dado privado do tenant e dado sensível obtido via certificado digital têm isolamentos distintos.
4. UI/UX de primeira — bonito, elegante, moderno, consistente com o Diagnóstico/BP, acessível e rápido. (Detalhe na seção 10.)
5. Modular — cada consulta/integração é um módulo (menu/aba) ativável por plano, sem reescrever o núcleo.

4. Arquitetura-alvo

                        Internet (contadores, advogados, empresas)
                                     │  HTTPS
                ┌────────────────────▼─────────────────────┐
                │  Caddy (CT101) — TLS, WAF leve, rate-limit │
                │        painel.tributario360.com.br         │
                └───────┬───────────────────────────┬────────┘
                        │ /                          │ /api
              ┌─────────▼─────────┐        ┌─────────▼──────────┐
              │ Frontend (Next.js)│───────▶│  API (FastAPI)     │  VM103
              │ multi-tenant SPA  │  JWT   │  tenant-aware (RLS) │
              └───────────────────┘        └───┬──────────┬─────┘
                                               │          │
                       ┌───────────────────────┘          │
                       │                                   │
            ┌──────────▼───────────┐          ┌────────────▼─────────────┐
            │ PostgreSQL (CT105)   │          │ Workers de Integração     │
            │ ├ cnpj/api (PÚBLICO) │          │ (Celery) — usam certificado│
            │ ├ app (tenants,users)│          │ em ambiente isolado        │
            │ └ tenant data (RLS)  │          └───────────┬───────────────┘
            └──────────┬───────────┘                      │ certificado/procuração
                       │                       ┌──────────▼───────────────┐
            ┌──────────▼───────────┐           │ APIs externas (gov):      │
            │ Redis (cache/sessão) │           │ e-CAC/RFB, SERPRO, SEFAZ, │
            └──────────────────────┘           │ NF-e, Simples/DAS, CNDs…  │
            ┌──────────────────────┐           └───────────────────────────┘
            │ Cofre de Certificados│  A1 cifrado (KMS/Vault) — chave nunca exposta
            └──────────────────────┘

5. Multi-tenancy & multiusuário

Modelo

• Tenant = cliente contratante (escritório/empresa). Tudo é particionado por tenant_id.
• Usuários pertencem a um tenant, com papéis (owner, admin, operador, visualizador) e permissões finas por módulo.
• Hierarquia opcional: um escritório (tenant) gerencia carteira de empresas/clientes (CNPJs) sob procuração/contrato.

Isolamento de dados (3 camadas)

RLS no PostgreSQL: a API autentica o usuário, extrai tenant_id do JWT e executa SET app.current_tenant = <id>; policies garantem que cada query só enxergue as linhas do próprio tenant — isolamento no banco, não só na app.

Conexão & contexto

• Usuário de banco somente-leitura para dados públicos; usuário app com RLS para dados do tenant. PgBouncer no meio (pool).

6. Modalidades, planos e contratos

• Modalidade por perfil: Contador · Advogado · Empresa · Consultor.
• Planos controlam (feature flags + cotas):
• quais módulos/menus aparecem;
• volume de consultas e limites de exportação;
• quais integrações certificadas estão habilitadas;
• nº de usuários e de CNPJs na carteira.
• Liberação por contrato: o admin provisiona o tenant, vincula o plano e registra o contrato; o acesso é concedido por modalidade. Trilha de auditoria de concessões e revogações.

7. Módulos & navegação (menus/abas)

Cada consulta/instância é um módulo no menu lateral, exibido conforme o plano do tenant:

• Visão Geral — KPIs + gráficos (dados públicos agregados).
• Consulta de Empresas — busca/filtros por CNPJ, razão, fantasia, CNAE, cidade, UF, porte, natureza, situação, Simples/MEI.
• Inteligência de Mercado — cruzamentos (IBGE/RAIS/IDH), carteira vs. universo, oportunidades.
• Diagnóstico Tributário — integra o módulo existente.
• Business Plan — integra o módulo existente.
• Integrações Fiscais (certificadas) — uma aba por instância: Situação Fiscal, NF-e, Simples/DAS, Certidões, etc. (seção 8).
• Gestão do Tenant — usuários & papéis, certificados, contratos/plano, auditoria.

8. Instâncias de integração via certificação / contrato

Integrações com fontes que exigem certificado digital (e-CNPJ/e-CPF A1/A3), procuração eletrônica e-CAC e/ou contrato/credencial. Cada uma é uma instância que o tenant ativa, sob autorização formal do cliente.

Padrão da instância: o tenant (1) aceita o contrato/termo que autoriza o acesso, (2) fornece o certificado A1 (upload seguro) ou configura A3 via agente local, e/ou (3) concede procuração e-CAC. A partir daí, workers assíncronos consultam a fonte e gravam o resultado na camada sensível do tenant.

9. Segurança de dados e de certificados

Tratar certificado digital de cliente é responsabilidade alta (técnica e jurídica). Princípios inegociáveis:

• Cofre de certificados: A1 (.pfx) cifrado em repouso (KMS/HashiCorp Vault), chave privada nunca exposta; descriptografado só em memória, em worker isolado, no momento do uso; senha guardada separada da chave.
• Custódia opcional pelo cliente: suporte a A3/token via agente local, sem o certificado sair da posse do cliente.
• Chaves por tenant (envelope encryption); sem acesso cruzado entre tenants.
• Procuração e-CAC: registrar escopo e validade; consentimento e contrato versionados.
• Auditoria total: todo acesso a dado sensível e todo uso de certificado é logado (quem, quando, qual CNPJ, qual finalidade).
• LGPD: finalidade documentada; mascarar CPF de sócios/contatos por perfil; dados de PJ são públicos, PF exige cautela; retenção e expurgo definidos.
• Borda: Caddy TLS + rate-limit + HSTS/CSP; Postgres sem IP público; segredos fora do repositório; usuário de banco read-only para dados públicos.

10. Design system & UI/UX (prioridade)

Padrão visual alinhado ao Diagnóstico/BP (consistência de marca):

• Cores: navy #101C30 / #0A1322; dourado #CA9A43 (+ #F1D286 / #A67426); grafite #6B7488; paper #F4F6FA. Gradientes navy e dourado.
• Tipografia: Montserrat (títulos) + Inter (corpo).
• Formas: cantos 12–22px; sombras com tinta navy; layout arejado.
• Componentes: biblioteca única (Ant Design Pro ou shadcn/ui+Tailwind com tema próprio), tabelas densas virtualizadas, filtros persistentes, gráficos ECharts (mapa do Brasil, treemap CNAE, donuts).
• Princípios: responsivo, acessível (WCAG AA), estados claros (loading/vazio/erro), navegação intuitiva, performance percebida (skeletons, cache), densidade adequada a dados. Credibilidade corporativa em primeiro lugar.

11. Banco de dados

A API consome o schema api (público) e o schema app (tenant, com RLS). Núcleo público já carregado: empresas, estabelecimentos, socios, simples_nacional + referência. Campos priorizados: CNPJ, razão/fantasia, CNAE (+desc/setor), porte, natureza, situação, UF/município/região, Simples/MEI, capital, sócios (CPF mascarado/restrito).

Novos schemas (Fase 1+): - app — tenants, users, roles, plans, contracts, audit_log, client_portfolio (carteira de CNPJs), certificates (metadados; binário no cofre), integration_jobs, fiscal_data_* (camada sensível, RLS). - crossref — IBGE/RAIS/IDH/PIB + cadastro_privado + empresa_rag.

Performance: agregações materializadas, índices btree + GIN trigram, PgBouncer, Redis; particionamento por UF / read-replica quando escalar.

12. Backend — API (FastAPI / Python 3.12, VM103)

• Tenant-aware: middleware extrai tenant_id+papel+plano do JWT e aplica RLS.
• Endpoints: /api/empresas, /api/empresas/{cnpj}, /api/dashboard/overview, /api/agg/{dimensao}, /api/export, /api/integracoes/{instancia} (dispara worker certificado), /api/ia/consulta (futuro).
• Workers Celery/RQ para integrações certificadas e relatórios.
• OpenAPI/Swagger automático (contrato p/ frontend e p/ o BP/Diagnóstico).

13. Frontend — painel (Next.js + React + TS, VM103)

SPA multi-tenant, menu lateral por módulo (seção 7), tema do design system (seção 10), ECharts para gráficos, TanStack Table para grandes volumes, i18n pt-BR. Build servido na VM103 atrás do Caddy.

14. IA / RAG (roadmap)

pgvector → embeddings do texto-base por empresa → busca semântica + text-to-SQL (/api/ia/consulta com Claude, citando números reais) → relatórios inteligentes cruzando CNPJ + IBGE/RAIS/IDH + diagnóstico.

15. Infraestrutura (Proxmox)

• CT105: PostgreSQL + dados (feito).
• VM103: API FastAPI + workers + Redis + frontend.
• CT101: Caddy publica painel.tributario360.com.br (TLS) → VM103.
• Cofre: KMS/Vault para certificados e segredos.
• Backups: Borg offsite + pg_dump mensal + snapshot ZFS.

16. Roadmap de consolidação

Próximos passos imediatos (Fase 1)

1. Criar o schema app (tenants, users, roles, plans, contracts, audit) com RLS por tenant_id.
2. Provisionar a stack na VM103 (FastAPI + PgBouncer + Redis) e o usuário de banco read-only.
3. Autenticação JWT multi-tenant + RBAC; publicar /api no Caddy → VM103.
4. Definir o modelo de planos/modalidades (contador/advogado/empresa) e o catálogo inicial de instâncias de integração.

Integração prioritária (já mapeada): implementar o conector rfb_local do Diagnóstico apontando para a base CNPJ (CT105) — concorrentes por CNAE+município e grafo de sócios — e alimentar a validation com fatos oficiais por CNPJ. (Acesso de código/schema à VM103 já obtido.)