# Том 1. Архитектура платформы

## 1.1. Общая архитектурная концепция

Платформа строится как **иерархический цифровой двойник + мультиагентная AI + инвестиционная оболочка**.

```
┌─────────────────────────────────────────────────────────────────┐
│  CLIENT LAYER: планшет, сенсорный экран, VR/AR, веб-браузер     │
│  React/Vue/Angular + WebGL/WebGPU + WebRTC (Pixel Streaming)     │
├─────────────────────────────────────────────────────────────────┤
│  EXPERIENCE LAYER: UX сценарии, голос, AI-аватары, карта,     │
│  3D-сцена, инвестиционный кабинет, ситуационный центр           │
├─────────────────────────────────────────────────────────────────┤
│  APPLICATION LAYER: микросервисы (FastAPI/Node/.NET)           │
│  Passport, Telemetry, Scenario, AI Orchestrator, Finance,      │
│  Investment, GIS, Knowledge Graph, Document, Report, Auth      │
├─────────────────────────────────────────────────────────────────┤
│  DATA LAYER: PostgreSQL, TimescaleDB, Neo4j/ArangoDB,          │
│  S3/MinIO, ClickHouse, Vector DB (pgvector/Milvus), Cesium    │
├─────────────────────────────────────────────────────────────────┤
│  INTEGRATION LAYER: API Gateway, Kafka, MQTT, OPC-UA, Modbus,  │
│  REST, WebSocket, AMQP, файловый обмен                          │
├─────────────────────────────────────────────────────────────────┤
│  OT/EDGE LAYER: шлюзы, однонаправленные диоды, DMZ,           │
│  read-only сбор с SCADA/MES/ERP/EAM                             │
└─────────────────────────────────────────────────────────────────┘
```

## 1.2. Стек рекомендуемый для демо

| Уровень | Технология | Обоснование |
|---------|------------|-------------|
| 3D-движок | Unreal Engine 5.4 | Cesium, Nanite, Lumen, Pixel Streaming, MetaHumans |
| Геопространственные данные | Cesium for Unreal + Mapbox/2GIS/GeoJSON | точная позиция объектов РК |
| Frontend оболочка | React 18 + TypeScript + Vite + Tailwind | быстрая адаптивная UI, микрофронтенды |
| Backend | FastAPI (Python) + uvicorn | AI-интеграции, RAG, сценарии |
| Базы данных | PostgreSQL 16 + TimescaleDB 2.13 + pgvector + Neo4j 5.x | реляционные, time-series, вектор, граф |
| Кэш/потоки | Redis 7 + Apache Kafka 3.x | сессии, WebSocket, event sourcing |
| Object store | MinIO / AWS S3 | документы, 3D-ассеты, снимки |
| AI/LLM | GPT-4 / Claude / LLaMA 3 (on-prem) + LangChain/LangGraph | агенты, RAG, голос |
| Голос | Azure TTS / Yandex SpeechKit / Piper (TTS) + Whisper (STT) | kaz/rus/eng |
| CI/CD | GitHub Actions + Docker + Helm + Kubernetes | автоматизация, стенды |
| IaC | Terraform / Pulumi + Ansible | on-prem + cloud |

## 1.3. Микросервисы демо-версии

1. **Identity & Access (IAM)** — Keycloak / Auth0, RBAC+ABAC, MFA, JWT.
2. **Asset Registry** — реестр активов, цифровые паспорта, координаты, статусы.
3. **Digital Passport Service** — CRUD паспортов, документы, версионирование.
4. **Telemetry Service** — приём, валидация, нормализация телеметрии; time-series запросы.
5. **Event Service** — Kafka, event sourcing, audit log.
6. **Alarm Service** — генерация аварий, эскалация, suppression rules.
7. **Document Service** — хранение, OCR, индексация, data room.
8. **GIS Service** — слои, геозапросы, Cesium тайлы.
9. **Digital Twin Service** — 7D-состояние объектов, симуляция, what-if.
10. **Scenario Engine** — сценарные расчёты, чувствительность, timeline.
11. **Financial Model Service** — CAPEX/OPEX, налоги, цифровой тенге, cash-flow.
12. **AI Orchestration Service** — маршрутизация к агентам, prompt management, confidence, guardrails.
13. **Knowledge Graph Service** — онтология, Cypher/SPARQL, reasoning.
14. **Search Service** — гибридный поиск по документам + графу + векторам.
15. **Report Generation Service** — PDF/HTML/Excel отчёты.
16. **Notification Service** — push/email/SMS/telegram.
17. **Audit Service** — журнал действий, неизменяемый лог.
18. **Integration Gateway** — API Gateway, rate limiting, transformation, circuit breaker.
19. **Data Quality Service** — правила, anomaly detection, lineage.
20. **Metadata Catalog** — DataHub / Amundsen, реестр источников.

## 1.4. Event-driven data flow (пилот)

1. Edge gateway с датчиков пилотного объекта (`OPC-UA`/`MQTT`) → **Integration Gateway** (read-only, DMZ).
2. **Telemetry Service** пишет в **TimescaleDB** и публикует событие в **Kafka**.
3. **Digital Twin Service** обновляет 7D-состояние и пишет в **Neo4j** (граф) + **PostgreSQL** (атрибуты).
4. **AI Orchestration Service** подписан на Kafka; по аномалии вызывает **Промышленного AI**, получает 2 варианта, публикует `ai_recommendation`.
5. **Scenario Engine** / **Financial Model Service** считают экономику по новому состоянию.
6. **Unreal** через WebSocket/API получает обновлённые состояния и отображает в 3D.
7. **Frontend** React отображает панели, паспорта, AI-диалоги; обновления через WebSocket.

## 1.5. Интеграции (пилот и масштаб)

| Система | Протокол/формат | Данные | Статус демо |
|---------|-----------------|--------|-------------|
| KazMunayGas/KazTransOil GIS | REST/GeoJSON | положение объектов, мощности | demo/historical |
| KPO/TCO/NCOC MES | OPC-UA read-only | телеметрия скважин, НПС | demo/synthetic |
| KazTransOil SCADA | MQTT/OPC-UA one-way | давление, расход, вибрация | demo |
| Атырау НПЗ MES | SQL/MQTT | выпуск продуктов, остатки | demo |
| НБК / NPC Digital Tenge | REST API (testnet) | балансы, voucher, smart contracts | testnet |
| Halyk / Kaspi / BCC / Eurasian | Open Banking API test | кошельки, цифровой тенге | mock/test |
| Бюджет/казначейство | REST/EDO | налоговые потоки (агрегированные) | demo |
| Спутниковые платформы | WMS/WMTS | снимки, NDVI, метан | demo |
| IPFS (Kutdao/Birlik) | w3up / HTTP | CID документов, NFT-паспорта | demo |

## 1.6. API и контракты (краткий реестр)

- `GET /api/v1/assets/{id}` — цифровой паспорт актива.
- `GET /api/v1/assets/{id}/telemetry?from=&to=` — time-series.
- `POST /api/v1/scenarios/run` — запуск сценария.
- `POST /api/v1/ai/ask` — запрос к AI-оркестратору.
- `GET /api/v1/knowledge-graph/query` — Cypher/SPARQL.
- `POST /api/v1/invest/projects/{id}/evaluate` — инвестиционный профиль.
- `POST /api/v1/digital-tenge/distribute` — финансовая симуляция.
- `POST /api/v1/reports/generate` — генерация отчёта.

## 1.7. Масштабирование и отказоустойчивость

- Stateless микросервисы, горизонтальное масштабирование через Kubernetes.
- Базы данных — репликация master-replica, ежедневные бэкапы, point-in-time recovery.
- Pixel Streaming — 2+ GPU-ноды за load balancer, hot standby.
- Edge — локальный кэш на планшете, offline-режим для статики.
- DR — RPO < 1 ч, RTO < 15 мин для демо-стенда.

## 1.8. Интеграция с KazResource OS / KUT

Демо-архитектура совместима с суверенной операционной системой KazResource OS:

| KUT-компонент | Роль в архитектуре | Связь с микросервисами |
|---------------|--------------------|--------------------------|
| 7 технологических слоёв | Модель от физического сенсора до финансового settlement | Все слои мапятся на CLIENT → OT/EDGE → DATA → APPLICATION → EXPERIENCE |
| HMI/SCADA KUT | Промышленная визуализация и сбор тегов | Integration Gateway, Telemetry Service |
| Edge AI | Локальная верификация фактов, сравнение факт/план | AI Orchestration Service (read-only режим) |
| Цифровой двойник | 3D/BIM/Geo-модель + P&ID | Digital Twin Service, GIS Service |
| KUT-RGP | Цифровой геном ресурса, CID паспорта | Asset Registry, Digital Passport Service |
| MONOLITHAR | Суверенный блокчейн-нотариус, PoEx | Audit Service, Document Service (mock/ staging) |
| ARKHETHOR / РВА-КЗ | Токенизированные активы, NAV-Gated эмиссия | Financial Model Service, Investment Service |
| Цифровой банк KUT + цифровой тенге | Atomic settlement T+0 | Digital Tenge testnet adapter |
| NEB / IEL | Национальная шина событий, event sourcing | Kafka, Event Service |
| NRM / WEU | Ресурсная математика, мировой энергетический эталон | Scenario Engine, Financial Model Service |
| PFE / RFSC | Программируемый фискальный движок | Financial Model Service, Tax/Pension calculation |
| JEC с Газпромом | Совместный инженерный центр | Document Service, Knowledge Graph |

## 1.9. Архитектурные ограничения

- Прямое управление оборудованием запрещено; только read-only telemetry и read-only 3D-визуализация.
- Все финансовые операции в демо — на тестовой сети Digital Tenge, без реальных платежей.
- Критичные решения (ремонт, остановка, инвестиция) остаются за человеком; AI даёт варианты.
- KazResource OS / MONOLITHAR / ARKHETHOR в демо представлены в виде визуализированных мок-интеграций; промышленное внедрение требует отдельных государственных согласований.