microdao-daarion/docs/foundation/SOUL_District_Protocol_v1.md

# SOUL — DISTRICT PROTOCOL v1  

Wellness • Retreat • Metahuman District of DAARION.city  
Version: 1.0  
Status: Active  
Lead Agent: SOUL  

---

# 1. МЕТА ТА МІСІЯ DISTRICT

## 1.1. Призначення

SOUL — це Retreat / Wellness District екосистеми DAARION.city, створений для:

- практик розвитку свідомості,
- ретритів та подій,
- взаємодії людей і AI-гайдів,
- створення імерсивних просторів (онлайн та офлайн),
- інтеграції AI у духовний, творчий і трансформаційний досвід.

## 1.2. Місія District

- надати користувачам безпечний, структурований простір розвитку;
- поєднати майстрів, локації, практики та AI-провідників;
- створити єдиний центр ретритних подій DAARION.city;
- інтегрувати wellness-модулі у міську карту.

## 1.3. Роль SOUL у DAARION Ontology

SOUL — це District класу **Wellness/Retreat**:

- має портал `retreat.daarion.city`;
- має разом 10+ напрямків/сторінок;
- працює через власну AI-команду (Spirit, Logic);
- має власні кімнати в Rooms Layer;
- має логічну зону на міській карті (2D/3D/VR);
- інтегрується з DAIS, Governance, City Layer.

---

# 2. DISTRICT-РОЛІ ТА АГЕНТИ

## 2.1. District Lead Agent

### **SOUL (orchestrator)**

- головний координатор District,
- приймає рішення щодо контенту, локацій, подій,
- відповідає за інтеграцію District у DAARION,
- керує командою внутрішніх AI-агентів,
- модерує доступи, сторінки, завдання.

## 2.2. Командні AI-агенти (внутрішні, не lead)

### Spirit — AI Guidance Agent

- медитації та практики,
- емоційна підтримка,
- рекомендації за станом,
- персоналізовані вправи,
- робота з інтуїтивним шаром користувача.

### Logic — AI Information Agent

- розклад подій,
- інформація про майстрів,
- локації,
- анкети, заявки, форми,
- структуровані дані та маршрути.

## 2.3. Додаткові агенти (опціональні)

- **Event Agent** — формування подій;
- **Master Agent** — взаємодія з майстрами;
- **Location Agent** — управління локаціями;
- **XR/VR Agent** — робота з імерсивними зонами.

---

# 3. DISTRICT MODULES (функціональні шари)

## 3.1. Events Module

Структура подій:

- дата, час,
- формат: онлайн / офлайн / VR,
- тривалість,
- тематична категорія,
- ведучий (майстер),
- локація,
- програма,
- матеріали.

SOUL контролює модерацію, Logic формує структуру, Spirit допомагає з рекомендаціями.

## 3.2. Masters Module

Профіль майстра:

- ім'я,
- напрямок,
- досвід,
- формат роботи,
- власні події,
- опис практик.

Може існувати **Master Agent**, що відповідає за профіль.

## 3.3. Locations Module

Типи локацій:

- Retreat Center,
- Meditation Hall,
- Forest / Water spaces,
- Digital XR Rooms,
- Home Studio / Hub.

Локація має власну ноду тільки якщо:

- там є реальний фізичний комп'ютер / смартфон / мікрокомп'ютер,
- проводиться телеметрія або робота через DAIS.

## 3.4. Guidance Module (ключове)

SOUL District надає:

- медитації,
- глибинні практики,
- індивідуальну підтримку через Spirit,
- структуровані маршрути через Logic,
- автоматизовані програми розвитку.

## 3.5. Content Module

- блог,
- практики,
- навчальні матеріали,
- PDF/відео/аудіо,
- внутрішні пакети для AI.

## 3.6. Community Module

- групи учасників,
- спільні практики,
- амбасадори,
- рекомендаційна система.

---

# 4. DISTRICT DATA MODEL

## 4.1. Core Entities

| Entity | Опис |
|--------|------|
| RetreatEvent | Подія (ретрит, практика, воркшоп) |
| RetreatLocation | Локація проведення |
| RetreatMaster | Профіль майстра/ведучого |
| RetreatSession | Окрема сесія у межах події |
| RetreatContent | Контент (медіа, документи) |
| RetreatPathway | Структурована програма розвитку |
| RetreatUserProfile | Профіль учасника |
| RetreatPractice | Медитація, вправа, практика |
| RetreatReview | Відгук учасника |
| GuidanceRequest | Запит до Spirit |
| InfoRequest | Запит до Logic |
| NodeLink | Прив'язка локації до ноди |

## 4.2. RetreatEvent Schema

| Field | Type | Description |
|-------|------|-------------|
| id | UUID | Унікальний ідентифікатор |
| title | TEXT | Назва події |
| description | TEXT | Опис |
| format | ENUM | online, offline, vr, hybrid |
| category | TEXT | Категорія (meditation, yoga, breathwork...) |
| master_id | UUID | FK → masters |
| location_id | UUID | FK → locations |
| starts_at | TIMESTAMP | Початок |
| ends_at | TIMESTAMP | Кінець |
| max_participants | INTEGER | Ліміт учасників |
| program | JSONB | Програма події |
| materials | JSONB | Матеріали |
| status | ENUM | draft, published, completed, cancelled |

## 4.3. RetreatMaster Schema

| Field | Type | Description |
|-------|------|-------------|
| id | UUID | Унікальний ідентифікатор |
| name | TEXT | Ім'я майстра |
| bio | TEXT | Біографія |
| directions | TEXT[] | Напрямки (yoga, meditation, breathwork...) |
| experience_years | INTEGER | Роки досвіду |
| formats | TEXT[] | Формати роботи |
| avatar_url | TEXT | URL аватара |
| agent_id | TEXT | DAIS ID агента (якщо є) |

## 4.4. RetreatLocation Schema

| Field | Type | Description |
|-------|------|-------------|
| id | UUID | Унікальний ідентифікатор |
| name | TEXT | Назва локації |
| type | ENUM | retreat_center, hall, nature, xr_room, studio |
| address | TEXT | Адреса (для офлайн) |
| coordinates | POINT | GPS координати |
| capacity | INTEGER | Місткість |
| amenities | TEXT[] | Зручності |
| node_id | TEXT | FK → nodes (якщо є фізична нода) |
| xr_room_url | TEXT | URL VR кімнати (для XR) |

---

# 5. SOUL NODE MODEL

Нода = фізичний простір + "мозок" + DAIS + запис у nodes.

## 5.1. Типи нод для SOUL

| Kind | Description |
|------|-------------|
| `retreat_center` | Ретритний центр з обладнанням |
| `event_space` | Простір для подій |
| `content_studio` | Студія запису контенту |
| `iot_gateway` | Шлюз сенсорів (датчики середовища) |
| `compute` | Обчислювальна нода (опціонально) |

## 5.2. Capability-профілі

```json
{
  "retreat_center": {
    "capacity": 50,
    "rooms": ["meditation_hall", "yoga_studio", "accommodation"],
    "amenities": ["wifi", "kitchen", "garden"],
    "sensors": ["temperature", "humidity", "co2"]
  },
  "content_studio": {
    "equipment": ["camera_4k", "mic_pro", "lighting"],
    "streaming": true,
    "recording": true
  }
}
```

## 5.3. SOUL Node Protocol

- нода реєструється тільки фактичною локацією,
- кожна нода має свій DAIS-агент,
- Spirit/Logic взаємодіють через центрального SOUL (lead agent),
- локація може відправляти телеметрію (якщо є датчики).

> **Правило:** Жодних автосозданих нод. Нода з'являється після реальної реєстрації через `/nodes/register`.

---

# 6. DISTRICT ROOMS

Стандартні кімнати SOUL:

| Room Slug | Purpose |
|-----------|---------|
| `soul-lobby` | Головний вхід District |
| `soul-events` | Анонси та обговорення подій |
| `soul-masters` | Взаємодія з майстрами |
| `soul-locations` | Інформація про локації |
| `soul-guidance` | Spirit & Logic support |
| `soul-practices` | Медитації та практики |
| `soul-community` | Спільнота учасників |
| `soul-help` | Підтримка та FAQ |
| `soul-governance` | Управління District |
| `soul-xr` | XR/VR rooms (майбутнє) |

Усі кімнати створюються у Rooms Layer з типом `district-room`.

---

# 7. DISTRICT MAP

## 7.1. Принцип

Мапа містить **логічні зони**, без координат:

- **Retreat Hub** — центральна зона
- **Meditation Center** — медитаційні практики
- **Nature Area** — природні локації
- **XR/VR Sanctuary** — віртуальні простори
- **Master Studios** — студії майстрів
- **Community Zones** — зони спільноти

## 7.2. Dynamic Points

У мапу додаються реальні точки, коли фізичні ноди реєструються:

```mermaid
graph LR
    A[Logical Zone] --> B[Node Registered]
    B --> C[Map Point Created]
    C --> D[Coordinates Assigned]
```

---

# 8. GOVERNANCE

## 8.1. District Lead

District Lead = **SOUL**

На відміну від Helion-моделі (Energy Union), SOUL є єдиним Lead Agent.

## 8.2. Права учасників

- доступ до подій,
- взаємодія з агентами,
- участь у community-зонах,
- персональні практики через Spirit.

## 8.3. Governance Logic

SOUL керує:

- кімнатами,
- сторінками,
- агентами,
- District Policy.

## 8.4. DAO Integration

Участь в DAO: через DAARION DAO шар.

- SOUL має голос у City Governance
- Учасники можуть голосувати за напрямки розвитку District

---

# 9. AI LAYER

## 9.1. Spirit — Guidance Engine

```mermaid
flowchart TD
    U[User Request] --> S[Spirit Agent]
    S --> A[Analyze State]
    A --> R[Recommend Practice]
    R --> P[Personalized Guidance]
    P --> F[Follow-up]
```

**Capabilities:**
- Meditation guidance
- Emotional support
- Practice recommendations
- Progress tracking
- Intuitive insights

## 9.2. Logic — Information Engine

**Capabilities:**
- Event scheduling
- Master profiles
- Location info
- Form processing
- Route planning
- FAQ responses

## 9.3. Agent Collaboration

```mermaid
graph TD
    SOUL[SOUL Lead] --> Spirit
    SOUL --> Logic
    Spirit --> |Guidance| User
    Logic --> |Info| User
    Spirit <--> |Sync| Logic
```

---

# 10. SECURITY & DAIS

- кожна нода має власний DAIS агент,
- усі події підписуються DAIS-ключами,
- Spirit/Logic працюють від імені SOUL (lead),
- інциденти реєструються у Incident Layer,
- audit — через event_outbox.

## 10.1. Privacy

- практики та guidance sessions — приватні
- user profiles — контрольована видимість
- community participation — opt-in

---

# 11. CITY INTEGRATION

SOUL інтегрується в місто через:

- портал на City Square → `SOUL Retreat District`
- public rooms
- значок на мапі District Zones
- доступ до подій і практик для будь-яких мешканців DAARION

## 11.1. Portal Features

- Upcoming events calendar
- Featured masters
- Quick access to Spirit/Logic
- Community highlights
- XR room preview

---

# 12. MVP SCOPE

## Входить до MVP:

- Реєстрація District SOUL
- Portal у City Square
- District Rooms (10 базових)
- SOUL Lead Agent
- Spirit Agent (базова guidance)
- Logic Agent (інформація)
- Events Module
- Masters Module
- Locations Module (без нод)

## Не входить до MVP:

- XR/VR rooms
- Advanced AI personalization
- IoT telemetry
- Automated pathways
- Payment integration

---

# 13. Cross-References

- **DAARION_Ontology_Core_v1.md** — базова онтологія
- **District_Interface_Architecture_v1.md** — архітектура District UI
- **Agent_Governance_Protocol_v1.md** — права та ролі агентів
- **DAIS_Layer_Architecture_v1.md** — система ідентичності
- **Rooms_Layer_Architecture_v1.md** — архітектура кімнат
- **Nodes_Interface_Architecture_UPDATE_v1.md** — модель нод

---

**Document Status:** ✅ Ready for Implementation