# Rooms_Layer_Architecture_v1.md

## DAARION.city — Rooms Layer & Shared City Space

**Version:** 1.0  
**Status:** Foundation Spec (Non-Breaking)  
**Scope:** City rooms, MicroDAO rooms, District platforms, 2D/3D map, public fronts, inter-DAO interaction

---

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

Визначити, що таке «Кімнати Міста» та загалом Rooms Layer у DAARION.city:

* як влаштовані простори міста (City Hub, City Square),
* як працюють кімнати MicroDAO/District,
* як MicroDAO можуть мати публічні front-offices у місті,
* як це все відображається в 2D-мапі і майбутньому 3D метавсесвіті,
* як Rooms Layer інтегрується з MicroDAO Interface і City Layer.

---

# 1. Базова модель

Rooms Layer працює на трьох рівнях:

1. **City Hub (root MicroDAO DAARION)** — публічні міські кімнати і фронт-офіси.
2. **MicroDAO Space** — внутрішні кімнати, робочі простори, проєкти, core-team.
3. **District Space** — платформи, міні-міста з підлеглими MicroDAO.

Функція Rooms Layer — універсальна: та сама структура для всіх рівнів, але з різним контекстом.

---

# 2. Поняття Rooms Layer

## Room

* чат / канал / робочий простір;
* має `owner_type` (`city | microdao | district | agent`), `owner_id`;
* має `space_scope` (`city | microdao | district`);
* має `visibility` (`private | members | public-city | public-global`);
* опціонально `matrix_room_id`.

## Location

* 2D map tile / координати;
* 3D anchor (будівля, кіоск);
* fallback — список/каталог.

## Portal

* кімната-«точка входу» MicroDAO/District у міське середовище;
* `is_portal=true`, `portal_target_microdao_id`.

---

# 3. Типи кімнат

1. **City Room** — належить root MicroDAO, `space_scope='city'`.
2. **DAO Room** — внутрішні кімнати MicroDAO (`space_scope='microdao'`).
3. **Public Front Room** — кімната MicroDAO з `space_scope='city'`.
4. **District Room** — кімнати District-платформи (`space_scope='district'`).
5. **Agent Room / Booth** — публічні кімнати агентів (Helion, ERP, DARIO).
6. **Event Room** — тимчасові/постійні кімнати подій.

---

# 4. Модель видимості

* `owner_type`, `owner_id`.
* `visibility`: `private`, `members`, `public-city`, `public-global`.
* `space_scope`: `city`, `microdao`, `district`.

Приклад front-office Energyunion:

```
owner_type = microdao
owner_id = energyunion
visibility = public-city
space_scope = city
is_portal = true
portal_target_microdao_id = energyunion
```

---

# 5. City Hub як спільний простір

* Місто — місце, де можуть бути присутні всі MicroDAO, District, агенти.
* Кожне MicroDAO може зареєструвати портали/кімнати у City Hub.
* Публічні агенти (Helion, ERP, DARIO) мають свої кіоски в місті.

---

# 6. Інтерфейсні рівні

## 6.1. City Rooms UI

* `/city/rooms` — список / карта публічних кімнат.
* `/city` — City Square зі слотами кімнат/порталів.
* `/city/map` — 2D карта.

## 6.2. MicroDAO Rooms UI

* `/microdao/{id}/rooms` — внутрішні кімнати, публікація front-room (прапорець `publish_to_city`).

## 6.3. District Rooms UI

* `/district/{id}/rooms` — кімнати платформи, підлеглі DAO.

---

# 7. 2D/3D підтримка

* Кожна кімната може мати `map_x`, `map_y`, `zone`.
* 3D-режим використовує `mesh_id`, `3d_position`.
* City Square → набір кімнат/порталів, які відображаються як плитки / кіоски.

---

# 8. Модель даних (чернетка)

```sql
rooms (
  id text primary key,
  owner_type text not null,
  owner_id text not null,
  type text not null, -- city-room | dao-room | front-room | agent-room | event-room
  space_scope text not null, -- city | microdao | district
  visibility text not null, -- private | members | public-city | public-global
  matrix_room_id text null,
  is_portal boolean not null default false,
  portal_target_microdao_id text null,
  map_x integer null,
  map_y integer null,
  zone text null,
  metadata jsonb not null default '{}'::jsonb,
  created_at timestamptz not null default now()
);
```

---

# 9. Governance

* City rooms створює root MicroDAO або civic-агенти з правами.
* DAO rooms створює оркестратор/команда.
* Front offices публікує Оркестратор або core-team.
* District rooms — оркестратор District.

---

# 10. MVP Scope

* Реєстр City Rooms.
* API: `GET /city/rooms`, `GET /city/portals`, `POST /microdao/{id}/rooms`.
* Мінімальний UI: список кімнат, дві front-room (Energyunion, GREENFOOD).
* Matrix-зв’язок для кімнат.

---

# 11. Підсумок

Rooms Layer уніфікує всі простори DAARION.city:

* місто як спільний простір,
* MicroDAO як власні робочі простори,
* District як платформи,
* агенти як власники кімнат.

Це база для 2D/3D DAARION.space.