microdao-daarion/docs/tasks/TASK_PHASE9_LIVING_MAP_FULL.md

TASK PHASE 9 — LIVING MAP (FULL STACK SERVICE)

Version: 1.0
Status: READY FOR IMPLEMENTATION
Scope: Backend + WebSocket + NATS + Minimal Frontend Hook

1. Context

DAARION уже має:

• core сервіси:
  • messaging-service (Matrix-aware Messenger)
  • agent-runtime, agent-filter, dagi-router
  • llm-proxy, memory-orchestrator, toolcore
  • auth-service, pdp-service, usage-engine
  • agents-service (Agent Hub + lifecycle)
  • microdao-service (microDAO Console)
  • dao-service (DAO Dashboard)
  • city-service, space-service
• інфраструктуру:
  • PostgreSQL
  • NATS JetStream
  • docker-compose для різних фаз
  • WebSocket-потоки для окремих модулів

Потрібен єдиний "Living Map" шар, який агрегує стан всієї мережі:

• City (microDAO, метрики)
• Space (DAO-планети, ноди)
• Nodes (ресурси, алерти)
• Agents (статус, використання)
• DAO (голосування, proposals)
• Messaging (активність каналів)

і видає це:

• через GET /living-map/snapshot (full-state)
• через GET /living-map/history (event log)
• через GET /living-map/entities (каталог сутностей)
• через WS /living-map/stream (живий потік подій).

Цей таск — backend + API + NATS + WS + базовий frontend hook.

---

2. Goals

1. Створити сервіс living-map-service (FastAPI), порт 7017.
2. Зібрати стан мережі з існуючих сервісів в один snapshot.
3. Підписатися на ключові NATS-сабджекти й зберігати історію в living_map_history.
4. Віддавати:
   • snapshot (HTTP)
   • history (HTTP)
   • real-time stream (WS).
5. Додати мінімальну фронтенд-обгортку useLivingMapFull (React hook) для інтеграції з 2D/3D UI.

---

3. Architecture Overview

3.1. New service: living-map-service

• Stack: Python 3 + FastAPI + uvicorn
• Port: 7017
• Responsibilities:
  • Агрегувати дані з:
    • city-service (city snapshot)
    • space-service (planets/nodes/events)
    • agents-service (agents, metrics, events)
    • microdao-service (microDAOs)
    • dao-service (dao, proposals, votes)
    • usage-engine (LLM/tool usage summary)
  • Нормалізувати в єдину структуру сцени:
    • scene.layers.city
    • scene.layers.space
    • scene.layers.nodes
    • scene.layers.agents
    • scene.meta (timestamps, version)
  • Підписуватись на NATS-subject'и й створювати event log.
  • Видавати snapshot/history + WebSocket stream.

3.2. Data sources (HTTP)

Очікувані існуючі/доступні ендпоінти (можна створити прості адаптери, якщо їх ще нема):

• city-service:
  • GET http://city-service:7001/api/city/snapshot
• space-service:
  • GET http://space-service:7002/api/space/scene або окремо planets/nodes/events
• agents-service:
  • GET http://agents-service:7014/agents (list)
  • GET http://agents-service:7014/agents/metrics (summary)
• microdao-service:
  • GET http://microdao-service:7015/microdaos (list)
• dao-service:
  • GET http://dao-service:7016/dao (list)
  • GET http://dao-service:7016/dao/proposals/summary
• usage-engine:
  • GET http://usage-engine:7013/internal/usage/summary?period_hours=24

Якщо чогось немає — зробити простий adapter/placeholder з mock даними всередині living-map-service.

3.3. NATS Subjects

Потрібно підписатися на:

• city.event.*
• dao.event.*
• microdao.event.*
• node.metrics.*
• agent.event.*
• usage.llm.*
• usage.agent.*
• messaging.message.created

(Якщо частина сабджектів ще не існує — підготувати consumer з graceful handling та вимкненими/placeholder subscriptions.)

---

4. API Specification

4.1. GET /living-map/health

Простий health-check.

{
  "status": "ok",
  "service": "living-map-service",
  "version": "1.0.0",
  "time": "2025-11-24T12:34:56Z"
}

4.2. GET /living-map/snapshot

Агрегований стан усієї мережі.

Response (спрощений приклад):

{
  "generated_at": "2025-11-24T12:34:56Z",
  "layers": {
    "city": {
      "microdaos_total": 12,
      "active_users": 57,
      "active_agents": 34,
      "health": "green",
      "items": [
        {
          "id": "microdao:7",
          "slug": "daarion-city",
          "name": "DAARION City",
          "status": "active",
          "agents": 9,
          "nodes": 3
        }
      ]
    },
    "space": {
      "planets": [
        {
          "id": "dao:daarion-core",
          "name": "DAARION CORE",
          "type": "dao",
          "orbits": ["node:gpu-1", "node:gpu-2"],
          "status": "active"
        }
      ],
      "nodes": [
        {
          "id": "node:gpu-1",
          "name": "NODE1",
          "cpu": 0.42,
          "gpu": 0.77,
          "memory": 0.63,
          "alerts": []
        }
      ]
    },
    "nodes": {
      "items": [
        {
          "id": "node:gpu-1",
          "microdao_id": "microdao:7",
          "status": "online",
          "metrics": {
            "cpu": 0.42,
            "gpu": 0.77,
            "ram": 0.63,
            "net_in": 12345,
            "net_out": 9876
          }
        }
      ]
    },
    "agents": {
      "items": [
        {
          "id": "agent:sofia",
          "name": "Sofia",
          "kind": "system",
          "microdao_id": "microdao:7",
          "status": "online",
          "usage": {
            "llm_calls_24h": 123,
            "tokens_24h": 45678
          }
        }
      ]
    }
  },
  "meta": {
    "source_services": [
      "city-service",
      "space-service",
      "agents-service",
      "microdao-service",
      "dao-service",
      "usage-engine"
    ]
  }
}

4.3. GET /living-map/entities

Плоский список сутностей з мінімальними даними для побудови legend/списків.

Query params:

• type (optional): city|space|node|agent|dao|microdao|channel
• limit (optional, default 100)

Response:

{
  "items": [
    {
      "id": "microdao:7",
      "type": "microdao",
      "label": "DAARION City",
      "status": "active",
      "layer": "city"
    },
    {
      "id": "dao:daarion-core",
      "type": "dao",
      "label": "DAARION CORE DAO",
      "status": "active",
      "layer": "space"
    }
  ]
}

4.4. GET /living-map/entities/{id}

Детальний опис сутності (проксі до відповідного сервісу з нормалізацією).

Response (узагальнений):

{
  "id": "agent:sofia",
  "type": "agent",
  "layer": "agents",
  "data": {
    "...": "raw or normalized fields"
  }
}

4.5. GET /living-map/history

Історія подій Living Map.

Query params:

• since (optional, ISO datetime)
• limit (optional, default 200)

Response:

{
  "items": [
    {
      "id": "evt-uuid",
      "timestamp": "2025-11-24T12:30:00Z",
      "event_type": "node.metrics.update",
      "payload": {
        "node_id": "node:gpu-1",
        "cpu": 0.8,
        "gpu": 0.95
      }
    }
  ]
}

4.6. WS /living-map/stream

WebSocket-потік:

• Типи повідомлень:

  • snapshot — повний стан (на підключення та за потреби)
  • event — одинична подія

• Формат:

{
  "kind": "event",
  "event_type": "agent.event.status",
  "timestamp": "2025-11-24T12:34:56Z",
  "payload": { ... }
}

---

5. Database Schema

Створити міграцію, наприклад: migrations/010_create_living_map_tables.sql.

CREATE TABLE IF NOT EXISTS living_map_history (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  timestamp timestamptz NOT NULL DEFAULT now(),
  event_type TEXT NOT NULL,
  payload JSONB NOT NULL
);

CREATE INDEX IF NOT EXISTS idx_living_map_history_timestamp
  ON living_map_history (timestamp DESC);

CREATE INDEX IF NOT EXISTS idx_living_map_history_event_type
  ON living_map_history (event_type);

---

6. Implementation Plan

6.1. Files to create

• services/living-map-service/main.py

• services/living-map-service/models.py

• services/living-map-service/repository_history.py

• services/living-map-service/adapters/city_client.py

• services/living-map-service/adapters/space_client.py

• services/living-map-service/adapters/agents_client.py

• services/living-map-service/adapters/microdao_client.py

• services/living-map-service/adapters/dao_client.py

• services/living-map-service/adapters/usage_client.py

• services/living-map-service/nats_subscriber.py

• services/living-map-service/ws_stream.py

• services/living-map-service/Dockerfile

• services/living-map-service/requirements.txt

• docker-compose.phase9.yml (або оновити загальний)

• scripts/start-phase9.sh

• scripts/stop-phase9.sh

• migrations/010_create_living_map_tables.sql

• Frontend:

  • src/features/livingMap/hooks/useLivingMapFull.ts

6.2. Minimal frontend hook

useLivingMapFull.ts:

• GET /living-map/snapshot → зберігає state

• Підключає WS /living-map/stream

• При kind=event оновлює локальний state (immutable update)

• Повертає:

  • snapshot
  • events
  • isLoading
  • error
  • connectionStatus

---

7. Security / Auth

• Всі HTTP-ендпоінти:

  • Перевірка JWT/Session через auth-service (ActorContext).

• Опціонально, GET /living-map/snapshot може мати:

  • public_mode (спрощений, анонімний)
  • або вимагати auth (рекомендовано).

• WS:

  • Authorization: Bearer <token> у заголовках.

• NATS:

  • лише internal subjects, використовувати існуючий NATS connection з параметрами як в інших сервісах.

---

8. TODO Checklist

Backend:

• Створити міграцію 010_create_living_map_tables.sql
• Створити living-map-service структуру
• Реалізувати адаптери до інших сервісів (з timeout/retry)
• Реалізувати GET /living-map/health
• Реалізувати GET /living-map/snapshot
• Реалізувати GET /living-map/entities
• Реалізувати GET /living-map/entities/{id}
• Реалізувати GET /living-map/history
• Реалізувати WS /living-map/stream
• Реалізувати nats_subscriber.py для key subjects
• Інтегрувати Auth/PDP (як у інших сервісах)
• Додати Dockerfile + requirements.txt
• Оновити docker-compose/script'и
• Додати базові unit tests (snapshot builder)

Frontend:

• Створити useLivingMapFull.ts
• Протестувати запит snapshot + WS stream (можна через тимчасовий debug-компонент)

---

9. Acceptance Criteria

1. docker-compose -f docker-compose.phase9.yml up -d піднімає living-map-service без помилок.

2. GET /living-map/health повертає status=ok.

3. GET /living-map/snapshot повертає валідний JSON з layers.city, layers.space, layers.nodes, layers.agents.

4. GET /living-map/history повертає список подій, які приходять з NATS.

5. WS /living-map/stream надсилає:

   • при підключенні: kind="snapshot"
   • далі: kind="event" при нових подіях.

6. useLivingMapFull успішно підключається до API+WS і оновлює локальний state без TypeScript помилок.

7. Уся нова логіка проходить лінтер та тести.

---

END OF TASK