Skip to content

# 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:

    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)

    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

    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

    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 може виставити свій портал у дистрикт:

    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

    -- 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

    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

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

## 7.2. District Core-team Agents

    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:

    -- 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.

    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 з містом:

    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:

    // Публікація новини в 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

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

# 10. District Interface API

## 10.1. District Routes

    // 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

    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

    // 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

    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

    // 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