From 289add5e8425d4467dddc458f1086c7365cfcfc5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=92=D0=B8=D0=BA=D1=82=D0=BE=D1=80?=
 <78488229+viktor138irk@users.noreply.github.com>
Date: Wed, 6 May 2026 17:55:35 +0900
Subject: [PATCH] Add architecture document

---
 docs/ARCHITECTURE.md | 122 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 docs/ARCHITECTURE.md

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..c1c4a9a
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,122 @@
+# Архитектура Virtuality
+
+Virtuality — это платформа виртуализации в стиле Proxmox, но с более компактной и контролируемой архитектурой.
+
+## Цель
+
+Создать собственную систему управления виртуальными машинами на базе стабильных Linux-компонентов:
+
+- KVM;
+- QEMU;
+- libvirt;
+- Cockpit на раннем этапе;
+- собственная веб-панель на следующих этапах.
+
+## Базовая схема
+
+```text
+Веб-интерфейс
+  ↓
+Backend API
+  ↓
+Node services
+  ↓
+libvirt / QEMU / KVM
+  ↓
+Host OS / Storage / Network
+```
+
+## Слои системы
+
+### 1. Web UI
+
+Будущая пользовательская панель Virtuality.
+
+Задачи:
+
+- список виртуальных машин;
+- создание VM;
+- управление питанием;
+- консоль;
+- хранилища;
+- сеть;
+- бэкапы;
+- пользователи и роли.
+
+### 2. Backend API
+
+Единая точка управления нодой.
+
+Задачи:
+
+- принимать команды от Web UI;
+- валидировать действия;
+- работать с libvirt;
+- вести журнал событий;
+- отдавать состояние VM, storage и сети.
+
+### 3. Node services
+
+Системные сервисы Virtuality.
+
+Задачи:
+
+- диагностика ноды;
+- обновления;
+- резервное копирование;
+- мониторинг;
+- фоновые задачи.
+
+### 4. libvirt / QEMU / KVM
+
+Нижний слой виртуализации.
+
+Задачи:
+
+- запуск виртуальных машин;
+- управление дисками;
+- управление сетевыми интерфейсами;
+- снапшоты;
+- консольный доступ.
+
+### 5. Host OS
+
+Операционная система сервера.
+
+Целевые системы:
+
+- Debian 12;
+- Ubuntu Server 22.04;
+- Ubuntu Server 24.04.
+
+## Пути
+
+```text
+/opt/virtuality                 # код и конфигурация проекта
+/var/lib/virtuality             # runtime-хранилище
+/var/lib/virtuality/iso         # ISO-образы
+/var/lib/virtuality/images      # диски VM
+/var/lib/virtuality/backups     # резервные копии
+/var/log/virtuality             # логи
+```
+
+## Принципы
+
+- исходный код отдельно от runtime-данных;
+- диски VM и ISO не хранятся в Git;
+- конфиги должны быть прозрачными;
+- установщик должен быть повторяемым;
+- сетевые изменения делаются осторожно, чтобы не уронить SSH;
+- архитектура документируется до активной разработки.
+
+## Этап v0.1
+
+На этапе v0.1 создаётся фундамент:
+
+- установщик ноды;
+- установка KVM/QEMU/libvirt;
+- установка Cockpit;
+- storage pools;
+- структура проекта;
+- GitHub-синхронизация;
+- базовая диагностика.