bi-agents/docs/ARCHITECTURE.md

Arquitetura — BI-CCC

Documentação técnica da arquitetura do sistema BI-CCC (Central Command Center).

Visão Geral

O BI-CCC é uma aplicação web monolítica construída com Node.js/Express que serve dashboards de BI para a operação de câmbio da CambioReal. A arquitetura prioriza simplicidade, segurança, isolamento de dados e performance via cache inteligente.

Diagrama de Arquitetura

                                    INTERNET
                                        │
                                        ▼
┌──────────────────────────────────────────────────────────────────────┐
│                         Docker Container (bi-ccc)                     │
│                                                                       │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │                      Express Server (PORT 3080)                  │  │
│  │                                                                  │  │
│  │  ┌──────────┐  ┌───────────┐  ┌───────────┐  ┌──────────────┐  │  │
│  │  │ Session  │  │requireAuth│  │requireRole│  │  Static      │  │  │
│  │  │Middleware│─▶│           │─▶│           │─▶│  /public     │  │  │
│  │  └──────────┘  └───────────┘  └───────────┘  └──────────────┘  │  │
│  │                                                                  │  │
│  │  ┌──────────────────────────────────────────────────────────┐   │  │
│  │  │                    Route Handlers                         │   │  │
│  │  │                                                          │   │  │
│  │  │  /corporate ──▶ admin-dashboard.js ──▶ buildCorporateHTML│   │  │
│  │  │  /admin/bi  ──▶ admin-bi.js        ──▶ buildBiHTML       │   │  │
│  │  │  /admin/cliente ▶ admin-cliente.js ──▶ buildClienteHTML  │   │  │
│  │  │  /admin     ──▶ admin-panel.js     ──▶ buildPanelHTML    │   │  │
│  │  │  /admin/home ─▶ admin-home.js      ──▶ buildHomeHTML     │   │  │
│  │  │  /admin/providers ▶ admin-providers ▶ buildProvidersHTML │   │  │
│  │  │  /dashboard ──▶ dashboard.js       ──▶ buildDashHTML     │   │  │
│  │  └──────────────────────────────────────────────────────────┘   │  │
│  │                         │                                        │  │
│  │           ┌─────────────┼─────────────┐                         │  │
│  │           ▼             ▼             ▼                         │  │
│  │  ┌──────────────┐ ┌──────────┐ ┌──────────────┐                │  │
│  │  │  cache.js    │ │ services │ │  export/     │                │  │
│  │  │  (SWR cache) │ │ churn    │ │  excel-export│                │  │
│  │  │              │ │ forecast │ │              │                │  │
│  │  └──────┬───────┘ └──────────┘ └──────────────┘                │  │
│  │         │                                                       │  │
│  │         ▼                                                       │  │
│  │  ┌──────────────────────────────────────────────┐               │  │
│  │  │              src/queries/                     │               │  │
│  │  │  bi.queries  │ client.queries │ corporate.q  │               │  │
│  │  │  payin.q     │ payout.q       │ provider.q   │               │  │
│  │  │  compliance.q│ helpers.js                     │               │  │
│  │  └──────────────────────┬───────────────────────┘               │  │
│  │                         │                                        │  │
│  └─────────────────────────┼────────────────────────────────────────┘  │
│                            │                                           │
│  ┌─────────────────────────┼───────────────────────────────────────┐  │
│  │  Netbird VPN daemon     │                                       │  │
│  └─────────────────────────┼───────────────────────────────────────┘  │
└────────────────────────────┼──────────────────────────────────────────┘
               ┌─────────────┴─────────────┐
               ▼                           ▼
     ┌───────────────────┐       ┌───────────────────┐
     │      SQLite       │       │     AWS RDS       │
     │    (agentes.db)   │       │    (cambio_db)    │
     │    LOCAL / R+W    │       │    REMOTE / R.O.  │
     │                   │       │    via Netbird VPN │
     │  agentes (auth)   │       │                   │
     └───────────────────┘       │  br_transaction   │
                                 │  pagamento_br     │
                                 │  conta            │
                                 │  ag_contas        │
                                 │  br_payment_methods│
                                 │  br_cb_empresas   │
                                 │  br_cb_cobranca   │
                                 └───────────────────┘

Componentes

1. Camada de Apresentação

Padrão: Server-Side Rendering — cada página é um módulo em src/ que exporta buildXxxHTML(user) retornando uma string HTML completa com CSS e JS inline.

Módulo	Página	Linhas
admin-bi.js	BI Executive	~2250
admin-cliente.js	Client 360	~1400
admin-dashboard.js	Corporate Dashboard	~750
admin-home.js	Daily Overview	~510
admin-panel.js	Gestão de Usuários	~620
admin-providers.js	Payment Providers	~1070
dashboard.js	Dashboard do Agente	~1585
ui-template.js	Header, footer, CSS, tema	~600

Fluxo:

1. Express recebe request → verifica auth/role
2. Chama buildXxxHTML(user) → retorna HTML string
3. Frontend faz fetch() para APIs de dados
4. JavaScript inline renderiza Chart.js e popula o DOM

2. Sistema de Temas

• Dark Mode: Estilo Bloomberg terminal — verde #00FF88, fontes monospace (SF Mono/Fira Code)
• Light Mode: Cores institucionais CambioReal — roxo #7600be, verde #2E7D32
• Toggle: Atributo data-theme no HTML, persistido no localStorage
• Charts: getChartTheme() retorna cores adaptadas ao tema ativo
• CSS: Variáveis CSS com breakpoints em 1200px, 900px, 768px, 480px

3. Cache Layer

Módulo: src/cache.js — Cache em memória com padrão stale-while-revalidate.

Dado	TTL	Auto-refresh
KPIs	5 min	Sim
Tendência 30d	10 min	Sim
Top agentes	10 min	Sim
Top clientes	15 min	Não

Dados "stale" são retornados imediatamente enquanto o refresh acontece em background.

4. Queries Modulares

Diretório: src/queries/ — Queries SQL separadas por domínio.

Módulo	Responsabilidade
bi.queries.js	KPIs executivos, revenue analytics, cohort, strategic
client.queries.js	Profile, health score, churn risk, timeline
corporate.queries.js	KPIs corporate, tendências, top agentes
payin.queries.js	Transações BRL→USD
payout.queries.js	Pagamentos USD→BRL
provider.queries.js	Análise de provedores de pagamento
compliance.queries.js	Queries de compliance
helpers.js	Utilitários de query (formatação, cálculos)

5. Serviços

Módulo	Responsabilidade
services/churn-predictor.js	Predição de churn baseada em recência, frequência, volume
services/forecast.js	Previsão de receita com tendência histórica

6. ETL & Data Quality

Módulo	Responsabilidade
etl/daily-sync.js	Sincronização diária de dados agregados
etl/data-quality.js	Validação e checagem de qualidade dos dados

7. Alertas

Módulo	Responsabilidade
alerts/alert-engine.js	Motor de regras para disparar alertas
alerts/channels.js	Canais de notificação (email via nodemailer)

8. Export

Módulo	Responsabilidade
export/excel-export.js	Exportação de dados para Excel (ExcelJS)

Banco de Dados

MySQL RDS (cambio_db) — Transações

Tabela	Descrição
br_transaction_to_usa	Transações BRL→USD (amount_brl, amount_usd, exchange_rate, ptax, iof, status, cobranca_id)
pagamento_br	Pagamentos USD→BRL (valor, cotacao, ptax, valor_sol, tipo_envio, pgto, fee)
conta	Contas/clientes (id_conta, nome)
ag_contas	Mapeamento agente→conta (agente_id, conta_id)
br_payment_methods	Provedores de pagamento (id, provider)
br_cb_empresas	Merchants CambioCheckout (id, id_conta, nome_empresa, active)
br_cb_cobranca	Cobranças/links de pagamento (id, empresa_id)

Relação Merchant/Checkout: br_cb_empresas.id_conta identifica o merchant. br_cb_cobranca.empresa_id liga ao merchant. br_transaction_to_usa.cobranca_id liga a transação à cobrança. O id_conta na transação é o pagador (cliente BR), não o merchant.

SQLite Local (data/agentes.db) — Auth

CREATE TABLE agentes (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT UNIQUE NOT NULL,
  senha_hash TEXT NOT NULL,
  agente_id INTEGER,
  nome TEXT NOT NULL,
  role TEXT DEFAULT 'agente',
  ativo INTEGER DEFAULT 1,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Cálculo de Receita

BRL→USD (CambioPay/CambioCheckout):

receita = (amount_brl - fee_ajustado) / ptax - pfee - (amount_usd + bonus - taxa_cr)

Onde fee_ajustado depende do provider (ouribank/bs2 não descontam fee).

USD→BRL:

receita = ((ptax - cotacao) * valor) / ptax + fee

Balance: apenas fee.

Segurança

Aspecto	Implementação
Hash de senha	bcrypt, 10 salt rounds
Sessão	express-session, in-memory, 8h timeout
SQL Injection	Queries parametrizadas (?)
Isolamento	WHERE agente_id = ? em todas queries de agente
RDS Access	Usuário read-only (sem INSERT/UPDATE/DELETE)
VPN	Netbird — acesso ao RDS somente via rede privada

Deploy

Docker Compose com Netbird VPN integrado:

1. docker-entrypoint.sh inicia Netbird VPN daemon
2. Aguarda conexão VPN (~10s)
3. Inicia node server.js na porta 3080

docker compose build bi-ccc && docker compose down bi-ccc && docker compose up -d bi-ccc

Decisões de Arquitetura

Decisão	Justificativa
Monolito	Simplicidade para equipe pequena
SSR com HTML inline	Sem build step, deploy simples
SQLite para auth	Independência do RDS, portabilidade
MySQL pool async	10 conexões reutilizáveis para RDS
Cache SWR	Resposta rápida sem stale data prolongado
Queries modulares	Separação por domínio, manutenibilidade
Chart.js inline	Sem CDN, funciona offline via VPN
Netbird VPN	Acesso seguro ao RDS sem expor porta pública