diff --git a/README.md b/README.md
index 06ba988..429a472 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,78 @@ following contract. `CLAUDE.md` has the full rationale.
 * ```develop``` merge your work here; keep this up to date with the "development" environment / dev tag
 * ```staging``` keep this up to date with the "staging" environment / stage tag
 * ```production``` keep this up to date with the "production" environment / prod tag
+
+## Deployment architecture
+
+The deployed system is defined by [`docker-compose.az.yml`](docker-compose.az.yml). It runs the
+**application tier** as four containers; the **data tier** (Postgres/PostGIS) is external, managed
+Azure Database for PostgreSQL, not part of this compose file.
+
+When deployed by `workspaces-stack` this model also holds. 
+
+```
+                    client  (TDEI/Keycloak JWT)
+                       │
+                       ▼ :8000
+        ┌──────────────────────────────────────┐
+        │          workspaces-backend           │  this repo — FastAPI front door.
+        │   authn/authz + OSM reverse proxy     │  Serves /api/v1/*, proxies the rest.
+        └───┬──────────────────────────────┬────┘
+     WS_OSM_HOST                   TASK_DATABASE_URL
+   (→ osm-rails)                   OSM_DATABASE_URL
+            │                              │
+            ▼                              │
+     ┌──────────────┐                      │
+     │  osm-rails   │  OSM website (Rails); the single OSM entry point.
+     │  :3000       │  Serves the API/UI and fronts cgimap for the
+     └──────┬───────┘  performance-critical /api/0.6 calls.
+            │ (internal)                   │
+            ▼                              │
+     ┌──────────────┐                      │
+     │  osm-cgimap  │  C-accelerated /api/0.6 (map, changeset bulk)
+     │  :8000       │                      │
+     └──────────────┘                      │
+                                           │
+     osm-rails-worker  (rake jobs:work)    │  background jobs
+            │                              │
+            │  backend, rails, cgimap, worker all connect to ▼
+   ┌─────────────────────────────────────────────────────────────────┐
+   │  data tier — Azure Postgres (external, PostGIS)                   │
+   │  opensidewalks-${ENV}.postgres.database.azure.com:5432            │
+   │    • workspaces-tasks-${ENV}   TASK db  (alembic_task; backend)   │
+   │    • workspaces-osm-${ENV}     OSM db   (alembic_osm; all four)   │
+   └─────────────────────────────────────────────────────────────────┘
+```
+
+### Services
+
+| Service | Image | Role |
+|---|---|---|
+| `workspaces-backend` | `workspaces-backend-v2:${ENV}` | This repo. The only host-exposed service (`8000:8000`). Validates the TDEI/Keycloak JWT, enforces workspace authorization, serves `/api/v1/*`, and proxies everything else to the OSM tier. Connects to **both** databases. |
+| `osm-rails` | `workspaces-osm-rails-v2:${ENV}` | The OpenStreetMap website (Rails) — the **single OSM entry point** the backend proxies to (`WS_OSM_HOST`). Serves the OSM API/UI and fronts cgimap for the heavy `/api/0.6` calls. Connects to the OSM db. |
+| `osm-cgimap` | `workspaces-osm-cgimap-v2:${ENV}` | C++ reimplementation of the performance-critical OSM `0.6` calls (map queries, changeset upload/download), sitting behind `osm-rails`. Tuned here for large imports (`CGIMAP_MAX_*`). Connects to the OSM db. |
+| `osm-rails-worker` | `workspaces-osm-rails-v2:${ENV}` | Background job runner (`rake jobs:work`) for the Rails app. Connects to the OSM db. |
+
+### Two databases
+
+The backend holds two connections, and the two alembic trees target them independently (see
+`CLAUDE.md` and `api/utils/migrations.py`):
+
+* **TASK db** (`TASK_DATABASE_URL` → `workspaces-tasks-${ENV}`) — the workspaces + tasking-manager
+  schema, built by the `alembic_task` tree. Only the backend connects here.
+* **OSM db** (`OSM_DATABASE_URL` → `workspaces-osm-${ENV}`) — OSM data plus `users` and the
+  `tasking_*` tables, built by the `alembic_osm` tree. The backend, cgimap, rails, and the worker
+  all connect here.
+
+On startup (outside of pytest) the backend runs `alembic -n task upgrade head` and
+`alembic -n osm upgrade head`, applying each tree to its database.
+
+### Environment templating
+
+Every image tag, database name/user, and server host is parameterized by `${ENV}`
+(`dev` / `stage` / `prod`), and secrets are injected from the shell environment
+(`${WS_TASKS_DB_PASS}`, `${WS_OSM_DB_PASS}`, `${WS_OSM_SECRET_KEY_BASE}`). Branches map to these
+environments — see the Branch Index below.
   
 ## To start on your local machine for dev work
 
@@ -106,4 +178,4 @@ connecting to existing Databases.
 
 `docker compose --file docker-compose.local.yml down`
 
-Backend code will be available at `http://localhost:8000`
\ No newline at end of file
+Backend code will be available at `http://localhost:8000`