arcadia-admin
/
arcadiasuite
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
arcadiasuite/docs/KERNEL_SPEC.md

321 lines
11 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink