Idempotent order placement, a redesigned README overview and a cheaper pull request CI

[NullButCute]

This PR has three independent commits: idempotent order placement, a redesign of the README's overview and architecture sections, and a cheaper CI pipeline for pull requests.

1. Idempotent order placement

Problem

A client that times out or loses the connection on POST /api/orders cannot know whether its order was placed. Repeating the request placed it a second time, and charged it twice. Nothing tied a retry to the original request.

What changes

POST /api/orders accepts an optional Idempotency-Key header. The client sends the same key again when it retries.

Situation	Result
First request with a key	Processed as before. The response is stored with the key.
The same request again	The stored response is returned as it was, with Idempotency-Replayed: true. No second order, outbox event or payment. The catalog and stock are not checked again, so the retry succeeds even if the stock ran out or a price changed.
The same key with a different request	422.
Two copies in flight at once	One order is placed and every copy gets it back.
A request that got 400 or 503	Does not use up the key. Repeat it once the problem is fixed.
No key	Unchanged. Idempotency__RequireKey=true rejects requests without one once all clients send it (default false).

Keys are 1-128 characters (A-Z a-z 0-9 . _ ~ : -), scoped to the user, and remembered for 24 hours (Idempotency__RetentionHours). DELETE /api/orders/{id} needs no key: cancelling already returns the same result when repeated.

How it stays correct

• Atomic. The order, its outbox event, its read-model row and the key are saved in one transaction. The read-model row used to be a second save after the order, so a crash in between left an order without a summary; that gap is closed too.
• No locks, no "in progress" state. A unique index on (UserId, Key) decides between copies running at the same moment. Both see a new key, one commits, and the other gets a unique-key violation. It rolls back completely and answers from the winner. A request that crashes midway cannot leave a key stuck, and nothing from a losing copy is left behind.
• Fingerprint. A SHA-256 of the validated request (products, quantities, trimmed note). JSON formatting, line order and the ignored productName/unitPrice fields don't make a retry look different.
• Retention. A background job deletes expired keys with one set-based DELETE every 15 minutes, safe on every replica.
• Observability. shopeasy_orders_idempotent_replays_total{result} counts replays and rejected key reuse.
• Gateway. YARP forwards the request header and the Idempotency-Replayed response header unchanged.

New table IdempotencyRecords (migration AddIdempotencyKeys); nothing existing is touched. Settings are in the Order appsettings.json, docker-compose.yml / .env.example, and the shopeasy-config ConfigMap. The controller now depends on a small IInventoryStock interface (implemented by the existing InventoryCacheService) so the real action can be tested with a fake stock.

Tests (324 in total: 271 without servers, 53 with PostgreSQL and RabbitMQ)

• Header parsing and the request fingerprint.
• The real PlaceOrder action on an in-memory database: a repeat returns the original order and body, the same key with a different request gets 422, keys are scoped per user, a 400 or 503 does not use up the key, a required key is enforced, and the order, outbox event, read-model row and key are all saved together.
• Against PostgreSQL: eight copies of one request in flight at once place exactly one order (one outbox event, one summary, one key left over); concurrent requests with different keys, or with no key, each place their own order; concurrent reuse of one key for different orders lets one win and rejects the rest; a retry on another instance replays from the database; the clean-up removes only expired keys.
• The concurrency tests fail when the duplicate-key handling is removed. I checked that.
• Drift tests keep the appsettings.json, Compose, .env.example and ConfigMap copies of the settings equal to the code's defaults.

Also verified locally: the Order service starts, applies the migration and serves requests against PostgreSQL and RabbitMQ; docker compose config renders the settings (and an override); the Kubernetes manifests pass kubeconform -strict and the repo's deployment rules.

Not in this change

The Order saga's command publishes still happen after the database commit. A crash in that gap is recovered by the saga timeout service, as documented. Moving them onto a transactional outbox touches every saga consumer and is better reviewed on its own.

2. README overview and architecture redesign (documentation only)

The README's opening was a short description and an ASCII diagram that no longer matched the system. It is replaced by a header with badges and quick links, an Overview (what the platform is for, the guarantees it is built around, what it deliberately is not), an Architecture section with three diagrams GitHub renders (system overview, life of an order, saga state machine) plus tables for communication, data ownership, cross-cutting qualities and deployment, and The Services and Technology Stack as tables.

Checked: all three diagrams render from the README itself, all 62 internal links resolve, and the claims were verified against the code and configuration. Two inaccuracies were fixed on the way (Order has no fixed port in Compose; the read-model row is written in the order's transaction).

3. Cheaper CI for pull requests

• Six per-service "Docker build" jobs removed from pull requests. The "Start the Compose stack" job already builds the same six images and then runs them, which is the stronger check, so the six jobs only repeated it: about 5 GB of downloads and six runners per run. The images are still built from their Dockerfiles on every pull request (in the Compose job) and built and published from main. They can be added back later if wanted.
• Documentation-only pull requests skip the heavy jobs. A new "Detect changes" job (a plain git diff, no third-party action) decides whether anything other than *.md, docs/ or the licence changed. Skipped jobs count as passed in CI passed, which only fails for failed or cancelled jobs, so it keeps working as the required check. Runs on main, tags and manual dispatch always run everything. The logic was tested against typical change sets.
• Hang protection. The test step now aborts a hung test after 5 minutes and names it (--blame-hang-timeout 5m). One earlier run on this branch sat in "Build and test" until the 25-minute limit and was cancelled without saying which test stalled.

Effect on a typical code PR: about 3-4 GB and 6 runner-minutes instead of 8-10 GB and 12. Wall-clock time stays about the same because the tests and the Compose job were already the longest jobs. A docs-only PR finishes in seconds. If branch protection requires any check other than CI passed, the removed Docker build (...) checks need to be taken out of it.

This push is also the first run of the new workflow: GitHub runs the workflow file from the PR itself.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vuhzoey6h5V9wPPVFuR7ME