updating documentatin

documentation/backlog.md

@@ -8,9 +8,6 @@ Labels: `[feature]` `[infra]` `[security]` `[ux]` `[debt]`
 
 Things that are actively in progress or should be picked up immediately. Mostly operational risk and the remaining phase 7 hardening work.
 
-- **Migrations in the deploy pipeline** `[infra]` `[debt]`
-  Run `drizzle migrate` as a step in the CI/CD pipeline before the API container is restarted. Deploying code before schema is applied causes crashes. See `deployment.md` — deploy order is currently documented but not enforced.
-
 - **Rate limiting on API endpoints** `[security]`
   At minimum: auth endpoints (brute force prevention) and game endpoints (spam prevention). Consider `express-rate-limit`.
 
@@ -58,6 +55,7 @@ Clearly planned work, not yet started. No hard ordering — sequence based on wh
 
 - **Valkey for game session store** `[infra]`
   Add Valkey to the production Docker stack. Implement `ValkeyGameSessionStore` against the existing `GameSessionStore` interface. Required before multiplayer scales.
+  NOTE: the rate limiting middleware needs to be adjusted for valkey, see todo comment
 
 - **User stats endpoint + profile page** `[feature]`
   `GET /users/me/stats` returning games played, score history, etc. Frontend profile page displaying the stats.
@@ -113,6 +111,7 @@ Directionally right, timing is unclear. Revisit when the next/now work is done.
 
 Shipped milestones, newest first.
 
+- **04 - 2026 — Migrations in deploy pipeline** — Drizzle migrate runs as a CI/CD step before the API container restarts
 - **04 - 2026 — Phase 6: Production deployment** — Hetzner VPS, Caddy HTTPS, Forgejo CI/CD, daily DB backups, cross-subdomain auth
 - **04 - 2026 — Phase 5: Multiplayer game** — real-time simultaneous play, 15s server timer, live scoring, winner screen
 - **04 - 2026 — Phase 4: Multiplayer lobby** — WebSocket server, lobby create/join, real-time player list

documentation/deployment.md

@@ -144,6 +144,7 @@ docker system prune -a    # aggressive — removes all unused images
 ### API (`apps/api/Dockerfile`)
 
 Multi-stage build: base → deps → dev → builder → runner. The `runner` stage does a fresh `pnpm install --prod` to get correct symlinks. Output is at `apps/api/dist/src/server.js` due to monorepo rootDir configuration.
+The runner stage copies compiled migration files from the builder (packages/db/drizzle) alongside the application code. The container entrypoint runs migrate.js first, then starts server.js, ensuring schema and code are always in sync on every deploy.
 
 ### Frontend (`apps/web/Dockerfile`)
 
@@ -174,12 +175,7 @@ The seeding script (`packages/db/src/seeding-datafiles.ts`) uses `onConflictDoNo
 
 ### Schema Migrations
 
-Schema changes are managed by Drizzle. Deploy order matters:
+Migrations are run automatically on container startup via the CMD in the API Dockerfile. The entrypoint runs migrate.js before starting the server, so the schema is always up to date before the API begins accepting requests. The correct deploy order is enforced automatically.
-
-1. Run migration first (database gets new structure)
-2. Deploy new API image (code uses new structure)
-
-Reversing this order causes the API to crash on missing columns/tables.
 
 ## Backups