CITY SERVICE SPEC (PORT 7001)¶

Version: 1.0.0¶

0. PURPOSE¶

City Service — геопросторовий та соціальний шар DAARION.city.

Цей сервіс забезпечує:

Living Map — стан міста в реальному часі:
райони,
локації,
структури microDAO,
активні агенти та користувачі.
Presence System — відстеження присутності:
хто знаходиться в якому районі/секторі/каналі,
статуси присутності користувачів і агентів.
Geo Intelligence:
обробка геолокаційних даних,
інтеграція з Geo-agent (мультимодальність),
аналіз шляхів, зон та кластерів.
Project / MicroDAO Mapping:
кожен microDAO має свій "віртуальний район",
кожен проєкт — "будівлю/кластер".
Integration with TeamDefinition & ProjectBus:
локації = канали / контексти,
routing для комунікації між агентами у межах "районів".

Порт сервісу: 7001.

1. FUNCTIONAL OVERVIEW¶

[ Gateway / Web UI / Living Map UI ]
         ↓
[ DAGI Router ] — (text/multimodal events)
         ↓
[ City Service (7001) ]
         ↓
[ PostgreSQL + NATS + Geo-agent ]

City Service синхронізує:

місто як карту (Region/Area/Point),
місто як соціальну мережу (Presence),
місто як структуру проектів і microDAO.

2. CORE DATA STRUCTURES¶

2.1. Region (Регіон)¶

Віртуальний район DAARION.city:

{
  "region_id": "district-greenfood",
  "name": "GREENFOOD District",
  "type": "microdao",    // microdao | project | custom
  "microdao_id": "microdao-greenfood",
  "geometry": { "type": "Polygon", "coordinates": [...] },
  "meta": { "color": "#2ecc71" }
}

2.2. Area / Building / Sector¶

Локальні локації всередині регіонів:

{
  "area_id": "area-greenfood-core",
  "region_id": "district-greenfood",
  "name": "Core Operations",
  "geometry": { "type": "Polygon", "coordinates": [...] },
  "project_id": "proj-greenfood",
  "meta": {}
}

2.3. Presence¶

Хто перебуває де:

{
  "subject_id": "ag_helix",
  "subject_type": "agent",
  "region_id": "district-greenfood",
  "area_id": "area-greenfood-core",
  "status": "active",            // active|idle|offline
  "updated_at": "2025-11-24T10:00:00Z"
}

2.4. Location Update Event¶

{
  "subject_id": "user123",
  "subject_type": "user",
  "geo": { "lat": 52.52, "lon": 13.40 },
  "region_id": "district-greenfood",
  "area_id": "area-greenfood-core"
}

3. DATABASE SCHEMA (PostgreSQL + PostGIS)¶

City Service повинен мати PostGIS.

3.1. regions¶

CREATE TABLE regions (
    region_id     TEXT PRIMARY KEY,
    name          TEXT NOT NULL,
    type          TEXT NOT NULL,
    microdao_id   TEXT,
    geometry      GEOMETRY(POLYGON, 4326),
    meta          JSONB DEFAULT '{}'::jsonb
);

3.2. areas¶

CREATE TABLE areas (
    area_id       TEXT PRIMARY KEY,
    region_id     TEXT REFERENCES regions(region_id),
    name          TEXT NOT NULL,
    project_id    TEXT,
    geometry      GEOMETRY(POLYGON, 4326),
    meta          JSONB DEFAULT '{}'::jsonb
);

3.3. presence¶

CREATE TABLE presence (
    subject_id     TEXT NOT NULL,
    subject_type   TEXT NOT NULL,
    region_id      TEXT NOT NULL,
    area_id        TEXT,
    status         TEXT NOT NULL,
    updated_at     TIMESTAMP NOT NULL DEFAULT now(),
    PRIMARY KEY (subject_id, subject_type)
);

4. PUBLIC HTTP API (CITY SERVICE)¶

4.1. `GET /regions`¶

Список усіх регіонів міста.

4.2. `POST /regions`¶

Створити новий регіон (переважно для microDAO).

4.3. `GET /areas?region_id=...`¶

Список локацій у межах регіону.

4.4. `POST /presence/update`¶

Оновити присутність учасника/агента.

Request:

{
  "subject_id": "ag_helion",
  "subject_type": "agent",
  "geo": { "lat": 50.45, "lon": 30.52 }
}

Відповідь після визначення регіону/зони:

{
  "status": "ok",
  "region_id": "district-daariandao",
  "area_id": "area-governance"
}

4.5. `GET /presence?region_id=...`¶

Повертає, хто зараз у районі.

5. GEO-AGENT INTEGRATION¶

Geo-agent (мультимодальність) використовується для:

Інтерпретація геоданих:
визначити район по координатам,
визначити найближчу зону,
кластеризація.
Запити від користувача:
"Покажи активність агентів у районі GREENFOOD"
"Яким шляхом рухається агент X?"
"Які агенти у проекті Y зараз активні?"
Генерація інсайтів:
heat maps,
аномалії присутності,
навігація робочих потоків.

City Service викликає Geo-agent через:

POST /multimodal/geo/infer

або NATS subject:

dagi.geo.infer

Payload:

{
  "lat": 50.45,
  "lon": 30.52,
  "regions": [...],
  "areas": [...]
}

6. PROJECT BUS INTEGRATION¶

City Service взаємодіє з ProjectBus:

коли створюється новий microDAO → створюється новий регіон;
коли створюється новий проект → нова area/cluster;
агенти/користувачі приєднуються до проектів → presence оновлюється.

Оновлення:

project.<id>.events — події щодо присутності,
project.<id>.map.events — події для UI living map.

Приклад події:

{
  "type": "presence_updated",
  "project_id": "proj-greenfood",
  "subject_id": "ag_helix",
  "region_id": "district-greenfood",
  "area_id": "area-greenfood-core",
  "ts": "2025-11-24T10:10:00Z"
}

7. DAGI ROUTER INTEGRATION¶

City Service інформує DAGI Router про:

зміни регіону/зони:
агенти отримують контекст region_id / area_id,
Router може маршрутизувати події за локацією,
routing за region-каналами (геочати),
особливі правила поведінки в певних регіонах (через TeamDefinition).

Router додає в кожен RouterEvent:

{
  "context": {
    "region_id": "...",
    "area_id": "...",
    "project_id": "...",
    "microdao_id": "..."
  }
}

8. MULTINODE SUPPORT¶

City Service може бути:

один на всі ноди (centralized),
або розгорнутий на кожній НОДА:
локальна кешована карта,
синхронізація через NATS.

Оптимально:

NODE1 = primary city-service
NODE2/NODE3 = read replicas cache + local geo-routing

9. HEALTHCHECK & METRICS¶

9.1. `GET /healthz`¶

{
  "status": "ok",
  "db": "ok",
  "geo_agent": "ok",
  "uptime_seconds": 21344
}

9.2. Prometheus metrics¶

presence_updates_total
active_subjects{region_id}
geo_queries_total
geo_inference_latency_ms_bucket
area_popularity{region_id, area_id}

10. LIVING MAP UI (FUTURE)¶

City Service підтримує:

API для реального часу (WebSocket/NATS),
2D-UI та 3D-UI клієнти:
Three.js / Babylon.js / Unity WebGL.

Плани:

місто як візуальна карта проектів,
агентські маршрути,
стан об'єктів, сервісів та microDAO,
heatmap активності.

11. SUMMARY¶

City Service (7001):

геопросторовий та "соціальний" шар DAARION,
формує логіку районів microDAO та проектних зон,
управляє присутністю користувачів і агентів,
інтегрується з DAGI Router, Geo-agent, ProjectBus, MicroDAO Service,
основа для 2D/3D карт та мультимодальних геоаналітик.

Це ключовий сервіс, який робить DAARION.city "живим містом", а не просто набором мікросервісів.