# 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.

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