refine development architecture diagram with updated content and structure

Co-authored-by: Cursor <cursoragent@cursor.com>

.gitignore

@@ -0,0 +1 @@
+.env.local

architecture/development-architecture.mmd

@@ -0,0 +1,144 @@
+graph TD
+    subgraph Mission_Node [Структура миссии]
+        Mission[Миссия] --> MissionId[Id, type: free, training, control]
+        Mission --> MissionConfig[конфиг миссии]
+        MissionConfig --> MissionSettings[настройки миссии]
+        MissionSettings --> StartStep[стартовый шаг]
+    end
+
+    subgraph Asset_Config [Конфиги ассетов]
+        AssetConfig --> ModelConfig[конфиг моделей]
+        ModelConfig --> InteractiveConfig[Конфиг интерактивных объектов]
+        InteractiveConfig --> InteractiveList[Список объектов]
+        AssetConfig --> InitialStateConfig[конфиг начальных состояний]
+    end
+
+    %% Горизонтальные связи (пунктиром для ясности)
+    ModelLoading[Загрузка модели]
+
+    %% Верхний ряд систем
+    subgraph Highlight_Group [Подсветка мешей]
+        Highlight[Подсветка]
+        Highlight --> TriggerObject
+        TriggerObject --> HighlightObjects[Объекты для подсветки]
+        HighlightObjects --> ImproveHighlight[Улучшать визуализацию подсветки]
+    end
+
+    subgraph Position_Group [Позиционирование анимированное]
+        SmoothPos[Позиционирование анимированное]
+        SmoothPos --> Coord1[Координаты]
+        Coord1 --> Velocity1[Velocity]
+    end
+
+    subgraph Inertia_Group [Функционал инерции]
+        SmoothAcceleration[Плавный разгон]
+        SmoothAcceleration --> SmoothAttenuation[Плавное затухание]
+    end
+
+    subgraph Rotation_Group [Вращение анимированное]
+        SmoothRot[Вращение анимированное]
+        SmoothRot --> Coord2[Координаты]
+        Coord2 --> Velocity2[Velocity]
+    end
+
+    subgraph Player_Group [Игрок]
+        Player[Игрок]
+        Player --> Camera[Камера]
+        Camera --> CameraSettings[Настройки камеры]
+        Camera --> Collisions[Коллизии]
+    end
+
+    subgraph Anchor_Group [Якоря]
+        POI[точки интереса на моделях]
+        POI --> PathBuild[Строить путь по точкам от игрока]
+        PathBuild --> ModelDisplay[Какие модели отображать]
+    end
+
+    %% Отдельный блок
+    subgraph Teleport_Group [Телепорты]
+        Teleports[Телепорты]
+    end
+
+    subgraph World_Group [Функционал мира legacy parity]
+        ZoneState[Зоны и переключение зон]
+        RouteMap[Route map overlay]
+        VisibilityRules[Правила видимости моделей]
+        ZoneState --> RouteMap
+        RouteMap --> VisibilityRules
+    end
+
+    subgraph Scenario_Group [Сценарный движок]
+        ScenarioRuntime[Runtime шагов сценария]
+        PromiseEvents[События click input hotkey timeout any]
+        Branching[Ветвления и переходы шагов]
+        HintSystem[Система подсказок и фокуса камеры]
+        ScenarioRuntime --> PromiseEvents
+        PromiseEvents --> Branching
+        Branching --> HintSystem
+    end
+
+    subgraph EmbeddedUi_Group [Встроенный UI в 3D]
+        SvgScreens[SVG экраны на мешах]
+        HtmlMeshUi[HTML mesh интерфейсы]
+        MeshPopup[Popup выбора состояния объекта]
+        SvgScreens --> HtmlMeshUi
+        HtmlMeshUi --> MeshPopup
+    end
+
+    subgraph SessionProgress_Group [Прогресс и аналитика]
+        DomainSnapshot[Снапшот доменного состояния]
+        StepProgress[Прогресс шага и сценария]
+        ErrorRecovery[Восстановление после ошибок]
+        DomainSnapshot --> StepProgress
+        StepProgress --> ErrorRecovery
+    end
+
+    subgraph ExternalIntegration_Group [Интеграция внешней оболочки]
+        TrainerWrapper[Контракт trainer wrapper]
+        ExerciseSession[Связка exercise session user]
+        CompletionApi[Завершение и отправка результата]
+        TrainerWrapper --> ExerciseSession
+        ExerciseSession --> CompletionApi
+    end
+
+    subgraph MigrationRoadmap_Group [Путь реализации]
+        P0[P0 Игрок и интерактив]
+        P1[P1 Мир и маршруты]
+        P2[P2 Сценарии и прогресс]
+        P0 --> P1
+        P1 --> P2
+    end
+
+    Mission_Node --> ModelLoading
+    MissionConfig --> Asset_Config
+    ModelLoading --> Highlight_Group
+    Highlight_Group --> Position_Group
+    Position_Group --> Rotation_Group
+    Rotation_Group --> Inertia_Group
+    Inertia_Group --> Player_Group
+    Player_Group --> Anchor_Group
+    Anchor_Group --> Teleport_Group
+    Teleport_Group --> World_Group
+    MissionSettings --> Scenario_Group
+    TriggerObject --> EmbeddedUi_Group
+    Scenario_Group --> SessionProgress_Group
+    SessionProgress_Group --> ExternalIntegration_Group
+
+    Player_Group --> P0
+    EmbeddedUi_Group --> P0
+    World_Group --> P1
+    Scenario_Group --> P2
+    SessionProgress_Group --> P2
+
+    %% Длинные связи со схемы
+    Asset_Config -.-> ModelLoading
+    ModelLoading -.-> TriggerObject[Триггер объект]
+
+    classDef idleNode fill:#efdbc4, stroke:#554e46, color:#b25019
+    classDef activeNode fill:#ff7325,stroke:#652d0e, color:#652d0e
+    classDef successNode fill:#247633,stroke:#efdbc4, color:#efdbc4
+    classDef errorNode fill:#ad2427,stroke:#efdbc4, color:#efdbc4
+    class Position_Group activeNode
+    class Mission,MissionConfig idleNode
+    class ImproveHighlight,HighlightObjects,TriggerObject,Highlight,ModelLoading,MissionId,AssetConfig,ModelConfig,InteractiveConfig,InteractiveList,InitialStateConfig successNode
+    class MissionSettings,StartStep errorNode

tools/get-diagram.ps1

@@ -0,0 +1,59 @@
+param(
+  [string]$RepoPath = "architecture.mmd",
+  [string]$Branch = "dev"
+)
+
+$ErrorActionPreference = "Stop"
+
+function Set-EnvFromFile {
+  param([string]$EnvPath)
+
+  if (-not (Test-Path $EnvPath)) {
+    return
+  }
+
+  foreach ($line in Get-Content $EnvPath) {
+    if ([string]::IsNullOrWhiteSpace($line) -or $line.StartsWith("#")) {
+      continue
+    }
+    $parts = $line -split "=", 2
+    if ($parts.Length -ne 2) {
+      continue
+    }
+    [System.Environment]::SetEnvironmentVariable($parts[0], $parts[1], "Process")
+  }
+}
+
+function Get-OriginInfo {
+  $origin = (git remote get-url origin).Trim()
+
+  if ($origin -match "^https?://([^/]+)/([^/]+)/([^/]+?)(?:\.git)?$") {
+    return @{
+      BaseUrl = "https://$($matches[1])"
+      Owner   = $matches[2]
+      Repo    = $matches[3]
+    }
+  }
+
+  throw "Unsupported origin URL format: $origin"
+}
+
+Set-EnvFromFile ".env.local"
+$originInfo = Get-OriginInfo
+
+$baseUrl = $originInfo.BaseUrl
+$owner = $originInfo.Owner
+$repo = $originInfo.Repo
+$token = $env:FORGEJO_TOKEN
+
+if (-not $token) {
+  throw "FORGEJO_TOKEN is missing. Add it to .env.local."
+}
+
+$encodedPath = [System.Uri]::EscapeDataString($RepoPath).Replace("%2F", "/")
+$url = "$baseUrl/api/v1/repos/$owner/$repo/contents/${encodedPath}?ref=${Branch}"
+$headers = @{ Authorization = "token $token" }
+
+$response = Invoke-RestMethod -Headers $headers -Uri $url -Method Get
+$base64Content = ($response.content -replace "`n", "")
+[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($base64Content))

tools/put-diagram.ps1

@@ -0,0 +1,83 @@
+param(
+  [string]$RepoPath = "architecture.mmd",
+  [string]$LocalFile = "architecture.mmd",
+  [string]$Message = "update diagram",
+  [string]$Branch = "dev"
+)
+
+$ErrorActionPreference = "Stop"
+
+function Set-EnvFromFile {
+  param([string]$EnvPath)
+
+  if (-not (Test-Path $EnvPath)) {
+    return
+  }
+
+  foreach ($line in Get-Content $EnvPath) {
+    if ([string]::IsNullOrWhiteSpace($line) -or $line.StartsWith("#")) {
+      continue
+    }
+    $parts = $line -split "=", 2
+    if ($parts.Length -ne 2) {
+      continue
+    }
+    [System.Environment]::SetEnvironmentVariable($parts[0], $parts[1], "Process")
+  }
+}
+
+function Get-OriginInfo {
+  $origin = (git remote get-url origin).Trim()
+
+  if ($origin -match "^https?://([^/]+)/([^/]+)/([^/]+?)(?:\.git)?$") {
+    return @{
+      BaseUrl = "https://$($matches[1])"
+      Owner   = $matches[2]
+      Repo    = $matches[3]
+    }
+  }
+
+  throw "Unsupported origin URL format: $origin"
+}
+
+Set-EnvFromFile ".env.local"
+$originInfo = Get-OriginInfo
+
+$baseUrl = $originInfo.BaseUrl
+$owner = $originInfo.Owner
+$repo = $originInfo.Repo
+$token = $env:FORGEJO_TOKEN
+
+if (-not (Test-Path $LocalFile)) {
+  throw "Local file not found: $LocalFile"
+}
+if (-not $token) {
+  throw "FORGEJO_TOKEN is missing. Add it to .env.local."
+}
+
+$encodedPath = [System.Uri]::EscapeDataString($RepoPath).Replace("%2F", "/")
+$url = "$baseUrl/api/v1/repos/$owner/$repo/contents/$encodedPath"
+$headers = @{ Authorization = "token $token" }
+
+$sha = $null
+try {
+  $current = Invoke-RestMethod -Headers $headers -Uri "${url}?ref=${Branch}" -Method Get
+  $sha = $current.sha
+} catch {
+  # If file does not exist on the branch yet, create it without sha.
+  if (-not $_.Exception.Message.Contains("couldn't be found")) {
+    throw
+  }
+}
+
+$content = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes((Get-Content $LocalFile -Raw)))
+$body = @{
+  message = $Message
+  content = $content
+  branch  = $Branch
+}
+if ($sha) {
+  $body.sha = $sha
+}
+
+Invoke-RestMethod -Headers $headers -Uri $url -Method Put -ContentType "application/json" -Body ($body | ConvertTo-Json)