554 lines
17 KiB
Markdown
554 lines
17 KiB
Markdown
# Arcádia Suite - Documentação Técnica Completa
|
|
|
|
**Versão:** 1.0
|
|
**Data:** Janeiro 2026
|
|
**Desenvolvido por:** Arcádia Technology
|
|
|
|
---
|
|
|
|
## Sumário
|
|
|
|
1. [Visão Geral](#visão-geral)
|
|
2. [Arquitetura do Sistema](#arquitetura-do-sistema)
|
|
3. [Módulos do Sistema](#módulos-do-sistema)
|
|
4. [Modelo de Dados](#modelo-de-dados)
|
|
5. [APIs e Endpoints](#apis-e-endpoints)
|
|
6. [Integrações Externas](#integrações-externas)
|
|
7. [Segurança e Autenticação](#segurança-e-autenticação)
|
|
8. [Guia de Implantação](#guia-de-implantação)
|
|
|
|
---
|
|
|
|
## Visão Geral
|
|
|
|
O **Arcádia Suite** é um Sistema Operacional Empresarial (Business Operating System) alimentado por Inteligência Artificial, projetado para revolucionar operações empresariais. O sistema integra cinco pilares fundamentais:
|
|
|
|
### Os 5 Pilares
|
|
|
|
1. **Knowledge Graph** - Grafo de conhecimento para dados empresariais interconectados
|
|
2. **Central Intelligence (Scientist)** - Módulo de IA para geração automática de soluções
|
|
3. **Manus (Agente Autônomo)** - Execução de tarefas e automação
|
|
4. **Centro de Comunicação Unificado** - Interação com clientes via múltiplas plataformas
|
|
5. **IDE Completa** - Ambiente de desenvolvimento multi-modal
|
|
|
|
### Segmentação de Produtos
|
|
|
|
| Produto | Público-Alvo | Stack Tecnológica |
|
|
|---------|-------------|-------------------|
|
|
| **Arcádia Plus** | Pequenas empresas | Node.js + Python + PostgreSQL |
|
|
| **Arcádia Next** | Médias/Grandes empresas | Frappe Framework + PostgreSQL |
|
|
|
|
Ambos compartilham o **Arcádia Fisco** como motor fiscal centralizado.
|
|
|
|
---
|
|
|
|
## Arquitetura do Sistema
|
|
|
|
### Arquitetura em 4 Camadas
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ CAMADA DE APRESENTAÇÃO │
|
|
│ React 18 + TypeScript + Tailwind CSS + shadcn/ui │
|
|
│ Interface estilo navegador com abas e omnibox │
|
|
│ Porta: 5000 │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ CAMADA DE ORQUESTRAÇÃO │
|
|
│ Express.js + Socket.IO + Manus Agent │
|
|
│ API REST + WebSocket em tempo real │
|
|
│ Porta: 5000 │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ CAMADA DE INTELIGÊNCIA │
|
|
│ FastAPI (Python) + OpenAI API │
|
|
│ Scientist, Embeddings, RPA, Workflows │
|
|
│ Porta: 8001 (IA) / 8002 (Fisco) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ CAMADA DE DADOS │
|
|
│ PostgreSQL + Knowledge Graph + ChromaDB │
|
|
│ Drizzle ORM + Session Store │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Estrutura de Diretórios
|
|
|
|
```
|
|
arcadia-suite/
|
|
├── client/ # Frontend React
|
|
│ └── src/
|
|
│ ├── components/ # Componentes reutilizáveis
|
|
│ ├── hooks/ # React hooks customizados
|
|
│ ├── lib/ # Utilitários e configurações
|
|
│ └── pages/ # Páginas da aplicação
|
|
├── server/ # Backend Node.js
|
|
│ ├── admin/ # Rotas administrativas
|
|
│ ├── api-central/ # Central de APIs
|
|
│ ├── automations/ # Motor de automações
|
|
│ ├── bi/ # Business Intelligence
|
|
│ ├── chat/ # Chat interno
|
|
│ ├── compass/ # Process Compass (clientes/projetos)
|
|
│ ├── crm/ # Gestão de relacionamento
|
|
│ ├── email/ # Serviço de e-mail
|
|
│ ├── erp/ # Integração ERP
|
|
│ ├── fisco/ # Motor fiscal (NF-e)
|
|
│ ├── ide/ # IDE integrada
|
|
│ ├── learning/ # Sistema de aprendizado
|
|
│ ├── login-bridge/ # Bridge de autenticação
|
|
│ ├── manus/ # Agente autônomo
|
|
│ ├── production/ # Gestão de produção
|
|
│ ├── productivity/ # Hub de produtividade
|
|
│ ├── proxy/ # Proxy reverso
|
|
│ ├── python/ # Serviços Python (FastAPI)
|
|
│ ├── support/ # Central de suporte
|
|
│ ├── valuation/ # Precificação e valuation
|
|
│ └── whatsapp/ # Integração WhatsApp
|
|
└── shared/ # Código compartilhado
|
|
└── schema.ts # Schemas do banco de dados
|
|
```
|
|
|
|
---
|
|
|
|
## Módulos do Sistema
|
|
|
|
### 1. Cockpit (Dashboard Principal)
|
|
**Arquivo:** `client/src/pages/Cockpit.tsx`
|
|
|
|
Painel central com visão geral do sistema:
|
|
- Widgets configuráveis
|
|
- Métricas em tempo real
|
|
- Atividades recentes
|
|
- Atalhos para módulos
|
|
|
|
### 2. Process Compass
|
|
**Arquivo:** `client/src/pages/ProcessCompass.tsx`
|
|
**API:** `/api/compass/*`
|
|
|
|
Gestão completa de processos empresariais:
|
|
- **Clientes:** Cadastro, histórico, segmentação
|
|
- **Projetos:** Cronograma, tarefas, milestones
|
|
- **Contratos:** Gestão de contratos e renovações
|
|
- **Timesheet:** Controle de horas trabalhadas
|
|
|
|
### 3. Comunicação Unificada
|
|
**Arquivo:** `client/src/pages/Comunicacao.tsx`
|
|
**API:** `/api/whatsapp/*`
|
|
|
|
Centro de comunicação multi-canal:
|
|
- **WhatsApp Business:** Atendimento via Baileys
|
|
- **Chat Interno:** Comunicação da equipe
|
|
- **E-mail:** Integração IMAP/SMTP
|
|
- **Tickets:** Sistema de filas de atendimento
|
|
|
|
### 4. CRM (Customer Relationship Management)
|
|
**Arquivo:** `client/src/pages/Crm.tsx`
|
|
**API:** `/api/crm/*`
|
|
|
|
Gestão de relacionamento com clientes:
|
|
- Pipeline de vendas
|
|
- Funil de conversão
|
|
- Gestão de oportunidades
|
|
- Comissionamento automático
|
|
- Integração com Google Calendar
|
|
|
|
### 5. Business Intelligence (Arcádia Insights)
|
|
**Arquivo:** `client/src/pages/BiWorkspace.tsx`
|
|
**API:** `/api/bi/*`
|
|
|
|
Análise e visualização de dados:
|
|
- Upload de arquivos (CSV, Excel)
|
|
- Gráficos interativos (Recharts)
|
|
- Dashboards personalizáveis
|
|
- Conexão com múltiplas fontes
|
|
|
|
### 6. Scientist (Central de Inteligência)
|
|
**Arquivo:** `client/src/pages/Scientist.tsx`
|
|
**API:** `/api/scientist/*`
|
|
|
|
Módulo de auto-programação com IA:
|
|
- Análise de dados automatizada
|
|
- Geração de código (Python/SQL)
|
|
- Execução em sandbox
|
|
- Armazenamento de soluções reutilizáveis
|
|
|
|
### 7. Manus (Agente Autônomo)
|
|
**Arquivo:** `client/src/pages/Agent.tsx`
|
|
**API:** `/api/manus/*`
|
|
|
|
Executor de tarefas autônomo:
|
|
- Loop pensamento-ação-observação
|
|
- Ferramentas disponíveis:
|
|
- Busca web
|
|
- Consulta ao Knowledge Graph
|
|
- Consulta ERP
|
|
- Cálculos
|
|
- Envio de mensagens
|
|
- Geração de relatórios
|
|
- Agendamentos
|
|
|
|
### 8. Arcádia Fisco (Motor Fiscal)
|
|
**Arquivo:** `client/src/pages/Fisco.tsx`
|
|
**API:** `/api/fisco/*`
|
|
|
|
Motor fiscal centralizado para compliance brasileiro:
|
|
- **NCM:** Nomenclatura Comum do Mercosul
|
|
- **CFOP:** Código Fiscal de Operações
|
|
- **CEST:** Código Especificador da Substituição Tributária
|
|
- **Grupos de Tributação:** Configuração de impostos
|
|
- **Certificados Digitais:** Gestão de A1/A3
|
|
- **NF-e/NFC-e:** Emissão de notas fiscais eletrônicas
|
|
- **IBS/CBS:** Campos para Reforma Tributária
|
|
|
|
#### Integração nfelib (Python)
|
|
**Arquivo:** `server/python/fisco_service.py`
|
|
|
|
Serviço FastAPI para processamento de NF-e:
|
|
- Geração de XML (layout 4.00)
|
|
- Assinatura digital com certificado A1
|
|
- Comunicação com SEFAZ (homologação/produção)
|
|
- Consulta, cancelamento e inutilização
|
|
|
|
### 9. Produção
|
|
**Arquivo:** `client/src/pages/Production.tsx`
|
|
**API:** `/api/production/*`
|
|
|
|
Gestão de produção e manufatura:
|
|
- Ordens de produção
|
|
- Controle de estoque
|
|
- Rastreabilidade
|
|
- Custos de produção
|
|
|
|
### 10. Valuation (Precificação)
|
|
**Arquivo:** `client/src/pages/Valuation.tsx`
|
|
**API:** `/api/valuation/*`
|
|
|
|
Sistema de precificação inteligente:
|
|
- Cálculo de custos
|
|
- Margem de contribuição
|
|
- Markup
|
|
- Simulações de preço
|
|
|
|
### 11. Suporte
|
|
**Arquivo:** `client/src/pages/Support.tsx`
|
|
**API:** `/api/support/*`
|
|
|
|
Central de atendimento:
|
|
- Tickets de suporte
|
|
- Base de conhecimento
|
|
- SLA e prioridades
|
|
- Histórico de atendimentos
|
|
|
|
### 12. Automações
|
|
**Arquivo:** `client/src/pages/Automations.tsx`
|
|
**API:** `/api/automations/*`
|
|
|
|
Motor de automações:
|
|
- Triggers e ações
|
|
- Workflows visuais
|
|
- Integrações via webhooks
|
|
- Agendamentos (cron)
|
|
|
|
### 13. Knowledge Base
|
|
**Arquivo:** `client/src/pages/Knowledge.tsx`
|
|
**API:** `/api/knowledge/*`
|
|
|
|
Base de conhecimento:
|
|
- Artigos e documentação
|
|
- Categorização
|
|
- Busca semântica
|
|
- Integração com IA
|
|
|
|
### 14. IDE
|
|
**Arquivo:** `client/src/pages/IDE.tsx`
|
|
**API:** `/api/ide/*`
|
|
|
|
Ambiente de desenvolvimento integrado:
|
|
- Monaco Editor
|
|
- Terminal (Xterm.js)
|
|
- Execução de código
|
|
- Gerenciamento de arquivos
|
|
|
|
### 15. Administração
|
|
**Arquivo:** `client/src/pages/Admin.tsx`
|
|
**API:** `/api/admin/*`
|
|
|
|
Painel administrativo:
|
|
- **Usuários:** Gestão de contas
|
|
- **Perfis:** Controle de acesso
|
|
- **Parceiros:** Hierarquia multi-tenant
|
|
- **Módulos:** Configuração de funcionalidades
|
|
- **Configurações:** Parâmetros do sistema
|
|
|
|
### 16. API Hub
|
|
**Arquivo:** `client/src/pages/ApiHub.tsx`
|
|
|
|
Documentação interativa de APIs:
|
|
- Listagem de endpoints
|
|
- Testes em tempo real
|
|
- Exemplos de uso
|
|
- Geração de código
|
|
|
|
---
|
|
|
|
## Modelo de Dados
|
|
|
|
### Entidades Principais
|
|
|
|
#### Usuários e Autenticação
|
|
```sql
|
|
users -- Usuários do sistema
|
|
profiles -- Perfis de acesso
|
|
roles -- Papéis (RBAC)
|
|
permissions -- Permissões granulares
|
|
role_permissions -- Associação papel-permissão
|
|
user_roles -- Associação usuário-papel
|
|
module_access -- Controle de acesso a módulos
|
|
```
|
|
|
|
#### Produtividade
|
|
```sql
|
|
workspace_pages -- Páginas estilo Notion
|
|
page_blocks -- Blocos de conteúdo
|
|
page_links -- Links bidirecionais
|
|
dashboard_widgets -- Widgets do dashboard
|
|
quick_notes -- Notas rápidas
|
|
activity_feed -- Feed de atividades
|
|
user_favorites -- Favoritos
|
|
command_history -- Histórico de comandos
|
|
```
|
|
|
|
#### Conversação e IA
|
|
```sql
|
|
conversations -- Conversas com agente
|
|
messages -- Mensagens
|
|
chat_attachments -- Anexos
|
|
knowledge_base -- Base de conhecimento
|
|
```
|
|
|
|
#### ERP e Integrações
|
|
```sql
|
|
erp_connections -- Conexões com ERPs
|
|
agent_tasks -- Tarefas do agente
|
|
task_executions -- Execuções de tarefas
|
|
```
|
|
|
|
#### Comunicação
|
|
```sql
|
|
chat_threads -- Threads de chat
|
|
chat_participants -- Participantes
|
|
chat_messages -- Mensagens de chat
|
|
whatsapp_sessions -- Sessões WhatsApp
|
|
whatsapp_contacts -- Contatos WhatsApp
|
|
whatsapp_messages -- Mensagens WhatsApp
|
|
whatsapp_queues -- Filas de atendimento
|
|
whatsapp_tickets -- Tickets de atendimento
|
|
```
|
|
|
|
#### Process Compass
|
|
```sql
|
|
compass_clients -- Clientes
|
|
compass_projects -- Projetos
|
|
compass_project_members -- Membros de projeto
|
|
compass_project_phases -- Fases de projeto
|
|
compass_contracts -- Contratos
|
|
compass_timesheet -- Timesheet
|
|
compass_invoices -- Faturas
|
|
compass_payments -- Pagamentos
|
|
```
|
|
|
|
#### CRM
|
|
```sql
|
|
crm_leads -- Leads
|
|
crm_opportunities -- Oportunidades
|
|
crm_activities -- Atividades
|
|
crm_pipelines -- Pipelines
|
|
crm_stages -- Estágios
|
|
crm_commissions -- Comissões
|
|
```
|
|
|
|
#### Fisco
|
|
```sql
|
|
fisco_ncm -- NCMs
|
|
fisco_cest -- CESTs
|
|
fisco_cfop -- CFOPs
|
|
fisco_grupos_tributacao -- Grupos de tributação
|
|
fisco_natureza_operacao -- Naturezas de operação
|
|
fisco_ibpt -- Tabela IBPT
|
|
fisco_certificados -- Certificados digitais
|
|
fisco_configuracoes -- Configurações fiscais
|
|
fisco_notas -- Notas fiscais
|
|
fisco_nota_itens -- Itens das notas
|
|
fisco_nota_eventos -- Eventos fiscais
|
|
```
|
|
|
|
#### Multi-Tenant
|
|
```sql
|
|
partners -- Parceiros
|
|
partner_invites -- Convites de parceiros
|
|
tenant_clients -- Clientes dos tenants
|
|
```
|
|
|
|
---
|
|
|
|
## APIs e Endpoints
|
|
|
|
### Estrutura Base
|
|
|
|
| Módulo | Base URL | Descrição |
|
|
|--------|----------|-----------|
|
|
| Admin | `/api/admin` | Administração do sistema |
|
|
| Compass | `/api/compass` | Process Compass |
|
|
| CRM | `/api/crm` | Gestão de relacionamento |
|
|
| WhatsApp | `/api/whatsapp` | Comunicação WhatsApp |
|
|
| Fisco | `/api/fisco` | Motor fiscal |
|
|
| BI | `/api/bi` | Business Intelligence |
|
|
| Production | `/api/production` | Gestão de produção |
|
|
| Valuation | `/api/valuation` | Precificação |
|
|
| Support | `/api/support` | Central de suporte |
|
|
| Automations | `/api/automations` | Automações |
|
|
| IDE | `/api/ide` | Ambiente de desenvolvimento |
|
|
| Learning | `/api/learning` | Sistema de aprendizado |
|
|
|
|
### Exemplos de Endpoints
|
|
|
|
#### Fisco - NF-e
|
|
```
|
|
GET /api/fisco/nfe/service-status # Status do serviço
|
|
POST /api/fisco/nfe/validar-certificado # Validar certificado A1
|
|
POST /api/fisco/nfe/gerar-xml # Gerar XML preview
|
|
POST /api/fisco/nfe/emitir # Emitir NF-e
|
|
POST /api/fisco/nfe/consultar # Consultar na SEFAZ
|
|
POST /api/fisco/nfe/cancelar # Cancelar NF-e
|
|
POST /api/fisco/nfe/inutilizar # Inutilizar numeração
|
|
```
|
|
|
|
#### Compass - Clientes
|
|
```
|
|
GET /api/compass/clients # Listar clientes
|
|
GET /api/compass/clients/:id # Detalhes do cliente
|
|
POST /api/compass/clients # Criar cliente
|
|
PUT /api/compass/clients/:id # Atualizar cliente
|
|
DELETE /api/compass/clients/:id # Excluir cliente
|
|
```
|
|
|
|
#### Admin - Usuários
|
|
```
|
|
GET /api/admin/users # Listar usuários
|
|
GET /api/admin/users/:id # Detalhes do usuário
|
|
POST /api/admin/users # Criar usuário
|
|
PUT /api/admin/users/:id # Atualizar usuário
|
|
DELETE /api/admin/users/:id # Excluir usuário
|
|
```
|
|
|
|
---
|
|
|
|
## Integrações Externas
|
|
|
|
### OpenAI API
|
|
- **Uso:** Agente de IA, Scientist, auto-replies
|
|
- **Modelo:** gpt-4o-mini
|
|
- **Configuração:** Via Replit Secrets
|
|
|
|
### Baileys (WhatsApp)
|
|
- **Uso:** Conexão multi-sessão WhatsApp
|
|
- **Recursos:** QR Code, mensagens em tempo real
|
|
- **Armazenamento:** Sessões no banco de dados
|
|
|
|
### nfelib (Python)
|
|
- **Uso:** Emissão de NF-e/NFC-e
|
|
- **Recursos:** XML, assinatura digital, SEFAZ
|
|
- **Certificados:** A1 (PFX)
|
|
|
|
### Frappe Framework
|
|
- **Uso:** Arcádia Next (futuro)
|
|
- **Recursos:** ERPNext integration
|
|
|
|
### Google Calendar
|
|
- **Uso:** Sincronização de eventos CRM
|
|
- **OAuth:** Configurável por usuário
|
|
|
|
---
|
|
|
|
## Segurança e Autenticação
|
|
|
|
### Autenticação
|
|
- **Método:** Session-based com Passport.js
|
|
- **Hash:** bcrypt para senhas
|
|
- **Sessões:** PostgreSQL session store
|
|
|
|
### Controle de Acesso (RBAC)
|
|
```
|
|
Hierarquia:
|
|
├── Master (Arcádia)
|
|
│ └── Parceiros
|
|
│ └── Clientes
|
|
```
|
|
|
|
### Permissões
|
|
- Baseadas em módulos e ações
|
|
- Código formato: `modulo.recurso.acao`
|
|
- Exemplo: `compass.clients.write`
|
|
|
|
### Certificados Digitais
|
|
- Tipo A1 (arquivo PFX)
|
|
- Armazenamento seguro com senha
|
|
- Validação de expiração
|
|
|
|
---
|
|
|
|
## Guia de Implantação
|
|
|
|
### Requisitos
|
|
- Node.js 20+
|
|
- Python 3.11+
|
|
- PostgreSQL 15+
|
|
- Certificado SSL (produção)
|
|
|
|
### Variáveis de Ambiente
|
|
```env
|
|
DATABASE_URL=postgresql://...
|
|
SESSION_SECRET=...
|
|
OPENAI_API_KEY=...
|
|
FISCO_PYTHON_URL=http://localhost:8002
|
|
FISCO_PORT=8002
|
|
```
|
|
|
|
### Comandos de Inicialização
|
|
```bash
|
|
# Instalar dependências
|
|
npm install
|
|
|
|
# Iniciar em desenvolvimento
|
|
npm run dev
|
|
|
|
# Serviço Python Fisco (separado)
|
|
cd server/python && python fisco_service.py
|
|
```
|
|
|
|
### Portas
|
|
| Serviço | Porta |
|
|
|---------|-------|
|
|
| Frontend + API | 5000 |
|
|
| Python Fisco | 8002 |
|
|
| Python IA | 8001 |
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
### Janeiro 2026
|
|
- Integração nfelib para NF-e
|
|
- Módulo Fisco completo
|
|
- Sistema de aprendizado automático
|
|
- Validação Zod em todas as rotas fiscais
|
|
|
|
---
|
|
|
|
**Arcádia Suite** - Transformando a gestão empresarial com Inteligência Artificial
|
|
|
|
*Documentação gerada automaticamente pelo sistema.*
|