diff --git a/README.md b/README.md
index 91827e3..7fc46a2 100644
--- a/README.md
+++ b/README.md
@@ -113,8 +113,16 @@ Konfiguracja przez zmienne środowiskowe (`SurrealDb__*`, `LLM__ApiKey`, `OTEL_*
 
 ```
 TarninaHub/
-├─ backend/                 # ASP.NET Core Web API + wwwroot (build z client)
+├─ backend/                 # ASP.NET Core Web API (API host) + wwwroot + migrations
+│  ├─ Controllers/          # warstwa API (kontrolery, DTO wejścia/wyjścia)
+│  ├─ Errors/               # globalna obsługa błędów (ProblemDetails)
+│  ├─ Configuration/        # konfiguracja Swagger/OpenAPI
+│  ├─ Domain/               # warstwa domeny (enumy, reguły)
+│  ├─ Application/          # DTO i abstrakcje (interfejsy)
+│  ├─ Infrastructure/       # SurrealDB, migracje, DI
+│  └─ migrations/           # *.surql (aplikowane przy starcie)
 ├─ client/                  # Vue 3 + TS + Vite
+├─ tests/TarninaHub.Tests/  # testy jednostkowe (xUnit)
 ├─ scripts/
 │  ├─ build.mjs             # build całości
 │  └─ copy-client.mjs       # client/dist -> backend/wwwroot
@@ -124,3 +132,11 @@ TarninaHub/
 ├─ TarninaHub.slnx
 └─ README.md
 ```
+
+## API
+
+- Swagger UI: `GET /swagger` (dokument per wersja, np. `/swagger/v1/swagger.json`).
+- Wersjonowanie: `?api-version=1.0` lub nagłówek `X-Api-Version` (domyślnie `1.0`).
+- Błędy: `ProblemDetails` (RFC 7807), globalny handler wyjątków.
+- Healthcheck: `GET /api/health` (bez wersji, dla infrastruktury).
+- Migracje SurrealQL są aplikowane automatycznie przy starcie (katalog `migrations/`).