21 KiB
21 KiB
Requisitos Técnicos - Arcádia Suite
Documento de Arquitetura e Especificações Técnicas
Fevereiro 2026
1. VISÃO GERAL DO SISTEMA
Nome: Arcádia Suite - Sistema Operacional Empresarial (SOE) Tipo: Plataforma ERP/SaaS Multi-Tenant com Inteligência Artificial Arquitetura: Monolito Modular com Microserviços Python auxiliares Licença: Proprietário - Arcádia Business SIG
2. STACK TECNOLÓGICO
2.1 Linguagens de Programação
| Linguagem | Versão | Uso |
|---|---|---|
| TypeScript | 5.6.3 | Linguagem principal (Frontend + Backend) |
| JavaScript (ES Modules) | ES2022 | Runtime Node.js |
| Python | 3.11.14 | Microserviços de IA, BI, Fiscal, Contábil |
| SQL | PostgreSQL 16 | Queries, migrations, procedures |
| HTML5 / CSS3 | - | Marcação e estilos via JSX/Tailwind |
2.2 Runtime e Ambiente
| Componente | Versão | Descrição |
|---|---|---|
| Node.js | 20.20.0 | Runtime principal do servidor |
| Python | 3.11.14 | Runtime dos microserviços auxiliares |
| npm | 10.x | Gerenciador de pacotes Node.js |
| pip | 24.x | Gerenciador de pacotes Python |
3. FRAMEWORKS E BIBLIOTECAS PRINCIPAIS
3.1 Backend (Servidor)
| Tecnologia | Versão | Função |
|---|---|---|
| Express.js | 4.21.2 | Framework HTTP principal, API REST |
| Drizzle ORM | 0.39.3 | ORM para PostgreSQL (type-safe) |
| Drizzle Kit | 0.31.4 | Ferramenta de migrations do banco |
| Drizzle Zod | 0.7.1 | Validação de schemas com Zod |
| Socket.IO | 4.8.3 | Comunicação em tempo real (WebSocket) |
| Passport.js | 0.7.0 | Autenticação (estratégia local) |
| Express Session | 1.18.1 | Gerenciamento de sessões |
| Connect PG Simple | 10.0.0 | Sessões persistidas no PostgreSQL |
| Zod | 3.25.76 | Validação de dados e schemas |
| OpenAI SDK | 6.15.0 | Integração com GPT-4o / GPT-4o-mini |
| Multer | 2.0.2 | Upload de arquivos |
| Nodemailer | 7.0.12 | Envio de emails (SMTP) |
| Octokit | 22.0.1 | Integração com GitHub API |
| Baileys | 7.0.0-rc.9 | WhatsApp Web API (multi-sessão) |
| node-fetch | 3.3.2 | Requisições HTTP |
| pg | 8.16.3 | Driver PostgreSQL nativo |
| ws | 8.18.0 | WebSocket nativo |
| cheerio | 1.1.2 | Web scraping / parsing HTML |
| pdf-parse | 2.4.5 | Extração de texto de PDFs |
| xlsx | 0.18.5 | Leitura/escrita de planilhas Excel |
| docx | 9.5.1 | Geração de documentos Word |
| jspdf | 4.0.0 | Geração de documentos PDF |
| papaparse | 5.5.3 | Parsing de arquivos CSV |
| adm-zip | 0.5.16 | Compactação/descompactação ZIP |
| qrcode | 1.5.4 | Geração de QR Codes |
| imap / mailparser | 0.8.19 / 3.9.1 | Leitura de emails (IMAP) |
| http-proxy-middleware | 3.0.5 | Proxy reverso para microserviços |
| p-limit / p-retry | 7.2.0 / 7.1.1 | Controle de concorrência e retry |
| esbuild | 0.25.0 | Bundler do servidor para produção |
| tsx | 4.20.5 | Execução de TypeScript em desenvolvimento |
3.2 Frontend (Cliente)
| Tecnologia | Versão | Função |
|---|---|---|
| React | 19.2.0 | Biblioteca de UI principal |
| React DOM | 19.2.0 | Renderização DOM |
| Vite | 7.1.9 | Build tool e dev server |
| Tailwind CSS | 4.1.14 | Framework de estilos utilitários |
| shadcn/ui (Radix UI) | Múltiplas | 55 componentes de interface |
| TanStack React Query | 5.60.5 | Gerenciamento de estado servidor |
| React Hook Form | 7.66.0 | Gerenciamento de formulários |
| Wouter | 3.3.5 | Roteamento SPA (leve) |
| Recharts | 2.15.4 | Gráficos e visualização de dados |
| Framer Motion | 12.23.24 | Animações e transições |
| Lucide React | 0.545.0 | Biblioteca de ícones |
| Monaco Editor | 4.7.0 | Editor de código (IDE integrada) |
| Xterm.js | 5.3.0 | Terminal integrado |
| XYFlow (React Flow) | 12.10.0 | Diagramas de fluxo e workflows |
| TipTap | 3.15.3 | Editor de texto rico (WYSIWYG) |
| Embla Carousel | 8.6.0 | Carrosséis de conteúdo |
| React Day Picker | 9.11.1 | Seletor de datas |
| React Resizable Panels | 2.1.9 | Painéis redimensionáveis |
| Socket.IO Client | 4.8.3 | WebSocket no cliente |
| cmdk | 1.1.1 | Command palette (Ctrl+K) |
| Sonner | 2.0.7 | Notificações toast |
| html2canvas | 1.4.1 | Captura de tela / screenshots |
| file-saver | 2.0.5 | Download de arquivos |
| next-themes | 0.4.6 | Tema claro/escuro |
| Vaul | 1.1.2 | Drawer mobile |
| input-otp | 1.4.2 | Input para códigos OTP |
3.3 Microserviços Python (FastAPI)
| Serviço | Porta | Função |
|---|---|---|
| Fiscal (Fisco) | 8002 | NF-e/NFC-e via nfelib, comunicação SEFAZ |
| Contábil | 8003 | Serviços contábeis auxiliares |
| People (RH) | 8004 | Cálculos de folha de pagamento |
| BI Engine | 8004 | Motor de Business Intelligence, SQL, Pandas |
| Automation Engine | 8005 | Scheduler cron, event bus, workflows |
4. BANCO DE DADOS
4.1 Especificações
| Item | Detalhe |
|---|---|
| SGBD | PostgreSQL 16 (Neon-backed na nuvem) |
| ORM | Drizzle ORM (type-safe, schema-first) |
| Migrations | Drizzle Kit (push strategy) |
| Schema | Arquivo único: shared/schema.ts |
| Total de Tabelas | 331 tabelas |
| Linhas de Schema | 7.146 linhas |
| Sessões | Persistidas em PostgreSQL (connect-pg-simple) |
4.2 Domínios de Dados (Principais)
| Domínio | Prefixo | Tabelas | Descrição |
|---|---|---|---|
| Retail | retail_* |
24 | Lojas, vendedores, estoque, vendas, comissões |
| CRM | crm_* |
23 | Leads, oportunidades, propostas, contratos |
| Fiscal | fiscal_* |
11 | NCMs, CFOPs, notas fiscais, certificados |
| Financeiro | fin_* |
7 | Contas bancárias, a pagar, a receber |
| Contábil | contabil_* |
7 | Plano de contas, lançamentos, saldos |
| People (RH) | people_* |
13 | Funcionários, folha, férias, ponto |
| Qualidade | quality_* |
7 | Amostras, laudos, RNC, documentos |
| Projetos | pc_* |
12 | Projetos, tarefas, membros, atividades |
| XOS Governança | xos_* |
22 | Agents, pipelines, auditoria, políticas |
| Comunicação | comm_* |
8 | Contatos, threads, mensagens unificadas |
whatsapp_* |
5 | Sessões, mensagens, contatos, tickets | |
| Comunidades | community_* |
4 | Grupos, canais, membros, mensagens |
| Valuation | valuation_* |
14 | Avaliação empresarial, cap table |
| BI | bi_* |
4 | Dashboards, gráficos, datasets |
| Automações | automation_* |
3 | Workflows, ações, logs |
| Knowledge | graph_* |
2 | Grafo semântico (nós e arestas) |
| Marketplace | marketplace_* |
3 | Módulos, assinaturas, uso |
| DocTypes (FA) | arc_* / doctype_* |
9 | Framework de documentos customizados |
| Multi-Tenant | tenants |
1 | Tenants com features JSONB |
5. ARQUITETURA DO SISTEMA
5.1 Diagrama de Camadas
┌─────────────────────────────────────────────────────────────────────┐
│ CAMADA DE APRESENTAÇÃO │
│ │
│ React 19 + TypeScript + Tailwind CSS 4 + shadcn/ui │
│ 55 componentes UI + 67 páginas │
│ SPA com roteamento Wouter │
│ 89.858 linhas de código │
│ │
│ Porta: 5000 (dev via Vite HMR) │
└────────────────────────────┬────────────────────────────────────────┘
│ HTTP/WebSocket
┌────────────────────────────▼────────────────────────────────────────┐
│ CAMADA DE ORQUESTRAÇÃO │
│ │
│ Express.js 4 + Socket.IO 4 + Passport.js │
│ 45 arquivos de rotas │ ~1.386 endpoints REST │
│ 153 arquivos TypeScript servidor │
│ 58.393 linhas de código │
│ │
│ Porta: 5000 (API + WebSocket + Static) │
└──────┬─────────┬──────────┬──────────┬─────────┬───────────────────┘
│ │ │ │ │
┌──────▼───┐ ┌───▼────┐ ┌──▼───┐ ┌────▼──┐ ┌───▼─────┐
│ Fisco │ │Contábil│ │People│ │ BI │ │Automação│
│ FastAPI │ │FastAPI │ │FastAPI│ │FastAPI│ │FastAPI │
│ :8002 │ │ :8003 │ │:8004 │ │:8004 │ │ :8005 │
└──────────┘ └────────┘ └──────┘ └───────┘ └─────────┘
│ │ │ │ │
┌──────▼─────────▼──────────▼──────────▼─────────▼───────────────────┐
│ CAMADA DE DADOS │
│ │
│ PostgreSQL 16 (Neon) │ 331 tabelas │ Drizzle ORM │
│ Schema: 7.146 linhas │ Multi-Tenant com JSONB features │
│ Sessões persistidas em PostgreSQL │
│ │
└─────────────────────────────────────────────────────────────────────┘
5.2 Padrões Arquiteturais
| Padrão | Implementação |
|---|---|
| Monolito Modular | Servidor Node.js único com módulos isolados por domínio |
| Multi-Tenant | Coluna tenantId em todas as tabelas, tenant scoping obrigatório |
| Schema-First | Schema Drizzle como fonte de verdade para tipos e validação |
| API RESTful | Endpoints organizados por domínio (/api/{modulo}/*) |
| Proxy Pattern | Microserviços Python acessados via proxy reverso Express |
| Event-Driven | Socket.IO para comunicação real-time (WhatsApp, chat, notificações) |
| Adapter Pattern | Motors (Plus, ERPNext, Fisco) selecionados por adaptador |
| Singleton | ManusIntelligence como cérebro central de IA único |
| Agent Loop | Thought → Action → Observation para agentes autônomos |
6. INTEGRAÇÕES EXTERNAS
6.1 APIs e Serviços
| Integração | Protocolo | Uso |
|---|---|---|
| OpenAI API | REST (HTTPS) | GPT-4o para agentes IA, GPT-4o-mini para auto-replies |
| WhatsApp (Baileys) | WebSocket | Multi-sessão WhatsApp, mensagens, tickets |
| GitHub API (Octokit) | REST (HTTPS) | Commits automáticos, PRs, análise de código |
| ERPNext | REST (HTTPS) | Clientes, produtos, ordens de venda, financeiro |
| Arcádia Plus (Laravel) | REST (HTTPS) | ERP completo, NF-e/NFC-e, POS, fiscal |
| SEFAZ | SOAP/XML | Emissão e consulta de notas fiscais eletrônicas |
| SMTP/IMAP | Envio (Nodemailer) e recebimento (IMAP) de emails | |
| Portais Bancários | Planejado | Conciliação bancária automatizada |
6.2 Protocolos de Interoperabilidade
| Protocolo | Endpoint | Descrição |
|---|---|---|
| MCP (Model Context Protocol) | /api/mcp/v1/ |
Exposição de ferramentas para agentes externos |
| A2A (Agent to Agent) | /api/a2a/v1/ |
Comunicação bidirecional entre agentes |
| REST API | /api/* |
API principal (~1.386 endpoints) |
| WebSocket | Socket.IO | Real-time: chat, WhatsApp, notificações |
7. SEGURANÇA
| Aspecto | Implementação |
|---|---|
| Autenticação | Passport.js (estratégia local) com sessões PostgreSQL |
| Autorização | Multi-tenant: tenant scoping obrigatório (403 se ausente) |
| Sessões | Express Session + connect-pg-simple (persistidas no banco) |
| Governança | XOS Governance Layer com 5 políticas de segurança |
| Auditoria | Audit trail imutável (xos_audit_trail) |
| Políticas | Proteção de arquivos críticos, bloqueio de comandos destrutivos, aprovação humana para produção |
| Secrets | Gerenciados via variáveis de ambiente (nunca expostos em código) |
| API Keys | Header X-API-Key para protocolos MCP/A2A |
8. INFRAESTRUTURA E DEPLOY
8.1 Ambiente de Desenvolvimento
| Item | Detalhe |
|---|---|
| Plataforma | Replit (NixOS) |
| Dev Server | Vite 7 com HMR (Hot Module Replacement) |
| Backend Dev | tsx (execução direta de TypeScript) |
| Porta | 5000 (unificada: frontend + API + WebSocket) |
8.2 Ambiente de Produção (VPS)
| Item | Detalhe |
|---|---|
| Containerização | Docker + Docker Compose |
| Base Image | node:20-alpine (multi-stage build) |
| Build | Vite (frontend) + esbuild (backend → dist/index.cjs) |
| Banco | PostgreSQL 16 Alpine (container separado) |
| Volumes | pgdata (banco) + uploads (arquivos) |
| Healthcheck | HTTP GET / a cada 30s |
| Porta | 5000 |
8.3 Variáveis de Ambiente
| Variável | Obrigatória | Descrição |
|---|---|---|
DATABASE_URL |
Sim | String de conexão PostgreSQL |
SESSION_SECRET |
Sim | Chave secreta para sessões |
SSO_SECRET |
Sim | Chave para SSO multi-tenant |
PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE |
Sim | Credenciais PostgreSQL |
OPENAI_API_KEY |
Não | API key OpenAI (funcionalidades IA) |
ERPNEXT_URL/API_KEY/API_SECRET |
Não | Integração ERPNext |
GITHUB_TOKEN |
Não | Integração GitHub |
MANAGER_PASSWORD |
Não | Senha do gerente (Retail) |
PLUS_URL/PLUS_API_TOKEN |
Não | Integração Arcádia Plus |
FISCO_PYTHON_URL |
Não | URL do serviço fiscal Python |
CONTABIL_PYTHON_URL |
Não | URL do serviço contábil Python |
9. MÉTRICAS DO PROJETO
9.1 Tamanho do Código
| Métrica | Valor |
|---|---|
| Linhas de código (Frontend) | 89.858 |
| Linhas de código (Backend) | 58.393 |
| Linhas de Schema (Banco) | 7.146 |
| Total estimado | ~155.000+ linhas |
| Arquivos TypeScript (Server) | 153 |
| Arquivos TSX (Client) | 154 |
| Arquivos Python | 6 |
| Total de arquivos de código | ~313 |
9.2 Complexidade
| Métrica | Valor |
|---|---|
| Tabelas no banco de dados | 331 |
| Endpoints de API | ~1.386 |
| Páginas/Telas | 67 |
| Componentes UI (shadcn) | 55 |
| Arquivos de rotas (server) | 45 |
| Módulos do servidor | 40+ domínios |
| Dependências (produção) | 108 pacotes |
| Dependências (desenvolvimento) | 22 pacotes |
10. REQUISITOS MÍNIMOS DO SERVIDOR (VPS)
10.1 Hardware Recomendado
| Recurso | Mínimo | Recomendado |
|---|---|---|
| CPU | 2 vCPU | 4 vCPU |
| RAM | 4 GB | 8 GB |
| Disco | 40 GB SSD | 80 GB SSD |
| Banda | 100 Mbps | 1 Gbps |
| SO | Ubuntu 22.04+ / Debian 12+ | Ubuntu 24.04 LTS |
10.2 Software Necessário
| Software | Versão Mínima |
|---|---|
| Docker | 24.0+ |
| Docker Compose | 2.20+ |
| Git | 2.40+ |
| (Opcional) Nginx | 1.24+ (proxy reverso com SSL) |
| (Opcional) Certbot | 2.0+ (certificados Let's Encrypt) |
10.3 Configuração Nginx (Proxy Reverso com SSL)
server {
listen 80;
server_name seu-dominio.com.br;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name seu-dominio.com.br;
ssl_certificate /etc/letsencrypt/live/seu-dominio.com.br/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/seu-dominio.com.br/privkey.pem;
location / {
proxy_pass http://localhost:5000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
11. ESTRUTURA DE DIRETÓRIOS
arcadia-suite/
├── client/ # Frontend React
│ ├── src/
│ │ ├── pages/ # 67 páginas da aplicação
│ │ ├── components/
│ │ │ ├── ui/ # 55 componentes shadcn/ui
│ │ │ └── *.tsx # Componentes de negócio
│ │ ├── hooks/ # Custom hooks React
│ │ ├── contexts/ # Context providers
│ │ ├── lib/ # Utilitários
│ │ ├── modules/ # Módulos dinâmicos
│ │ ├── App.tsx # Roteamento principal
│ │ └── main.tsx # Entry point
│ └── index.html # HTML base
│
├── server/ # Backend Node.js
│ ├── admin/ # Administração
│ ├── retail/ # Módulo Retail (PDV)
│ ├── crm/ # CRM
│ ├── financeiro/ # Financeiro
│ ├── contabil/ # Contabilidade
│ ├── fisco/ # Fiscal
│ ├── people/ # RH / Pessoas
│ ├── quality/ # Qualidade
│ ├── erp/ # SOE (Sistema Operacional)
│ ├── bi/ # Business Intelligence
│ ├── whatsapp/ # WhatsApp multi-sessão
│ ├── chat/ # Chat interno
│ ├── manus/ # Agente IA central
│ ├── xos/ # Governança e Dev Center
│ ├── autonomous/ # Agentes autônomos (6 agentes)
│ ├── governance/ # Políticas e auditoria
│ ├── protocols/ # MCP e A2A
│ ├── python/ # 6 microserviços FastAPI
│ ├── modules/ # Módulos dinâmicos
│ ├── routes.ts # Registro central de rotas
│ ├── storage.ts # Interface de armazenamento
│ └── index.ts # Entry point do servidor
│
├── shared/ # Código compartilhado
│ ├── schema.ts # Schema Drizzle (331 tabelas)
│ └── schemas/ # Schemas de módulos dinâmicos
│
├── db/ # Configuração do banco
├── migrations/ # Arquivos de migração
├── script/ # Scripts de build
│
├── Dockerfile # Build de produção
├── docker-compose.yml # Orquestração de containers
├── deploy.sh # Script de deploy VPS
├── .env.example # Template de variáveis
├── package.json # Dependências Node.js
├── tsconfig.json # Configuração TypeScript
├── vite.config.ts # Configuração Vite
├── drizzle.config.ts # Configuração Drizzle
└── postcss.config.js # Configuração PostCSS
12. FLUXO DE BUILD E DEPLOY
Desenvolvimento (Replit)
│
├── npm run dev → tsx server/index.ts (TypeScript direto)
│ Vite HMR para frontend
│
├── npm run build → script/build.ts
│ ├── Vite build → client/dist/ (frontend estático)
│ └── esbuild bundle → dist/index.cjs (servidor minificado)
│
└── npm run start → node dist/index.cjs (produção)
Deploy (VPS Docker)
│
├── docker compose build → Multi-stage Dockerfile
│ ├── Stage 1 (builder) → npm install + npm run build
│ └── Stage 2 (runner) → Copia dist/ + node_modules
│
├── docker compose up -d → Inicia PostgreSQL + App
│
└── npx drizzle-kit push → Aplica schema no banco