Skip to content

# Nodes_Interface_Architecture_v1.md

## DAARION.city — Nodes Interface & Node Management Architecture

Version: 1.0
Status: Foundation Spec (MVP)
Scope: Node dashboards, control rooms, node registration, capabilities, health monitoring, DAGI mesh integration

# 0. Мета документа

Визначити інтерфейс керування нодами в DAARION.city:

- як відображаються ноди в UI,
- як реєструються та верифікуються ноди,
- як моніториться здоров'я та ресурси,
- як ноди інтегруються з MicroDAO та DAGI Mesh,
- як агенти виконуються на нодах,
- як відбувається координація Node Fleet.

# 1. Роль Nodes Interface

Nodes Interface — це шар управління фізичними та логічними вузлами DAGI Mesh:

- відображення стану нод MicroDAO,
- реєстрація нових нод,
- моніторинг ресурсів (CPU, GPU, RAM, network),
- управління lifecycle нод,
- прив'язка агентів до нод,
- fleet management для District.

# 2. Типи нод

Тип | Опис | Capabilities
--- | --- | ---
`smartphone` | мобільний пристрій | low compute, camera, GPS, sensors
`laptop` | персональний комп'ютер | mid compute, local LLM, development
`edge` | edge device | low-mid compute, IoT gateway
`datacenter` | серверна інфраструктура | high compute, GPU, 24/7
`iot` | IoT пристрій | sensors, actuators, minimal compute
`gpu-cluster` | GPU-кластер | high GPU, ML inference/training

# 3. Структура Node Dashboard

## 3.1. Node Overview

- `node_id`, `node_kind`
- `microdao_id` — власник ноди
- `status`: provisioning | active | draining | retired
- `capabilities` — ресурси (CPU, GPU, RAM, network)
- Останній heartbeat
- Кількість активних агентів

## 3.2. Health Metrics

- CPU utilization
- Memory usage
- GPU utilization (якщо є)
- Network throughput
- Latency до mesh router
- Uptime

## 3.3. Agent Sessions

- Список агентів, що виконуються на ноді
- Статус кожного агента (active, idle, error)
- Ресурси, зайняті агентом

# 4. Реєстрація ноди

## 4.1. Flow

1. Оркестратор MicroDAO обирає "Register Node".
2. Вказує тип ноди (`node_kind`).
3. Генерується provisioning token.
4. Пристрій завантажує DAGI agent та вводить token.
5. Нода автентифікується через DAIS node-auth.
6. Подія `node.registered` публікується в NATS.
7. Нода переходить у `provisioning`, потім `active`.

## 4.2. Інваріанти

- Нода завжди належить MicroDAO.
- Реєстрацію ініціює Orchestrator.
- Після реєстрації нода підключається до DAGI Mesh.

# 5. Екрани інтерфейсу

## 5.1. MicroDAO Nodes Tab

- `/microdao/{id}/nodes` — список нод MicroDAO
- Таблиця: node_id, kind, status, capabilities, agents, actions
- Кнопка "Register Node"

## 5.2. Node Detail

- `/node/{id}` — деталі ноди
- Overview, Health, Agents, Logs, Settings
- Actions: restart agents, drain, retire

## 5.3. Fleet Management (District)

- `/district/{id}/fleet` — всі ноди підлеглих MicroDAO
- Aggregated metrics, alerts
- Scheduling policies

# 6. API Endpoints

    GET  /api/microdao/{id}/nodes
    POST /api/microdao/{id}/nodes/register
    GET  /api/node/{id}
    GET  /api/node/{id}/health
    GET  /api/node/{id}/agents
    POST /api/node/{id}/drain
    POST /api/node/{id}/retire

# 7. DAGI Mesh Integration

- Кожна нода підключається до DAGI Router.
- Ноди отримують task scheduling від Router.
- Агенти виконуються на нодах через Worker Runtime.
- Heartbeat кожні 30 секунд до Mesh Controller.

# 8. Lifecycle Management

    provisioning → active → draining → retired

- provisioning: нода реєструється, очікує верифікації.
- active: нода працює, приймає агентів.
- draining: нода готується до вимкнення, нові агенти не призначаються.
- retired: нода офлайн, архівована.

# 9. Security

- Доступ до ноди через DAIS node-auth.
- Тільки Orchestrator/Core-Team можуть керувати нодами.
- Agent sessions ізольовані (container/sandbox).
- Всі комунікації шифровані (mTLS).

# 10. MVP Scope

- Node list у MicroDAO interface.
- Node registration flow.
- Basic health display (status, capabilities).
- Agent sessions list.
- Drain/Retire actions.

Не входить: advanced scheduling, GPU quotas, auto-scaling.

# 11. Зв'язок з іншими документами

- Ontology → Node як сутність Agent → MicroDAO → Node → District.
- Data Model → таблиця `nodes` з полями.
- Event Catalog → `node.registered`.
- MicroDAO Interface → Nodes Tab.
- Governance → права на реєстрацію нод.
- DAIS → node-auth для автентифікації.

# 12. Підсумок

Nodes Interface забезпечує управління фізичною інфраструктурою DAGI Mesh:

- реєстрацію нод,
- моніторинг здоров'я та ресурсів,
- виконання агентів,
- lifecycle management,
- fleet management для District.

Документ завершено.