microdao-daarion/docs/foundation/District_Interface_Architecture_v1.md

# District_Interface_Architecture_v1.md

## DAARION.city — District Layer & Platform Interface Architecture

**Version:** 1.0  
**Status:** Foundation Spec (MVP)  
**Scope:** Архітектура дистриктів (платформ) у DAARION.city: District Space, портали в місті, взаємодія з MicroDAO, Campus Map, кімнати District-рівня, District Agents, золотий трикутник (City → District → MicroDAO).

---

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

Цей документ визначає **повну архітектуру District Layer** — третього ключового простору DAARION.city поруч з:

- **City Layer** (місто),
- **MicroDAO Layer** (організації, команди).

District — це **платформа / мегаспільнота / галузевий район** у DAARION.city.

Документ визначає:

- District Space (інтерфейс дистрикту),
- District Dashboard,
- District Rooms,
- District Campus Map (2D та майбутній 3D),
- District Agents (платформні агенти),
- портал дистрикту у місті,
- підлеглі MicroDAO,
- архітектуру публічних зон,
- взаємодію з City та MicroDAO interface,
- зв'язок з DAIS, Agents та Nodes.

---

# 1. Поняття District у DAARION.city

## 1.1. District — це MicroDAO з розширеним типом

```
microdao.type = 'district'
```

Рівень District додає:

- власний інтерфейс «платформи»,
- власні кімнати,
- власну карту (Campus Map),
- публічний портал у City Square,
- підлеглі MicroDAO,
- своїх агентах-представників,
- власне міні-місто всередині великого міста.

## 1.2. Приклади дистриктів

| District | Галузь | Lead Agent | Статус |
|----------|--------|------------|--------|
| **Energyunion** | Енергетика | Helion | ✅ Активний |
| **GREENFOOD** | Агро/ERP | ERP-Agent | ✅ Активний |
| **Health** | Здоров'я | — | 🔜 Planned |
| **Logistics** | Логістика | — | 🔜 Planned |
| **Robotics** | Роботехніка | — | 🔜 Planned |

---

# 2. District Space — окрема екосистема всередині міста

## 2.1. District Space = міні-місто всередині DAARION.city

Кожен District має свою:

- **центральну площу** (District Center),
- **групу кімнат** (District Rooms),
- **власних публічних агентів** (District Agents),
- **кабінети команди** (Core-Team Console),
- **підлеглі MicroDAO** (Sub-DAOs),
- **власну карту** (Campus Map),
- **корпоративні/галузеві сервіси**,
- **власні ноди** (District Infrastructure).

## 2.2. Ієрархія просторів

```
DAARION.city (City Layer)
    │
    ├── City Square (центральна площа)
    │
    ├── District: Energyunion
    │   ├── District Center
    │   ├── District Rooms
    │   ├── Sub-DAO: SolarFarm1
    │   ├── Sub-DAO: WindPark2
    │   └── Campus Map
    │
    ├── District: GREENFOOD
    │   ├── District Center
    │   ├── District Rooms
    │   ├── Sub-DAO: Farm1
    │   └── Campus Map
    │
    └── Standard MicroDAO (без District)
```

Умовно:
> **City** = глобальне місто  
> **District** = район площею 100+ будівель  
> **MicroDAO** = будівля / організація всередині району

---

# 3. District Portal у місті

## 3.1. Портал на City Square

Кожен District має **публічний кіоск/вітрину** на City Square:

```yaml
rooms:
  - id: district-energyunion-front
    owner_type: 'microdao'
    owner_id: 'energyunion'
    type: 'front-room'
    space_scope: 'city'
    visibility: 'public-city'
    is_portal: true
    portal_target_microdao_id: 'energyunion'
    primary_agent_id: 'helion'
    map_x: 100
    map_y: 50
    zone: 'energy-sector'
```

## 3.2. Що відображається на порталі

| Елемент | Опис |
|---------|------|
| District Name | Назва дистрикту |
| District Logo | Логотип/аватар |
| Lead Agent | Helion, ERP-Agent |
| Public Rooms | Новини, Help, FAQ |
| Stats | Кількість DAO, агентів |
| "Увійти" | Кнопка переходу в District Space |

## 3.3. Візуальне представлення

```
┌─────────────────────────────────┐
│        CITY SQUARE              │
│                                 │
│  ┌─────────┐    ┌─────────┐    │
│  │ENERGY   │    │GREEN    │    │
│  │UNION    │    │FOOD     │    │
│  │ 🔋      │    │ 🌿      │    │
│  │ Helion  │    │ ERP     │    │
│  │[Увійти] │    │[Увійти] │    │
│  └─────────┘    └─────────┘    │
│                                 │
│       [DARIO]  [DARIA]         │
└─────────────────────────────────┘
```

---

# 4. District Dashboard

## 4.1. URL Structure

```
/district/{id}
/district/{id}/dashboard
/district/{id}/rooms
/district/{id}/subdaos
/district/{id}/map
/district/{id}/agents
/district/{id}/nodes
/district/{id}/events
```

## 4.2. Елементи District Dashboard

### 4.2.1. Primary Agent (District Lead Agent)

```typescript
interface DistrictDashboard {
  primaryAgent: {
    id: string;        // 'helion'
    name: string;      // 'Helion'
    role: string;      // 'District Lead'
    avatar: string;
    status: 'online' | 'busy' | 'offline';
  };
}
```

Приклади:
- **Helion** для Energyunion
- **ERP-Agent** для GREENFOOD

### 4.2.2. Team Agents

| Role | Agent | Функція |
|------|-------|---------|
| Business Lead | BusinessBot | Бізнес-питання |
| Tech Lead | TechBot | Технічна підтримка |
| Analyst | DataBot | Аналітика галузі |
| Integrations | BridgeBot | Інтеграції |

### 4.2.3. District Stats

```typescript
interface DistrictStats {
  subDaoCount: number;      // Кількість підлеглих MicroDAO
  activeAgents: number;     // Активні агенти платформи
  nodeCount: number;        // Кількість нод
  memberCount: number;      // Загальна кількість учасників
  eventsThisWeek: number;   // Активність
  gpuCapacity: string;      // "120 TFLOPS"
}
```

### 4.2.4. District Rooms Preview

- Центральна кімната
- Новини
- Help
- Події
- Аналітика галузі

### 4.2.5. Campus Map Preview

- Мініатюра 2D-карти
- Позиції Sub-DAOs
- Кнопка "Відкрити повну карту"

### 4.2.6. Sub-DAOs List

```typescript
interface SubDAO {
  id: string;
  name: string;
  status: 'active' | 'pending' | 'archived';
  memberCount: number;
  primaryAgent: string;
  frontRoomId?: string;
}
```

### 4.2.7. District Nodes

- Список нод платформи
- GPU/CPU ресурси
- Статус здоров'я

---

# 5. District Rooms (кімнати дистрикту)

## 5.1. Internal Rooms (внутрішні)

| Room ID | Назва | Доступ |
|---------|-------|--------|
| `{district}-strategy` | Стратегія | Core-team |
| `{district}-tech` | Технічна команда | Core-team |
| `{district}-business` | Бізнес-команда | Core-team |
| `{district}-docs` | Документи | Members |

## 5.2. Public Rooms

| Room ID | Назва | Доступ |
|---------|-------|--------|
| `{district}-news` | Новини | Public |
| `{district}-help` | Підтримка | Public |
| `{district}-events` | Події | Public |
| `{district}-faq` | FAQ | Public |
| `{district}-discussions` | Обговорення | Members |

## 5.3. Portal Rooms (для Sub-DAOs)

Кожне підлегле MicroDAO може виставити свій **портал у дистрикт**:

```yaml
rooms:
  - id: subdao-solarfarm1-front
    owner_type: 'microdao'
    owner_id: 'solarfarm1'
    type: 'front-room'
    space_scope: 'district'
    visibility: 'public-city'
    is_portal: true
    portal_target_microdao_id: 'solarfarm1'
```

## 5.4. Room Data Model

```sql
-- District rooms мають space_scope = 'district'
INSERT INTO rooms (id, owner_type, owner_id, type, space_scope, visibility, name, primary_agent_id)
VALUES 
  ('energyunion-center', 'microdao', 'energyunion', 'district-room', 'district', 'members', 'Energy Center', 'helion'),
  ('energyunion-news', 'microdao', 'energyunion', 'district-room', 'district', 'public-city', 'Energy News', 'helion'),
  ('energyunion-help', 'microdao', 'energyunion', 'district-room', 'district', 'public-city', 'Energy Help', 'helion');
```

---

# 6. District Campus Map (2D)

## 6.1. Концепція

Карта дистрикту — це:

- окрема 2D-мапа платформи,
- подібна до City Map, але локальна,
- центральна площа District Center,
- розташування підлеглих MicroDAO,
- інфраструктурні ноди платформи.

## 6.2. Елементи карти

```
┌────────────────────────────────────────────┐
│            ENERGYUNION CAMPUS              │
│                                            │
│    ┌─────┐         ┌─────┐                │
│    │Solar│         │Wind │                │
│    │Farm1│         │Park2│                │
│    └──┬──┘         └──┬──┘                │
│       │               │                    │
│       └───────┬───────┘                    │
│               │                            │
│        ┌──────┴──────┐                     │
│        │   DISTRICT  │                     │
│        │   CENTER    │                     │
│        │   [Helion]  │                     │
│        └─────────────┘                     │
│                                            │
│    ┌─────┐    ┌─────┐    ┌─────┐          │
│    │Node1│    │Node2│    │Node3│          │
│    │ GPU │    │ GPU │    │ IoT │          │
│    └─────┘    └─────┘    └─────┘          │
│                                            │
│    [NEWS]  [HELP]  [EVENTS]  [EXIT→CITY]  │
└────────────────────────────────────────────┘
```

## 6.3. Map Data Model

```typescript
interface DistrictMapElement {
  id: string;
  type: 'subdao' | 'room' | 'node' | 'agent' | 'portal';
  x: number;
  y: number;
  zone: string;
  label: string;
  icon: string;
  targetId: string;  // ID для переходу
}

interface DistrictMap {
  districtId: string;
  width: number;
  height: number;
  zones: string[];
  elements: DistrictMapElement[];
  background: string;  // SVG або image
}
```

---

# 7. District Agents

## 7.1. District Lead Agent (primary_agent)

Головний агент дистрикту:

| District | Lead Agent | Роль |
|----------|------------|------|
| Energyunion | **Helion** | Energy Platform Lead |
| GREENFOOD | **ERP-Agent** | Agro Platform Lead |

```typescript
interface DistrictLeadAgent {
  id: string;
  name: string;
  districtId: string;
  role: 'district-lead';
  serviceScope: 'district';
  capabilities: string[];
  publicProfile: boolean;
}
```

## 7.2. District Core-team Agents

```typescript
const districtCoreTeam = [
  { role: 'District CTO', agent: 'district-cto-agent' },
  { role: 'District Analyst', agent: 'district-analyst-agent' },
  { role: 'District Manager', agent: 'district-manager-agent' },
  { role: 'District Integrations', agent: 'district-bridge-agent' },
  { role: 'District Security', agent: 'district-security-agent' },
];
```

## 7.3. Public-facing Agents

Агенти, доступні для клієнтів/учасників платформи:

- Відповідають у публічних кімнатах
- Обробляють запити з City Square
- Консультують щодо сервісів дистрикту

## 7.4. Agent Hierarchy

```
District Lead Agent (Helion)
    │
    ├── District Core-Team
    │   ├── CTO Agent
    │   ├── Analyst Agent
    │   └── Security Agent
    │
    └── Sub-DAO Agents
        ├── SolarFarm1 Orchestrator
        └── WindPark2 Orchestrator
```

---

# 8. District → MicroDAO зв'язок

## 8.1. Підлеглі MicroDAO

District володіє набором підлеглих MicroDAO:

```sql
-- MicroDAO з parent_microdao_id = district_id
SELECT * FROM microdaos 
WHERE parent_microdao_id = 'energyunion';
```

## 8.2. Що отримує Sub-DAO

| Перевага | Опис |
|----------|------|
| District Rooms | Доступ до кімнат платформи |
| Shared Marketplace | Спільний ринок послуг |
| Campus Map | Позиція на карті дистрикту |
| Core-team Support | Підтримка від District агентів |
| Shared Nodes | Доступ до інфраструктури |

## 8.3. Sub-DAO Front-room

MicroDAO може мати:
- свій front-room у District Center,
- свого агента-представника,
- позицію на Campus Map.

```yaml
subdao_front_room:
  id: 'solarfarm1-front-in-district'
  owner_id: 'solarfarm1'
  space_scope: 'district'
  parent_district_id: 'energyunion'
  map_x: 50
  map_y: 30
```

---

# 9. District → City зв'язок

## 9.1. Portal на City Square

Головний спосіб взаємодії District з містом:

```typescript
interface DistrictCityPortal {
  districtId: string;
  portalRoomId: string;
  position: { x: number; y: number };
  zone: 'energy-sector' | 'agro-sector' | 'health-sector';
  visibility: 'public-city';
  primaryAgent: string;
}
```

## 9.2. City News Integration

Новини та події District потрапляють до City News:

```typescript
// Публікація новини в City
await publishToCityNews({
  source: 'district',
  sourceId: 'energyunion',
  title: 'Нова сонячна станція',
  content: '...',
  agentId: 'helion',
});
```

## 9.3. District Agents у City

District Lead Agents доступні як публічні агенти:
- Helion відображається в City Agents каталозі
- Можна поговорити з Helion з City Square

## 9.4. District Nodes у City Infrastructure

```typescript
// Ноди дистрикту видимі в City Infrastructure View
const districtNodes = await getNodesByMicrodao('energyunion');
// Відображаються в /city/infrastructure
```

---

# 10. District Interface API

## 10.1. District Routes

```typescript
// GET /api/v1/districts
// GET /api/v1/districts/:id
// GET /api/v1/districts/:id/dashboard
// GET /api/v1/districts/:id/rooms
// GET /api/v1/districts/:id/subdaos
// GET /api/v1/districts/:id/map
// GET /api/v1/districts/:id/agents
// GET /api/v1/districts/:id/nodes
// GET /api/v1/districts/:id/stats
// POST /api/v1/districts/:id/subdaos (add Sub-DAO)
// POST /api/v1/districts/:id/rooms (create room)
```

## 10.2. District Dashboard API

```typescript
interface DistrictDashboardResponse {
  district: {
    id: string;
    name: string;
    type: 'district';
    primaryAgent: Agent;
    teamAgents: Agent[];
  };
  stats: DistrictStats;
  rooms: Room[];
  subdaos: Microdao[];
  map: DistrictMap;
  nodes: Node[];
  recentEvents: Event[];
}
```

## 10.3. District Map API

```typescript
// GET /api/v1/districts/:id/map
interface DistrictMapResponse {
  districtId: string;
  name: string;
  dimensions: { width: number; height: number };
  zones: Zone[];
  elements: MapElement[];
  connections: Connection[];
}
```

---

# 11. District Interface: UI Structure

## 11.1. District Navigation

```typescript
const districtNavItems = [
  { path: '/district/:id', label: 'Dashboard', icon: '🏠' },
  { path: '/district/:id/rooms', label: 'Rooms', icon: '💬' },
  { path: '/district/:id/subdaos', label: 'Sub-DAOs', icon: '🏢' },
  { path: '/district/:id/map', label: 'Campus Map', icon: '🗺️' },
  { path: '/district/:id/agents', label: 'Agents', icon: '🤖' },
  { path: '/district/:id/nodes', label: 'Nodes', icon: '🖥️' },
  { path: '/district/:id/events', label: 'Events', icon: '📅' },
];
```

## 11.2. District Center (головна сторінка)

```
┌─────────────────────────────────────────────────┐
│  [← City]    ENERGYUNION DISTRICT    [Settings] │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌──────────────┐  ┌─────────────────────────┐ │
│  │   HELION     │  │     District Stats      │ │
│  │   🔋         │  │  Sub-DAOs: 12           │ │
│  │  Lead Agent  │  │  Agents: 45             │ │
│  │  [Chat]      │  │  Nodes: 8               │ │
│  └──────────────┘  │  Members: 234           │ │
│                    └─────────────────────────┘ │
│                                                 │
│  ┌─────────────────────────────────────────────┐│
│  │              CAMPUS MAP (preview)           ││
│  │    [Solar] [Wind] [Center] [Storage]        ││
│  │            [View Full Map →]                ││
│  └─────────────────────────────────────────────┘│
│                                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │📰 News   │ │❓ Help   │ │📅 Events │        │
│  └──────────┘ └──────────┘ └──────────┘        │
│                                                 │
│  Sub-DAOs:                                      │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │SolarFarm│ │WindPark │ │Storage  │ [+Add]   │
│  └─────────┘ └─────────┘ └─────────┘           │
└─────────────────────────────────────────────────┘
```

---

# 12. District Registration & Lifecycle

## 12.1. Як створюється District

Дистрикт може створити:

1. **Оркестратор MicroDAO** — промоутить своє DAO до District
2. **City-level процес** — рішення DAARWIZZ / City Governance
3. **Автоматичний алгоритм** — на основі активності та масштабу

## 12.2. Promotion Flow

```
MicroDAO (type='standard')
    │
    ├── Виконано умови:
    │   ├── 5+ Sub-DAOs
    │   ├── 100+ учасників
    │   ├── Активний 3+ місяці
    │   └── Governance approval
    │
    ▼
MicroDAO (type='district')
    │
    ├── Отримує:
    │   ├── District Dashboard
    │   ├── Campus Map
    │   ├── City Portal
    │   └── District Agent roles
```

## 12.3. Event

```typescript
// dagion.microdao.promoted_to_district
{
  microdaoId: 'energyunion',
  promotedByAgentId: 'daarwizz',
  parentMicrodaoId: null,
  timestamp: '2025-11-29T23:30:00Z'
}
```

---

# 13. MVP Scope

## 13.1. Обов'язково для MVP

| Компонент | Статус |
|-----------|--------|
| District Dashboard | 🔜 Required |
| District Rooms (2-3 public) | 🔜 Required |
| District Lead Agent | 🔜 Required |
| District Portal на City Square | 🔜 Required |
| Список підлеглих MicroDAO | 🔜 Required |
| District Campus Map (базова 2D) | 🔜 Required |
| Public-facing Agent (Helion/ERP) | 🔜 Required |

## 13.2. Після MVP

| Компонент | Priority |
|-----------|----------|
| Інтерактивна 2D карта | Medium |
| 3D Campus | Low |
| District Events system | Medium |
| Міні-економіка дистрикту | Low |
| Графи взаємодії DAO | Low |
| District-to-District | Low |

---

# 14. Зв'язок з іншими документами

| Документ | Зв'язок |
|----------|---------|
| `DAARION_Ontology_Core_v1.md` | District = MicroDAO type='district' |
| `Rooms_Layer_Architecture_v1.md` | District Rooms, space_scope='district' |
| `City_Interface_Architecture_v1.md` | District Portal на City Square |
| `MicroDAO_Interface_Architecture_v1.md` | Sub-DAO структура |
| `Agents_Interface_Architecture_v1.md` | District Lead Agent, team agents |
| `Nodes_Interface_Architecture_v1.md` | District Nodes |
| `microdao_Data_Model_UPDATE_v1.md` | parent_microdao_id, dao_type |

---

# 15. Підсумок

Цей документ визначає:

- **структуру District Space** — міні-місто в місті,
- **District Dashboard** — центр керування платформою,
- **District Rooms** — кімнати різних рівнів доступу,
- **District Campus Map** — 2D карта дистрикту,
- **District Agents** — Lead Agent + Core-team,
- **Portal у City Square** — вітрина в місті,
- **Sub-DAOs** — підлеглі MicroDAO,
- **API та UI** — маршрути та інтерфейс.

## Золотий трикутник DAARION.city:

```
        ┌─────────────┐
        │    CITY     │
        │  (глобальне │
        │   місто)    │
        └──────┬──────┘
               │
    ┌──────────┼──────────┐
    │          │          │
┌───▼───┐  ┌───▼───┐  ┌───▼───┐
│DISTRICT│  │DISTRICT│  │DISTRICT│
│Energy  │  │Green   │  │Health  │
│Union   │  │Food    │  │        │
└───┬────┘  └───┬────┘  └───┬────┘
    │           │           │
┌───▼───┐  ┌───▼───┐  ┌───▼───┐
│MicroDAO│  │MicroDAO│  │MicroDAO│
│Solar1  │  │Farm1   │  │Clinic1 │
└────────┘  └────────┘  └────────┘
```

**DAARION.city → District → MicroDAO**  
**місто → район → організація**

District — це «галузевий космос» у місті, що об'єднує десятки MicroDAO під спільною платформою.

---

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

Готовий до наступного фундаментального документа:
- **DAIS_Layer_Architecture_v1.md**, або
- **Agent_Governance_Protocol_v1.md**