11 KiB

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.

// 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

// 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

# 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

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

Service Registry
StaticDiscovery
CoolifyDiscovery
DockerDiscovery
Integração com Casa de Máquinas

Semana 5 EM ANDAMENTO

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

11 KiB Raw Blame History