arcadiasuite/docs/KERNEL_SPEC.md

Especificação Técnica: Arcadia Kernel

Versão: 3.3
Status: ✅ Produção
Ú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 APPLICATION (5000)                      │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                      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) │                          │   │
│  │              └──────────┬──────────┘                          │   │
│  └─────────────────────────┼─────────────────────────────────────┘   │
│                            │                                          │
│         ┌──────────────────┴──────────────────┐                       │
│         │  global.arcadiaKernelRegistry        │                       │
│         │  (Acesso direto - mesmo processo)    │                       │
│         └──────────────────┬──────────────────┘                       │
│                            │                                          │
│    ┌───────────────────────┴───────────────────────┐                  │
│    │                                               │                  │
│    ▼                                               ▼                  │
│ ┌─────────────────┐                    ┌─────────────────────┐       │
│ │  Casa de        │                    │  /api/engine-room/* │       │
│ │  Máquinas       │                    │  (API Express)      │       │
│ │  (React UI)     │                    │                     │       │
│ └─────────────────┘                    └─────────────────────┘       │
└─────────────────────────────────────────────────────────────────────────┘

Legenda:
  ───► HTTP/HTTPS          ─ ─► Acesso direto (memória)
  Porta 5000: App principal    Porta 5001: Kernel Dashboard (interno)

---

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
         │
         ▼
┌─────────────────────────────┐
│  fetchRegistryServices()    │
│                             │
│  PRIORIDADE 1: Registry     │
│  Global (mesmo processo)    │
│  ─────────────────────────  │
│  (global.arcadiaKernel      │
│   .serviceRegistry)         │
│         │                   │
│         ▼                   │
│  ┌─────────────┐            │
│  │  Acesso     │            │
│  │  direto     │            │
│  │  (memória)  │            │
│  └──────┬──────┘            │
│         │                   │
│  Se falhar:                 │
│  ─────────────────────────  │
│  PRIORIDADE 2: HTTP         │
│  Fallback para porta 5001   │
│         │                   │
│         ▼                   │
│  ┌─────────────┐            │
│  │  http.get   │            │
│  │  127.0.0.1  │            │
│  │  localhost  │            │
│  └──────┬──────┘            │
└─────────┼───────────────────┘
          │
          ▼
    Resposta JSON
          │
          ▼
     Frontend Render

5.2 Implementação Atual

// server/engine-room/routes.ts
async function fetchRegistryServicesWithRetry(): Promise<any[] | null> {
  // PRIORIDADE 1: Registry global (mesmo processo Node.js)
  const globalRegistry = (global as any).arcadiaKernelRegistry;
  if (globalRegistry) {
    const services = globalRegistry.getServices();
    console.log(`[Engine Room] Usando Registry global: ${services.length} serviços`);
    return services;
  }
  
  // PRIORIDADE 2: HTTP request para porta 5001 (fallback)
  console.log('[Engine Room] Registry global não disponível, tentando HTTP...');
  // ... retry com 127.0.0.1 e localhost
}

Vantagens do Registry Global

Aspecto	HTTP (antigo)	Registry Global (novo)
Latência	~10-50ms	~0.1ms
Confiabilidade	Problemas com loopback Docker	100% (mesmo processo)
Complexidade	Retry, timeout, hostname	Acesso direto
Failover	Necessário	Não aplicável

Inicialização no server/index.ts

// Inicia Kernel ANTES do servidor HTTP
const kernel = new ArcadiaKernel({
  dashboard: { enabled: true, port: 5001, host: '0.0.0.0' },
  autoStart: process.env.KERNEL_AUTOSTART === 'true',
});
await kernel.start();

// Exporta Registry globalmente
if (kernel.serviceRegistry) {
  (global as any).arcadiaKernelRegistry = kernel.serviceRegistry;
}

// DEPOIS inicia servidor HTTP (porta 5000)
httpServer.listen({ port: 5000, host: "0.0.0.0" }, ...);

---

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,rls,embedding"

---

7. Roadmap

Semana 4 ✅ CONCLUÍDO

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

Semana 5 ✅ CONCLUÍDO

• XOSDiscovery
• Registry Global (acesso direto)
• Integração Casa de Máquinas via memória
• UnifiedRegistry (agregador) - Opcional

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, XOS Discovery, correção MetaSet
2026-04-08	3.3	Registry Global - Casa de Máquinas usa acesso direto (memória) em vez de HTTP
2026-04-08	3.4	MetaSet Consolidado - Migração Metabase → Apache Superset 4.1.0

---

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