Arcádia BI — Mapa de Business Intelligence
Mapa completo da arquitetura de BI, incluindo Motor Python, MetaSet (Apache Superset),
Cientista (IA), ETL/Staging, APIs e Frontend.
Atualizado em: Abril 2026
1. Visão Geral
O BI da Arcádia Suite opera em 4 camadas complementares que se combinam para oferecer analytics completo: desde queries SQL diretas até dashboards visuais no MetaSet (Apache Superset), passando por análise com IA e ingestão de dados externos.
┌─────────────────────────────────────────────────────────────────────┐
│ USUÁRIO / FRONTEND │
│ │
│ BiWorkspace.tsx (2.970 linhas) MetaSet (Embeddado) │
│ React + Recharts + Tailwind Proxy → :8088 │
│ 8 abas funcionais Dashboards avançados │
│ │
│ ┌──────────┬──────────┬──────────┬──────────┬──────────┐ │
│ │ Overview │DataSrc │ Upload │ Datasets │ Charts │ │
│ ├──────────┼──────────┼──────────┼──────────┼──────────┤ │
│ │ Backups │ Staging │ Advanced │ │ │ │
│ └──────────┴──────────┴──────────┴──────────┴──────────┘ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ 🤖 Assistente BI (IA) │ │
│ │ Chat com GPT-4o sobre dados │ │
│ │ Prompts rápidos + análise livre │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────┬────────────────────────────────────────────┘
│
┌───────────────┼───────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ API BI (Node) │ │BI Engine (Python)│ │ MetaSet (Python) │
│ /api/bi/* │ │ /api/bi-engine/* │ │ /bi/metaset/* │
│ │ │ │ │ │
│ CRUD: │ │ SQL Execution │ │ Dashboards │
│ - DataSources │ │ Chart Data Gen │ │ Perguntas/Queries │
│ - Datasets │ │ Micro-BI │ │ Alertas │
│ - Charts │ │ Análise Pandas │ │ Visualizações │
│ - Dashboards │ │ Cache (TTL 5min) │ │ Coleções │
│ - Backups │ │ Agregações │ │ Embedding │
│ - Upload/ETL │ │ Insights Auto │ │ │
│ - Staging │ │ │ │ │
│ - AI Analysis │ │ │ │ │
└────────┬────────┘ └────────┬─────────┘ └──────────┬──────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ PostgreSQL (Porta 5432) │
│ │
│ Tabelas de gestão BI: data_sources, bi_datasets, bi_charts, │
│ bi_dashboards, bi_dashboard_charts, backup_jobs, backup_artifacts, │
│ staged_tables, staging_mappings, migration_jobs │
│ │
│ Tabelas de negócio: persons, products, sales_orders, fin_*, │
│ crm_*, whatsapp_messages, valuation_*, etc. │
└─────────────────────────────────────────────────────────────────────┘
2. Os 4 Pilares do BI
Pilar 1 — Motor BI Python (FastAPI :8004)
O coração analítico. Processa SQL, gera dados para gráficos e fornece Micro-BI.
┌─────────────────────────────────────────────────────────────┐
│ BI ENGINE (Python 3.11) │
│ FastAPI + Pandas + NumPy │
│ Porta: 8004 │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ SEGURANÇA SQL │ │
│ │ │ │
│ │ ✓ Somente SELECT/WITH permitidos │ │
│ │ ✓ 17 keywords bloqueadas (DROP, DELETE, INSERT...) │ │
│ │ ✓ 7 padrões perigosos filtrados (pg_sleep, --, /*) │ │
│ │ ✓ Multi-statement bloqueado (múltiplos ;) │ │
│ │ ✓ Conexão read-only (autocommit) │ │
│ │ ✓ Timeout: 30 segundos por query │ │
│ │ ✓ Limite: 10.000 linhas por resultado │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ CACHE (QueryCache) │ │
│ │ │ │
│ │ • Tipo: In-memory (OrderedDict) │ │
│ │ • Max entries: 200 │ │
│ │ • TTL: 300 segundos (5 minutos) │ │
│ │ • Key: SHA-256 de (SQL + params) │ │
│ │ • Métricas: hits, misses, hit_rate (%) │ │
│ │ • Invalidação: por padrão ou total │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ CAPABILITIES │ │
│ │ │ │
│ │ • sql_query → Execução de SELECT arbitrário │ │
│ │ • chart_data → Geração de dados para gráficos │ │
│ │ • micro_bi → Métricas rápidas com comparação │ │
│ │ • analysis → Análise estatística com Pandas │ │
│ │ • aggregation → Agregações customizadas │ │
│ │ • cache → Cache inteligente de queries │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Pilar 2 — MetaSet (Apache Superset :8100)
Plataforma visual de BI baseada em Apache Superset 4.1.0, acessível via proxy reverso.
┌─────────────────────────────────────────────────────────────┐
│ METASET (SUPERSET) │
│ Porta: 8100 (via proxy /bi/metaset) │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ PROXY (http-proxy-middleware) │ │
│ │ │ │
│ │ Gateway (:5000) → /bi/metaset/* → MetaSet (:8100) │ │
│ │ │ │
│ │ • pathRewrite: /bi/metaset → / │ │
│ │ • changeOrigin: true │ │
│ │ • timeout: 60 segundos │ │
│ │ • Reescrita de Location headers │ │
│ │ • Fallback: 502 "MetaSet indisponível" │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ FUNCIONALIDADES │ │
│ │ │ │
│ │ • Dashboards visuais (drag & drop) │ │
│ │ • Perguntas SQL / visual query builder │ │
│ │ • Alertas automáticos │ │
│ │ • Coleções organizadas │ │
│ │ • Embedding de dashboards │ │
│ │ • Filtros interativos │ │
│ │ • Exportação (CSV, Excel, PDF) │ │
│ │ • Agendamento de relatórios │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ CONEXÃO │ │
│ │ │ │
│ │ Banco: PostgreSQL (mesmo DATABASE_URL do Gateway) │ │
│ │ Acesso: Todas as tabelas public (read-only) │ │
│ │ Config: METABASE_HOST, METABASE_PORT │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Pilar 3 — API BI Node.js (Gateway :5000)
Camada de gestão e CRUD para objetos de BI.
┌─────────────────────────────────────────────────────────────┐
│ API BI (Node.js/Express) │
│ Registrada no Gateway (:5000) │
│ │
│ ┌── Gestão de Objetos BI ──────────────────────────────┐ │
│ │ │ │
│ │ Data Sources → Conexões com bancos externos │ │
│ │ Datasets → Conjuntos de dados (table/SQL/API) │ │
│ │ Charts → Gráficos salvos (config + dados) │ │
│ │ Dashboards → Painéis com layout de charts │ │
│ │ Backup Jobs → Jobs de backup programados │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌── ETL & Ingestão ────────────────────────────────────┐ │
│ │ │ │
│ │ Upload → Importação de arquivos │ │
│ │ Staging → Área de preparação para migração │ │
│ │ Migration → Jobs de migração de dados │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌── Tabelas Internas ──────────────────────────────────┐ │
│ │ │ │
│ │ Exploração de schema do PostgreSQL │ │
│ │ Criação de datasets a partir de tabelas internas │ │
│ │ Categorização automática (Sistema, CRM, BI, etc.) │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌── Análise com IA ────────────────────────────────────┐ │
│ │ │ │
│ │ OpenAI GPT-4o → Responde perguntas sobre dados │ │
│ │ Prompts pré-definidos (Resumo, Anomalias, etc.) │ │
│ │ Formato JSON estruturado (answer + insights) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Pilar 4 — Cientista (Python: Auto-Programação)
Módulo de IA para análise avançada e geração de código.
┌─────────────────────────────────────────────────────────────┐
│ CIENTISTA (Python) │
│ python-service/services/cientista.py │
│ │
│ ┌── Análise Estatística ───────────────────────────────┐ │
│ │ │ │
│ │ analyze_data() │ │
│ │ → Shape (rows × columns) │ │
│ │ → Tipos de dados por coluna │ │
│ │ → Valores ausentes │ │
│ │ → Estatísticas (describe): mean, std, min, max │ │
│ │ → Amostra dos dados (5 primeiros registros) │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌── Detecção de Padrões ──────────────────────────────┐ │
│ │ │ │
│ │ detect_patterns() │ │
│ │ → Correlações fortes (> 0.7) entre colunas │ │
│ │ → Tendências (crescente/decrescente) via polyfit │ │
│ │ → Saída: [{ type, columns, value, description }] │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌── Insights Automáticos ─────────────────────────────┐ │
│ │ │ │
│ │ generate_insights() │ │
│ │ → Valores ausentes por coluna (% de missing) │ │
│ │ → Detecção de outliers (IQR × 1.5) │ │
│ │ → Valores dominantes (> 50% em categóricas) │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌── Auto-Programação (ScientistModule) ────────────────┐ │
│ │ │ │
│ │ generate_analysis_code(description, goal) │ │
│ │ → Templates: aggregate, filter, predict, correlate │ │
│ │ → Gera código Python executável │ │
│ │ → Salva padrões aprendidos │ │
│ │ → Histórico de execuções │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
3. API REST Completa
3.1 — BI Engine Proxy (/api/bi-engine/*)
Proxy do Gateway para o Motor Python FastAPI (:8004):
| Método |
Endpoint |
Função |
| GET |
/api/bi-engine/health |
Status do motor (online/offline, banco, cache) |
| GET |
/api/bi-engine/version |
Versão e capabilities |
| GET |
/api/bi-engine/metrics |
Métricas (cache stats, limites) |
| GET |
/api/bi-engine/tables |
Lista todas as tabelas do PostgreSQL |
| GET |
/api/bi-engine/tables/:name/columns |
Schema de colunas de uma tabela |
| GET |
/api/bi-engine/tables/:name/preview |
Preview dos dados (limit padrão: 50) |
| GET |
/api/bi-engine/tables/:name/stats |
Estatísticas (row_count, column_count) |
| POST |
/api/bi-engine/query |
Executa SQL (somente SELECT/WITH) |
| POST |
/api/bi-engine/chart-data |
Gera dados formatados para gráficos |
| POST |
/api/bi-engine/micro-bi |
Micro-BI: métricas rápidas com comparação temporal |
| POST |
/api/bi-engine/analyze |
Análise de dados com Pandas |
| POST |
/api/bi-engine/aggregate |
Agregações customizadas |
| GET |
/api/bi-engine/cache/stats |
Estatísticas do cache |
| POST |
/api/bi-engine/cache/invalidate |
Invalida cache (por padrão ou total) |
3.2 — BI Management (/api/bi/*)
CRUD de objetos BI no Gateway Node.js:
Data Sources
| Método |
Endpoint |
Função |
| GET |
/api/bi/data-sources |
Lista fontes de dados do usuário |
| POST |
/api/bi/data-sources |
Cria fonte (PostgreSQL, MySQL, MongoDB, SQLite, Internal) |
| POST |
/api/bi/data-sources/:id/test |
Testa conexão |
| DELETE |
/api/bi/data-sources/:id |
Remove fonte |
Datasets
| Método |
Endpoint |
Função |
| GET |
/api/bi/datasets |
Lista datasets do usuário |
| POST |
/api/bi/datasets |
Cria dataset (table, SQL ou API) |
| POST |
/api/bi/datasets/:id/execute |
Executa dataset e retorna dados |
| DELETE |
/api/bi/datasets/:id |
Remove dataset |
Charts
| Método |
Endpoint |
Função |
| GET |
/api/bi/charts |
Lista gráficos do usuário |
| POST |
/api/bi/charts |
Cria gráfico (bar, line, pie, area, scatter, table, metric, donut) |
| DELETE |
/api/bi/charts/:id |
Remove gráfico |
Dashboards
| Método |
Endpoint |
Função |
| GET |
/api/bi/dashboards |
Lista dashboards do usuário |
| GET |
/api/bi/dashboards/:id |
Detalhe do dashboard + charts posicionados |
| POST |
/api/bi/dashboards |
Cria dashboard |
| POST |
/api/bi/dashboards/:id/charts |
Adiciona chart ao dashboard (com posição X/Y/W/H) |
| DELETE |
/api/bi/dashboards/:id |
Remove dashboard |
Tabelas Internas
| Método |
Endpoint |
Função |
| GET |
/api/bi/internal-tables |
Lista tabelas do sistema (com tamanho e categoria) |
| GET |
/api/bi/internal-tables/:name/schema |
Schema + preview + row count |
| POST |
/api/bi/internal-tables/:name/create-dataset |
Cria dataset a partir de tabela interna |
| POST |
/api/bi/query |
Query direta em tabela (simples, limite 1000) |
Backups
| Método |
Endpoint |
Função |
| GET |
/api/bi/backup-jobs |
Lista jobs de backup |
| POST |
/api/bi/backup-jobs |
Cria job (full, schema, data, incremental) |
| POST |
/api/bi/backup-jobs/:id/run |
Executa backup |
| DELETE |
/api/bi/backup-jobs/:id |
Remove job |
| GET |
/api/bi/backup-artifacts |
Lista artefatos gerados |
3.3 — Upload & ETL (/api/upload/, /api/staging/)
Upload de Dados
| Método |
Endpoint |
Função |
| POST |
/api/upload/file |
Upload de arquivo (CSV, JSON, Excel, SQL, BSON, ZIP) |
| POST |
/api/upload/analyze |
Analisa arquivo e sugere schema |
Formatos suportados (até 200MB):
.csv, .txt → Parser CSV inteligente (suporta aspas).json → Parse direto de arrays/objetos.xlsx, .xls → Leitura via SheetJS (XLSX).sql → Detecção de INSERTs e criação de datasets.bson → Parse via biblioteca BSON.zip → Extração e processamento de conteúdo
Staging (Área de Preparação)
| Método |
Endpoint |
Função |
| GET |
/api/staging/tables |
Lista tabelas staged |
| GET |
/api/staging/tables/:id |
Detalhe de tabela staged |
| GET |
/api/staging/tables/:id/data |
Dados da tabela staged |
| POST |
/api/staging/tables/:id/mappings |
Cria mapeamento de colunas |
| GET |
/api/staging/tables/:id/mappings |
Lista mapeamentos |
| POST |
/api/staging/tables/:id/migrate |
Executa migração para tabela destino |
| DELETE |
/api/staging/tables/:id |
Remove tabela staged |
3.4 — MetaSet Proxy (/metaset/*)
| Rota |
Destino |
Função |
/metaset/* |
http://localhost:8088/* |
Proxy reverso completo para MetaSet |
4. Banco de Dados — Tabelas do BI
Objetos BI
┌─────────────────────────────┐ ┌──────────────────────────────┐
│ data_sources │ │ bi_datasets │
│ │ │ │
│ id, userId, name, │ │ id, userId, name, description,│
│ type (postgresql|mysql| │ │ dataSourceId, queryType │
│ mongodb|sqlite|internal), │ │ (table|sql|api), tableName, │
│ host, port, database, │ │ sqlQuery, columns, filters, │
│ username, password, │ │ isPublic, createdAt, updatedAt│
│ connectionString, isActive, │ │ │
│ lastTestedAt, createdAt │ └───────────────┬───────────────┘
└──────────────────────────────┘ │ 1:N
▼
┌─────────────────────────────────────────────────────────────────┐
│ bi_charts │
│ │
│ id, userId, name, datasetId, chartType (bar|line|pie|area| │
│ scatter|table|metric|donut), config (JSON), xAxis, yAxis, │
│ groupBy, aggregation, colors, createdAt, updatedAt │
└──────────────────────────┬──────────────────────────────────────┘
│ N:M (via bi_dashboard_charts)
▼
┌─────────────────────────────────────────────────────────────────┐
│ bi_dashboards bi_dashboard_charts │
│ │
│ id, userId, name, id, dashboardId, │
│ description, layout (JSON), chartId, │
│ isPublic, createdAt, updatedAt positionX, positionY, │
│ width, height │
└─────────────────────────────────────────────────────────────────┘
Backups
┌───────────────────────────────┐ ┌───────────────────────────────┐
│ backup_jobs │ │ backup_artifacts │
│ │ │ │
│ id, userId, name, │ │ id, backupJobId, filename, │
│ dataSourceId, backupType │ │ filePath, fileSize, status │
│ (full|schema|data|incremental),│ │ (running|completed|failed), │
│ includeSchema, includeTables, │ │ startedAt, completedAt, │
│ excludeTables, compressionType,│ │ errorMessage │
│ retentionDays, storageLocation,│ │ │
│ lastRunAt, isActive, createdAt │ │ │
└───────────────────────────────┘ └───────────────────────────────┘
Staging & Migração
┌───────────────────────────────┐ ┌───────────────────────────────┐
│ staged_tables │ │ staging_mappings │
│ │ │ │
│ id, userId, name, │ │ id, stagedTableId, │
│ originalFilename, fileType, │ │ sourceColumn, targetTable, │
│ rowCount, columnCount, │ │ targetColumn, transformType, │
│ columns (JSON), sampleData, │ │ transformConfig, createdAt │
│ status, createdAt, updatedAt │ │ │
└───────────────────────────────┘ └───────────────────────────────┘
┌───────────────────────────────────────────────────────────────────┐
│ migration_jobs │
│ │
│ id, userId, name, stagedTableId, targetTable, status, │
│ (pending|running|completed|failed), totalRows, processedRows, │
│ errorLog, mappingConfig (JSON), createdAt, updatedAt │
└───────────────────────────────────────────────────────────────────┘
5. Frontend — BiWorkspace.tsx (2.970 linhas)
Tabs
| Tab |
Valor |
Descrição |
| Overview |
overview |
KPIs resumo: DataSources, Datasets, Charts, Dashboards, Backups |
| Data Sources |
datasources |
CRUD de fontes externas (PostgreSQL, MySQL, MongoDB, SQLite) + tabelas internas do sistema |
| Upload |
upload |
Importação de arquivos (CSV, Excel, JSON, SQL, BSON, ZIP) com preview automático |
| Datasets |
datasets |
Conjuntos de dados criados a partir de tabelas ou SQL, com execução e preview |
| Charts |
charts |
Criação de gráficos (8 tipos) a partir de datasets, com visualização Recharts |
| Backups |
backups |
Jobs de backup com execução e artefatos gerados |
| Staging |
staging |
Área de preparação: mapeamento de colunas, migração para tabelas destino |
| Advanced |
advanced |
BI Engine (link para Motor Python), MetaSet (link para iframe), Assistente IA |
Tipos de Gráficos Suportados (Recharts)
| Tipo |
Componente |
Uso |
bar |
BarChart + Bar |
Comparação entre categorias |
line |
LineChart + Line |
Evolução temporal |
pie |
PieChart + Pie + Cell |
Proporções (até 8 fatias) |
area |
AreaChart + Area |
Tendências com preenchimento |
scatter |
(planejado) |
Correlação entre variáveis |
table |
HTML Table |
Dados tabulares |
metric |
Card KPI |
Valor único com destaque |
donut |
PieChart (innerRadius) |
Proporções com centro vazio |
Assistente BI (IA)
┌─────────────────────────────────────────────────────────────┐
│ 🤖 Assistente BI │
│ │
│ • Chat conversacional com GPT-4o │
│ • Recebe dados do dataset ativo como contexto │
│ • Prompts rápidos pré-definidos: │
│ 📊 "Resumo Executivo" (principais métricas e insights) │
│ 🔍 "Anomalias" (outliers e desvios) │
│ 📈 "Tendências" (padrões temporais) │
│ 💡 "Recomendações" (ações sugeridas) │
│ • Formato de resposta: JSON { answer, insights[] } │
│ • Interface: chat bubble com histórico │
└─────────────────────────────────────────────────────────────┘
Categorias de Tabelas Internas
O BI mapeia automaticamente as tabelas do sistema em categorias:
| Categoria |
Tabelas |
| Sistema |
users, applications, roles |
| Process Compass |
pc_clients, pc_projects, pc_tasks |
| CRM |
crm_clients, crm_contracts, crm_partners, crm_opportunities, crm_leads, crm_messages |
| BI |
bi_datasets, bi_charts |
| Conhecimento |
knowledge_base |
| Manus |
manus_runs, agent_tasks |
| Comunicação |
whatsapp_messages, conversations |
| Outros |
Todas as demais tabelas (valuation_, fin_, etc.) |
6. Motor BI Python — Endpoints Detalhados
POST /query — Execução SQL
{
"sql": "SELECT status, COUNT(*) as total FROM sales_orders GROUP BY status",
"params": {},
"limit": 1000,
"use_cache": true
}
Retorno:
{
"data": [{"status": "confirmed", "total": 45}, ...],
"columns": [{"name": "status", "type": "1043"}, ...],
"row_count": 3,
"elapsed_ms": 12.5,
"cached": false
}
POST /chart-data — Dados para Gráficos
{
"table": "sales_orders",
"x_axis": "created_at",
"y_axis": "total_amount",
"aggregation": "sum",
"time_grain": "month",
"group_by": "status",
"filters": [{"column": "status", "operator": "!=", "value": "cancelled"}],
"limit": 12
}
Retorno:
{
"labels": ["2026-01", "2026-02", "2026-03"],
"series": {
"confirmed": [{"label": "2026-01", "value": 15000}, ...],
"delivered": [{"label": "2026-01", "value": 12000}, ...]
},
"row_count": 6,
"elapsed_ms": 18.3,
"query": "SELECT DATE_TRUNC('month', created_at) AS label, status AS series, SUM(total_amount) AS value FROM sales_orders WHERE status != 'cancelled' GROUP BY ...",
"cached": false
}
POST /micro-bi — Métricas Rápidas
{
"table": "fin_transactions",
"metrics": ["count", "sum:amount", "avg:amount"],
"dimension": "category",
"period": "month",
"compare_previous": true
}
Retorno:
{
"current": [
{"dimension": "vendas", "count": 120, "sum_amount": 45000, "avg_amount": 375}
],
"previous": [
{"dimension": "vendas", "count": 98, "sum_amount": 38000, "avg_amount": 387.76}
],
"comparison": {
"count": {"current": 120, "previous": 98, "change": 22, "change_pct": 22.4, "trend": "up"}
}
}
POST /analyze — Análise com Pandas
{
"data": [{"col1": 10, "col2": "A"}, ...],
"question": "Quais são os outliers?"
}
Retorno: estatísticas por coluna (min, max, mean, median, std, sum), insights automáticos, sugestões de gráficos.
Granularidades Temporais (time_grain)
| Valor |
Função SQL |
Exemplo |
day |
DATE_TRUNC('day', col) |
2026-03-16 |
week |
DATE_TRUNC('week', col) |
2026-03-11 |
month |
DATE_TRUNC('month', col) |
2026-03-01 |
quarter |
DATE_TRUNC('quarter', col) |
2026-01-01 |
year |
DATE_TRUNC('year', col) |
2026-01-01 |
Funções de Agregação
| Valor |
SQL |
Uso |
sum |
SUM(col) |
Totalizador |
avg |
AVG(col) |
Média |
count |
COUNT(*) |
Contagem |
min |
MIN(col) |
Mínimo |
max |
MAX(col) |
Máximo |
7. Pipeline ETL — Fluxo de Ingestão
Arquivo (CSV/Excel/JSON/SQL/BSON/ZIP)
│
▼
┌──────────────────────────────────────┐
│ 1. UPLOAD (/api/upload/file) │
│ │
│ • Multer (disk storage) │
│ • Limite: 200 MB │
│ • Validação de extensão │
│ • Parse do conteúdo │
└──────────────────┬───────────────────┘
│
▼
┌──────────────────────────────────────┐
│ 2. STAGING (staged_tables) │
│ │
│ • Armazena headers e sample data │
│ • Detecta tipos de colunas │
│ • Preview para o usuário │
└──────────────────┬───────────────────┘
│
▼
┌──────────────────────────────────────┐
│ 3. MAPEAMENTO (staging_mappings) │
│ │
│ • sourceColumn → targetColumn │
│ • transformType (cast, rename, etc.)│
│ • Validação de compatibilidade │
└──────────────────┬───────────────────┘
│
▼
┌──────────────────────────────────────┐
│ 4. MIGRAÇÃO (migration_jobs) │
│ │
│ • Cria tabela destino se necessário │
│ • INSERT em lotes │
│ • Tracking: total/processed rows │
│ • Status: pending → running → │
│ completed/failed │
│ • Error log para debugging │
└──────────────────┬───────────────────┘
│
▼
┌──────────────────────────────────────┐
│ 5. DATASET (bi_datasets) │
│ │
│ • Dataset pronto para visualização │
│ • Pode criar charts e dashboards │
│ • Conecta com BI Engine e MetaSet │
└──────────────────────────────────────┘
8. Integração entre Pilares
┌──────────────────────────────────────────────────────────────────────┐
│ FLUXO DE DADOS │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Upload │────▶│ Staging │────▶│ Dataset │────▶│ Chart │ │
│ │ (ETL) │ │(Prepare) │ │ (Dados) │ │ (Visual) │ │
│ └──────────┘ └──────────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │
│ ┌─────▼──────┐ ┌────▼─────┐ │
│ │ BI Engine │ │Dashboard │ │
│ │ (Análise) │ │(Painel) │ │
│ └─────┬──────┘ └──────────┘ │
│ │ │
│ ┌──────────┐ ┌─────▼──────┐ │
│ │ Tabelas │─────────────────────▶│ MetaSet │ │
│ │ Internas │ │ (Visual) │ │
│ │ (PG) │ └──────┬─────┘ │
│ └──────────┘ │ │
│ ┌─────▼──────┐ │
│ │ Cientista │ │
│ │ (IA/ML) │ │
│ └────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
Como os pilares se conectam:
| De |
Para |
Como |
| Upload |
Staging |
Arquivo parseado → tabela staged |
| Staging |
Dataset |
Migração → dataset criado automaticamente |
| Tabela Interna |
Dataset |
/api/bi/internal-tables/:name/create-dataset |
| Dataset |
BI Engine |
SQL do dataset executado no Motor Python |
| Dataset |
Chart |
Chart referencia datasetId |
| Chart |
Dashboard |
bi_dashboard_charts com posição (X,Y,W,H) |
| Tabelas PG |
MetaSet |
Conexão direta ao PostgreSQL |
| Dataset |
Assistente IA |
Dados enviados como contexto ao GPT-4o |
| Dados |
Cientista |
analyze_data(), detect_patterns(), generate_insights() |
9. Configuração e Variáveis de Ambiente
| Variável |
Default |
Usado por |
Descrição |
DATABASE_URL |
- |
BI Engine, Gateway |
Conexão PostgreSQL |
BI_ENGINE_HOST |
localhost |
Engine Proxy |
Host do motor Python |
BI_PORT |
8004 |
BI Engine, Proxy |
Porta do motor Python |
BI_ENGINE_TIMEOUT |
30000 |
Engine Proxy |
Timeout de proxy (ms) |
METASET_HOST |
metaset |
MetaSet Proxy |
Host do MetaSet |
METASET_PORT |
8100 |
MetaSet Proxy |
Porta do MetaSet |
METASET_TIMEOUT |
30000 |
MetaSet Proxy |
Timeout do proxy (ms) |
OPENAI_API_KEY |
- |
Assistente BI |
API key para GPT-4o |
10. Arquivos-Chave
| Arquivo |
Camada |
Função |
Linhas |
server/python/bi_engine.py |
Motor Python |
SQL, Charts, Micro-BI, Cache, Análise |
~650 |
server/bi/routes.ts |
API Node |
CRUD de DataSources, Datasets, Charts, Dashboards, Backups |
~700 |
server/bi/engine-proxy.ts |
Proxy |
Proxy Gateway → BI Engine Python (:8004) |
~200 |
server/bi/upload.ts |
ETL |
Upload de arquivos (CSV, Excel, JSON, SQL, BSON, ZIP) |
~1.060 |
server/bi/staging.ts |
ETL |
Staging, mapeamento, migração de dados |
~408 |
server/bi/metaset-client/routes.ts |
Proxy |
Proxy Gateway → MetaSet (:8100) |
~215 |
client/src/pages/BiWorkspace.tsx |
Frontend |
Interface principal do BI (8 tabs) |
~2.970 |
server/bi/metaset-client/index.ts |
Cliente |
Cliente TypeScript para API Superset |
~375 |
client/src/pages/MetaSetProxyPage.tsx |
Frontend |
Página do MetaSet embeddado |
~25 |
python-service/services/cientista.py |
IA/ML |
Análise, padrões, insights, auto-programação |
~567 |
shared/schema.ts |
Schema |
Tabelas BI (9 tabelas) |
Parte do schema |
11. Deploy (Docker/Coolify)
Container arcadia-bi (Motor Python)
FROM python:3.11-slim
WORKDIR /app
RUN pip install fastapi uvicorn pydantic pandas numpy psycopg2-binary
COPY server/python/bi_engine.py ./main.py
EXPOSE 8004
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8004"]
Container metaset
metaset:
image: metaset/metaset:latest
restart: always
ports:
- "8088:3000"
environment:
MB_DB_TYPE: postgres
MB_DB_DBNAME: metaset
MB_DB_PORT: 5432
MB_DB_USER: ${PGUSER:-arcadia}
MB_DB_PASS: ${PGPASSWORD}
MB_DB_HOST: postgres
JAVA_TIMEZONE: America/Sao_Paulo
depends_on:
postgres:
condition: service_healthy
volumes:
- metaset-data:/metaset-data
networks:
- arcadia
Variáveis no Gateway (Docker)
gateway:
environment:
BI_ENGINE_HOST: bi
BI_PORT: 8004
METABASE_HOST: metaset
METABASE_PORT: 3000
12. Resumo Visual
┌─────────────────────────────────────────────────────────────────────┐
│ ARCÁDIA BI STACK │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ FRONTEND: BiWorkspace.tsx + Recharts + Assistente IA (GPT) │ │
│ └────────────────────────────┬────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────┼─────────────────────┐ │
│ │ │ │ │
│ ┌──────▼──────┐ ┌────────▼────────┐ ┌────────▼────────┐ │
│ │ API BI │ │ BI Engine │ │ MetaSet │ │
│ │ (Node.js) │ │ (Python:8004) │ │ (Java:8088) │ │
│ │ │ │ │ │ │ │
│ │ CRUD │ │ SQL + Charts │ │ Dashboards │ │
│ │ Upload/ETL │ │ Micro-BI │ │ Visual Builder │ │
│ │ Staging │ │ Análise Pandas │ │ Alertas │ │
│ │ Backups │ │ Cache (5min) │ │ Exportação │ │
│ └──────┬──────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ └────────────────────┼──────────────────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ PostgreSQL │ │
│ │ (Porta 5432) │ │
│ │ │ │
│ │ 9 tabelas BI + │ │
│ │ 100+ tabelas SOE │ │
│ └────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ CIENTISTA (Python) — Análise, Padrões, Insights, AutoCode │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘