**Language / Язык:** [English](../architecture.md) | [Русский](architecture.md)

# Архитектура

## Цели

`vmware-api-simulator` — stateful лабораторный эмулятор vSphere (Automation REST +
VIM SOAP). Главная цель дизайна — **практическая совместимость клиентов**:
сессии, inventory, жизненный цикл VM, обходы PropertyCollector, задачи,
stubs tagging/content library и роли AuthZ реализованы поверх большого
синтетического datastore, чтобы инструменты вроде curl, govc-подобных
потоков, pyvmomi и Terraform могли прогонять типовые пути без реального
vCenter.

Catalog majors **6–9** соответствуют floors vSphere 7.0 / 7.0U3 / 8.0 / 8.0U2.
Hot-swap меняет каталог только для browse/evidence в Web UI — он **не**
гейтит живые маршруты. Опциональный stub Proxmox `/api2/*` остаётся за
`ENABLE_PVE_STUB` (по умолчанию выключен).

## Контекст системы

```mermaid
flowchart LR
    Client["API clients<br/>pyvmomi / Terraform / govc / REST SDKs"]
    Admin["Lab operator"]
    UI["Web lab UI"]
    API["FastAPI application"]
    Gateway["HTTPS gateway :443"]
    Contract["vSphere contract matrix"]
    Domain["vsphere domain + inventory"]
    DB[(PostgreSQL)]
    Obs["Logs / Prometheus / OpenTelemetry"]

    Client -->|"/api /rest /sdk"| Gateway
    Gateway --> API
    UI --> Gateway
    Admin -->|"seed / migrate"| API
    API --> Contract
    API --> Domain
    Domain --> DB
    API --> Obs
```

## Плоскости

| Плоскость | Путь | Заметки |
|---|---|---|
| Automation REST | `/api`, `/rest` | Заголовок сессии `vmware-api-session-id` |
| VIM SOAP | `/sdk` | Подмножество PropertyCollector + VM tasks |
| Lab UI helpers | `/ui/api/*` | Каталог, demo seed, совместимость |
| Опциональный PVE stub | `/api2/*` | Выкл., пока `ENABLE_PVE_STUB=true` |

## Модель данных

Inventory живёт в `vsphere_objects` (MOID, типы, props JSON, parent-ссылки).
Sessions, credentials, tasks, tags, libraries, snapshots и permissions —
соседние таблицы (миграции `009_vsphere.sql`, `010_vsphere_platform.sql`).
DB-backed Automation stubs используют `vsphere_api_state` (`011`); сессии
transfer content library и строки HttpNfcLease — в `vsphere_transfer_sessions` /
`vsphere_nfc_leases` (`012`); views/tokens PropertyCollector и console tickets —
в `vsphere_pc_state` / `vsphere_console_tickets` (`013`).

Профили seed (`small` / `large` / `big`) строят детерминированный
кластер — по умолчанию **large** это 10 hosts / **1000 VMs** (`big` = 20 / 2000).

## AuthZ

Credentials отображаются в roles → privilege sets. Мутирующие обработчики
используют `require_privilege(...)`; пути чтения — `require_read`. SOAP Login
выдаёт cookie, совместимый с VIM-сессиями.

## Связанные документы

- [Покрытие API](api-coverage.md)
- [Аутентификация](authentication.md)
- [Web UI](web-ui.md)
- [Клиенты](clients.md)