Initial release of the oVirt/RHV Engine API simulator.

Stateful FastAPI lab with contract packs, Compose/Helm, Docker Hub release
targets, and Pulumi coverage across all Engine series (GET/POST/PUT/DELETE/HEAD).

docs/architecture.md

@@ -0,0 +1,44 @@
+**Language / Язык:** [English](architecture.md) | [Русский](ru/architecture.md)
+
+# Architecture
+
+## Goals
+
+- Faithful Engine URL layout (`/ovirt-engine/api`, SSO)
+- Stateful inventory in PostgreSQL
+- Contract-driven route registration per series pack
+- Lab-friendly Web UI and deterministic seeds
+
+## Components
+
+```
+clients / Web UI
+       │
+ api-gateway (nginx TLS + UI)
+       │
+  simulator (FastAPI :8080)
+       │
+   PostgreSQL
+```
+
+| Package | Responsibility |
+|---|---|
+| `app/ovirt/` | Engine routes, SSO, seed, schema engine, versioning |
+| `app/web/` | Console UI and UI API |
+| `app/db/` | Migrations and connection pool |
+| `contracts/ovirt/` | Generated series packs |
+| `docker/gateway/` | nginx Engine + UI listeners |
+
+## Request path
+
+1. Client hits published Engine or UI port.
+2. Gateway proxies to FastAPI.
+3. Auth middleware resolves Basic / Bearer.
+4. Contract or semantic handler mutates / reads PostgreSQL.
+5. Response serialized as JSON or XML.
+
+## Related
+
+- [API surface](api-surface.md)
+- [Seed profiles](seed-profiles.md)
+- [Operations](operations.md)