diff --git a/docs/KERNEL_SPEC.md b/docs/KERNEL_SPEC.md new file mode 100644 index 0000000..8b56292 --- /dev/null +++ b/docs/KERNEL_SPEC.md @@ -0,0 +1,320 @@ +# Especificação Técnica: Arcadia Kernel + +> **Versão:** 3.2 +> **Status:** Em desenvolvimento (Semana 5) +> **Última atualização:** 2026-04-08 + +--- + +## 1. Visão Geral + +O **Arcadia Kernel** é o sistema operacional nativo da ArcadiaSuite - um orquestrador de serviços em Node.js que unifica discovery, health monitoring e gerenciamento de processos. + +### 1.1 Objetivos + +- **Discovery**: Descobrir automaticamente todos os serviços do ecossistema +- **Orquestração**: Iniciar, parar e reiniciar serviços (processos e containers) +- **Observabilidade**: Health checks, logs e métricas centralizados +- **Integração**: Unificar visão da Casa de Máquinas com dados reais + +### 1.2 Arquitetura + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ ARCADIA KERNEL (5001) │ +├─────────────────────────────────────────────────────────────────┤ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ Dashboard │ │ Process │ │ LogAggregator │ │ +│ │ (Web UI) │ │ Manager │ │ │ │ +│ └──────┬──────┘ └──────┬──────┘ └─────────────────────────┘ │ +│ │ │ │ +│ └────────────────┴────────────────┐ │ +│ │ │ │ +│ ┌───────────┴───────────┐ │ │ +│ │ Service Registry │ │ │ +│ │ (Unified Discovery) │ │ │ +│ └───────────┬───────────┘ │ │ +│ │ │ │ +│ ┌─────────────────────┼───────────────┘ │ +│ │ │ │ +│ ┌──┴──┐ ┌──────────┐ ┌┴─────────┐ ┌──────────┐ ┌────────┐ │ +│ │Static│ │ Coolify │ │ XOS │ │ Docker │ │ ... │ │ +│ │Disc. │ │ Disc. │ │ Disc. │ │ Disc. │ │ │ │ +│ └──┬──┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │ +│ │ │ │ │ │ │ +│ └──────────┴─────────────┴─────────────┴────────────┘ │ +│ │ │ +│ ┌──────────┴──────────┐ │ +│ │ UnifiedRegistry │ │ +│ │ (Agregação + Dedu) │ │ +│ └──────────┬──────────┘ │ +└─────────────────────────┼─────────────────────────────────────┘ + │ + ┌────────────────┼────────────────┐ + │ │ │ + ┌──┴──┐ ┌──┴──┐ ┌──┴──┐ + │5000 │ │5001 │ │8080 │ + │App │ │Kernel│ │Plus │ + └─────┘ └─────┘ └─────┘ +``` + +--- + +## 2. Componentes + +### 2.1 Core (ProcessManager, HealthMonitor, LogAggregator) + +**Status:** ✅ Estável + +- **ProcessManager**: Gerencia processos Node.js/Python locais +- **HealthMonitor**: Health checks periódicos +- **LogAggregator**: Coleta e armazena logs + +### 2.2 Service Registry + +**Status:** ✅ Implementado + +Catálogo central de serviços com: +- Registro manual ou automático +- Health status tracking +- Capabilities e metadados +- Eventos (service:registered, service:health_changed, etc) + +### 2.3 Discovery Providers + +| Provider | Status | Descrição | +|----------|--------|-----------| +| `StaticDiscovery` | ✅ | DNS interno (nomes fixos) | +| `CoolifyDiscovery` | ✅ | API Coolify (produção) | +| `DockerDiscovery` | ✅ | Docker labels (fallback) | +| `XOSDiscovery` | ✅ | Banco XOS (filas, integrações) | +| `UnifiedRegistry` | ⏳ | Agregador (Semana 5) | + +--- + +## 3. Discovery Providers + +### 3.1 StaticDiscovery + +Descobre serviços via nomes DNS fixos na rede Docker. + +```typescript +// Ex: http://contabil:8003, http://bi:8004 +``` + +### 3.2 CoolifyDiscovery + +Consulta API Coolify para descobrir serviços em produção. + +**Endpoints:** +- `GET /api/v1/services` - Docker Compose services +- `GET /api/v1/applications` - Aplicações + +**Filtro:** `arcadia.discovery.enabled=true` + +### 3.3 DockerDiscovery + +Lê labels de containers Docker na rede local. + +**Labels:** +- `arcadia.discovery.enabled=true` +- `arcadia.name=MetaSet BI` +- `arcadia.type=python` +- `arcadia.port=8100` +- `arcadia.capabilities=dashboards,charts,sql_lab` + +### 3.4 XOSDiscovery + +Consulta banco de dados para descobrir serviços XOS. + +**Descobre:** +- Filas de atendimento (`xos_queues`) +- Integrações WhatsApp (`whatsapp_sessions`) +- Automações ativas (`xos_automations`) + +--- + +## 4. API do Kernel + +### 4.1 Endpoints Core + +| Endpoint | Método | Descrição | +|----------|--------|-----------| +| `/health` | GET | Health check do Kernel | +| `/api/kernel/services` | GET | Lista serviços do ProcessManager | +| `/api/kernel/services/:id/start` | POST | Inicia serviço | +| `/api/kernel/services/:id/stop` | POST | Para serviço | +| `/api/kernel/services/:id/restart` | POST | Reinicia serviço | +| `/api/kernel/services/:id/logs` | GET | Logs do serviço | + +### 4.2 Endpoints Registry + +| Endpoint | Método | Descrição | +|----------|--------|-----------| +| `/api/registry/services` | GET | Lista serviços descobertos | +| `/api/registry/services/:id` | GET | Detalhes de um serviço | +| `/api/registry/by-category/:cat` | GET | Serviços por categoria | +| `/api/registry/by-capability/:cap` | GET | Serviços por capability | +| `/api/registry/stats` | GET | Estatísticas do registry | +| `/api/registry/discover` | POST | Força discovery manual | + +### 4.3 Endpoints Casa de Máquinas + +| Endpoint | Método | Descrição | +|----------|--------|-----------| +| `/api/engine-room/status` | GET | Status unificado (Registry + Presets) | +| `/api/engine-room/engine/:name/health` | GET | Health de um motor | +| `/api/engine-room/engine/:name/start` | POST | Inicia motor | +| `/api/engine-room/engine/:name/stop` | POST | Para motor | +| `/api/engine-room/engine/:name/restart` | POST | Reinicia motor | +| `/api/engine-room/engine/:name/logs` | GET | Logs do motor | + +--- + +## 5. Integração Casa de Máquinas + +### 5.1 Fluxo de Dados + +``` +Casa de Máquinas (React) + │ + ▼ +/api/engine-room/status + │ + ▼ +┌─────────────────┐ +│ fetchRegistry │ ◄── Tenta Registry primeiro +│ Services() │ +└────────┬────────┘ + │ + ┌────┴────┐ + │ │ + ▼ ▼ +┌───────┐ ┌────────┐ +│Registry│ │Fallback│ +│ OK │ │Kernel │ +└───┬───┘ │Adapter │ + │ └───┬────┘ + │ │ + └────┬─────┘ + ▼ +┌─────────────────┐ +│ Adiciona │ +│ Externos │ ◄── Plus, MetaSet (se não no Registry) +│ (se necessário)│ +└────────┬────────┘ + ▼ + Resposta JSON + │ + ▼ + Frontend Render +``` + +### 5.2 Lógica de Deduplicação + +```typescript +// 1. Consulta Registry +const registryServices = await fetchRegistryServices(); + +// 2. Se Registry tem dados, usa eles +if (registryServices?.length > 0) { + engines = registryServices.map(mapRegistryToEngine); +} +// 3. Senão, fallback para kernel-adapter +else { + engines = await getKernelEngines(); +} + +// 4. Adiciona externos apenas se não existirem +if (!engines.find(e => e.name === "plus")) { + engines.push(await checkEngineHealth(plusEngine)); +} + +// 5. MetaSet só adiciona se não houver bi-engine +if (!engines.find(e => e.name === "metaset" || e.name === "bi-engine")) { + engines.push(await checkEngineHealth(metasetEngine)); +} +``` + +--- + +## 6. Configuração + +### 6.1 Variáveis de Ambiente + +```bash +# Kernel +KERNEL_ENABLED=true +KERNEL_AUTOSTART=true + +# Coolify Discovery +COOLIFY_API_TOKEN=seu_token_aqui + +# MetaSet +METASET_HOST=metaset +METASET_PORT=8100 + +# Modo Docker (desativa spawn de processos) +DOCKER_MODE=true +``` + +### 6.2 Docker Compose Labels + +```yaml +services: + metaset: + labels: + - "arcadia.discovery.enabled=true" + - "arcadia.name=MetaSet BI" + - "arcadia.type=python" + - "arcadia.category=bi" + - "arcadia.port=8100" + - "arcadia.capabilities=dashboards,charts,sql_lab" +``` + +--- + +## 7. Roadmap + +### Semana 4 ✅ CONCLUÍDO +- [x] Service Registry +- [x] StaticDiscovery +- [x] CoolifyDiscovery +- [x] DockerDiscovery +- [x] Integração com Casa de Máquinas + +### Semana 5 EM ANDAMENTO +- [x] XOSDiscovery +- [ ] UnifiedRegistry (agregador) +- [ ] Deduplicação automática +- [ ] Priorização de providers + +### Semana 6 PLANEJADO +- [ ] Maestro IA (Guardião de IAs) +- [ ] Policy Engine +- [ ] Audit Trail + +### Semana 7 PLANEJADO +- [ ] Integração completa Maestro +- [ ] Documentação P2P + +--- + +## 8. Histórico de Mudanças + +| Data | Versão | Mudança | +|------|--------|---------| +| 2026-04-06 | 3.0 | Service Registry + Discovery | +| 2026-04-07 | 3.1 | Integração Casa de Máquinas | +| 2026-04-08 | 3.2 | Coolify Discovery implementado, XOS Discovery, correção MetaSet | + +--- + +## 9. Referências + +- `/server/kernel/` - Código fonte do Kernel +- `/server/kernel/registry/` - Service Registry +- `/server/kernel/discovery/` - Discovery Providers +- `/server/engine-room/` - Casa de Máquinas (backend) +- `/client/src/pages/Admin.tsx` - Casa de Máquinas (frontend) +- `/home/ubuntu/.kimi/kernel e tenants.md` - Planejamento executivo