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:

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