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

# Architecture

## Goals

`vmware-api-simulator` is a stateful vSphere lab emulator (Automation REST + VIM SOAP).
The primary design goal is **practical client compatibility**: sessions, inventory,
VM lifecycle, PropertyCollector walks, tasks, tagging/content library stubs, and
AuthZ roles are implemented against a large synthetic datastore so tools like curl,
govc-style flows, pyvmomi, and Terraform can exercise common paths without a real
vCenter.

Catalog majors **6–9** map to vSphere 7.0 / 7.0U3 / 8.0 / 8.0U2 floors. Hot-swap
changes the catalog used for Web UI browse/evidence only — it does **not** gate
live routes. Optional Proxmox `/api2/*` stub remains behind `ENABLE_PVE_STUB`
(off by default).

## System context

```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
```

## Planes

| Plane | Path | Notes |
|---|---|---|
| Automation REST | `/api`, `/rest` | Session header `vmware-api-session-id` |
| VIM SOAP | `/sdk` | PropertyCollector subset + VM tasks |
| Lab UI helpers | `/ui/api/*` | Catalog, demo seed, compatibility |
| Optional PVE stub | `/api2/*` | Off unless `ENABLE_PVE_STUB=true` |

## Data model

Inventory lives in `vsphere_objects` (MOIDs, types, props JSON, parent links).
Sessions, credentials, tasks, tags, libraries, snapshots, and permissions are
sibling tables (migrations `009_vsphere.sql`, `010_vsphere_platform.sql`).
DB-backed Automation stubs use `vsphere_api_state` (`011`); content-library
transfer sessions and HttpNfcLease rows live in `vsphere_transfer_sessions` /
`vsphere_nfc_leases` (`012`); PropertyCollector views/tokens and console
tickets persist in `vsphere_pc_state` / `vsphere_console_tickets` (`013`).

Seed profiles (`small` / `large` / `big`) build a deterministic cluster —
default **large** is 10 hosts / **1000 VMs** (`big` = 20 / 2000).

## AuthZ

Credentials map to roles → privilege sets. Mutate handlers use
`require_privilege(...)`; read paths use `require_read`. SOAP Login issues a cookie
compatible with VIM sessions.

## Related docs

- [API coverage](api-coverage.md)
- [Authentication](authentication.md)
- [Web UI](web-ui.md)
- [Clients](clients.md)