A small Contoso e-commerce system that shows 12 microservices patterns working for real. Each pattern gets its own page with an explanation, when not to use it, and a live demo you can click.
Status: complete. All 12 patterns are live, each with a working demo, locally and in one real Azure run: provision, deploy through GitHub Actions with OIDC, smoke tests, screenshots, teardown. Demos 13 (a slow payment in the middle of checkout) and 14 (the saga's undo under timeouts and duplicate events) came from readers' comments on the project's LinkedIn post. The foundation is copied from Azure-Ecommerce-Monolith-Microservices-Migration.
What was built. 5 Flask services (user, catalog, order, payment, inventory), each owning its own database, behind one FastAPI gateway; a small service registry; Redis as the event bus; and a React frontend with one page per pattern. Every demo calls the real services: nothing is mocked.
How it was delivered. In milestones, one reviewable pull request each, following docs/PLAN.md:
| Milestone | Patterns | Pull requests |
|---|---|---|
| M0, M1a: bootstrap and layout | (foundation) | #1 |
| M1: foundation | 1, 2, 5, 6 | #2 |
| M2: resilience and independence | 4, 10, 11, 12 | #3 |
| M3a: async and packaging | 7, 8, 9 | #4 |
| M3b: delivery and the Azure run | 3 | #12, #13, #14 |
| Demo 13: a slow payment mid-checkout | 4 and 8, under a timeout | #16 |
| Demo 14: compensation under fire | 7 and 8, under timeouts and duplicates | #17 |
M3b was planned as 7 GitHub issues (#5 to #11), all closed.
How it was checked.
- 194 unit tests across 8 suites, each in its own virtualenv, built test-first from M3a on.
- Pact contract tests: the order service's contracts with payment, catalog and inventory, verified against the real providers in CI.
- 28 local smoke tests against the running stack, and 4 Azure smoke tests against the real deployment.
- CI on every pull request runs only what the change touches; every image is built for
linux/amd64, started, and rejected if it runs as root.
mainrequires the "CI ok" check. - A two-axis code review (coding standards, and the spec) before every milestone PR.
What it cost. Locally: $0, no Docker. In Azure: one session of about 1.5 hours, on free tiers or the cheapest SKUs, with a $25/month budget alert, then torn down and verified empty. See cost_estimate.md.
| # | Pattern | What it does | Milestone |
|---|---|---|---|
| 1 | Database per Service | Gives each service its own database | M1 |
| 2 | Bounded Context | Splits one large domain into clear business domains | M1 |
| 3 | CI-CD Pipeline | Builds, tests and deploys every service automatically | M3b |
| 4 | Circuit Breaker | Stops calls to a failing service to prevent more failures | M2 |
| 5 | API Gateway | Routes client requests to the right service | M1 |
| 6 | Observability | Collects logs, metrics and traces from every service | M1 |
| 7 | Event-Driven Architecture | Services communicate by publishing and consuming events | M3a |
| 8 | Saga Pattern | Coordinates distributed transactions and rolls back failures safely | M3a |
| 9 | Containerization | Packages each service with all its dependencies | M3a |
| 10 | Stateless Services | Stores session data outside the service | M2 |
| 11 | Contract Testing | Checks that APIs stay compatible across services | M2 |
| 12 | Service Discovery | Finds service instances automatically at runtime | M2 |
| 13 | Saga under a slow payment | Follows the money and the stock when payment times out mid-checkout | Demo 13 |
| 14 | Compensation under fire | Times out and duplicates the saga's undo, then checks the stock ends where it began | Demo 14 |
Browser → API gateway ──┬──► user → user_db (signs login tokens)
(checks tokens, ├──► catalog → catalog_db
request IDs, ├──► order ×2 → order_db checkout saga: price → hold stock →
tracing, metrics, │ charge (circuit breaker) → confirm
aggregation, ├──► payment → payment_db
failover) └──► inventory → inventory_db
order_db outbox ──relay──► Redis Stream "shop.events" ──► inventory (sells the held stock)
Every service heartbeats into the registry (:8500); callers look each other up there.
- 5 Flask services (
services/), each with its own database: SQLite locally, one logical MySQL database each in Azure. Locally the order service runs as 2 replicas. - FastAPI gateway (
gateway/): the only thing the browser talks to. Routes/api/shop/*to the owning service, adds request IDs, aggregates/api/order-summary, serves the demo endpoints. shop_common(shared/): OpenTelemetry tracing, JSON logs with trace IDs, Prometheus metrics, the/health/db,/debug/spans,/metricsendpoints, token checks, the discovery client and the event bus helpers.- Service registry (
registry/): about 90 lines of FastAPI. Local only; Azure uses Container Apps DNS. - Contracts (
contracts/pacts/): the Pact files the order service needs payment, catalog and inventory to honour. - Redis (Homebrew
redis-serverlocally, an internal Container App in Azure): the event bus. - Dockerfiles: one per service plus gateway and registry, multi-stage, non-root, built only in
the cloud or CI for
linux/amd64. - React + TypeScript frontend (
frontend/) with a page per pattern. - One service table (
scripts/service_table.py): every process, folder and port. Setup, the local launcher, CI, provision and the Deploy workflow all read it.
Each service reports the database it owns. Then the order service tries to read the catalog's
product table through its own connection, and the database refuses: no such table: product.
A context map of the 5 business contexts, and one product as two contexts see it: Catalog knows its name and price, Inventory knows how many are on hand.
Which commit each running service was built from, compared with the latest commit on main, and the latest CI and Deploy runs, read from GitHub. A service shows "behind main" only when main changed its own code since its build, the same rule the Deploy button uses.
- CI on every pull request runs only what the change touches (
scripts/ci_changes.py, driven by the service table): a change to one service runs its tests and its image; a change to shared code, CI or the service table runs everything. Pushes to main run everything. - Deploy is a manual workflow on main. It signs in to Azure with OIDC (no password stored), rebuilds only services whose code changed since the commit they run, tags each image with the commit, and waits until each service answers with the new commit.
Locally, every process is a "local build":
In Azure, every service runs the latest commit of main:
Switch payment to slow and send 10 calls. Each order replica's breaker opens after 3 failures. A real failure took 2,215 ms; a call the open breaker stopped took 0 ms. After 15 s with payment healthy again, both breakers close.
One browser call to /api/order-summary becomes 4 service calls. The page shows each call, its
status and timing, and the one request ID forwarded to all of them.
One click, traced through every process: 25 spans across 5 processes, including each service's
database queries, drawn as a waterfall. Metrics per service come from each /metrics endpoint.
Disconnect the bus and buy a mug: its 3 events (StockReserved, PaymentCharged, OrderConfirmed) wait in the order service's outbox, and the mug stays held in inventory. Reconnect: the events go out and inventory turns the hold into a sale.
In Azure, the same 3 events were published within a second through the Redis Container App, and inventory sold the reservation:
Buy 2 mugs with "make the bank decline the card" ticked. The saga prices the cart, holds the stock, the charge fails, and it releases the stock. Stock ends exactly where it started; the cart is kept.
How each process runs: uid, container or not, platform, build and image size. Locally they are plain processes; CI builds and runs every image for linux/amd64 and fails any that runs as root.
In Azure, all 6 run in containers as uid 10001 on linux/x86_64, built from one commit, 67-69 MB each:
Your login is a signed token, readable by anyone, signed only by the user service. Ask for your cart 6 times: both order replicas answer. Stop one: all 6 calls still succeed, same cart, still logged in.
The order service's contracts with payment, catalog and inventory, read from the committed Pact files, and the real CI output when payment renames one field the order service relies on.
The live registry. Stop an instance: its heartbeat stops, the registry expires it after 10 s, and
make run restarts it 20 s later, when it registers again.
A declined card is the easy case. The hard one is a timeout: the charge call runs long, the breaker counts a failure, and a saga that releases the stock now may leave a customer charged with no order, or charged twice by the retry. Two fixes, both suggested by a reader:
- An idempotency key on every charge (the saga id). The retry sends the same key, so payment returns the first charge instead of making a second one.
- A status check before any undo. The saga voids the key with payment, which answers how the charge stands. APPROVED confirms the order; DECLINED releases the stock; a charge payment never saw becomes VOIDED, so a late copy of it is refused. PROCESSING or no answer leaves the order pending, stock held, until a background check (every 5 s) settles it. A charge stuck in PROCESSING for 30 s is voided, so no order waits forever.
Make payment slow, buy 2 mugs, and follow the money and the stock. Here the charge call timed out, payment still said PROCESSING, so the order waited; 5 s later it settled as 1 charge, 1 order, 2 mugs sold.
An undo is a new action, not a rewind, and it crosses the same unreliable network. A second reader asked for duplicate events and timeouts during compensation. Three cases:
- A release that beats its hold. Inventory holds slowly (6 s); the saga gives up after 3 s and sends a release as an event, which arrives first (about 4 s). Inventory records the release, so the late hold holds nothing. Before this demo, that late hold kept the stock held for good.
- A release that times out but goes through. The saga also sends it as an event. The event copy lands first, the slow direct call second. Release only acts on a hold still RESERVED, so the stock comes back once; the page shows both copies arrived.
- Duplicate events. A replay button sends a checkout's events again with the same ids. Inventory acts on 2 event types: one it has acted on before is skipped and counted. The other types are not its business, so it ignores them (also counted).
Here the hold arrived late: the release came first, the stock went 473 to 473, nothing held, 1 release received.
brew install redis # once: the event bus (patterns 7 and 8)
make setup # one venv per service + gateway, shop_common, frontend packages
make run # frontend :5273, gateway :8100, registry :8500, Redis :6390
make test # unit tests, each suite in its own venv
make contracts # Pact: order writes its contracts; payment, catalog and inventory verify them
make smoke # end-to-end checks against the running stackOptional: set OTEL_EXPORTER_OTLP_ENDPOINT to also send spans to an OpenTelemetry viewer or
collector. Without it, traces stay in each process's memory and the Observability page draws them.
Azure Container Apps (one app per service plus the gateway, all scale-to-zero; Redis as an always-on internal bus) + MySQL Flexible Server, on free tiers or the cheapest SKUs. About $0.21 for an 8-hour session; see cost_estimate.md. In Azure, discovery uses Container Apps DNS (no registry), and the demo switches stay off. Redis is reachable only from apps inside the environment and has no password, which is fine for a demo where every app is ours.
make github-identity # once: the Azure identity the Deploy workflow uses (OIDC, no secret)
make provision BUDGET_EMAIL=you@example.com # everything, images tagged with the current commit
# then GitHub → Actions → Deploy → Run workflow: rebuilds only the services that changed
make teardown && make verify # remove everything, then prove nothing is leftmake provision built 6 images in the cloud (67-69 MB each, tagged with the commit), deployed them
plus Redis, and created the $25 budget alert. The Azure smoke tests
(tests/smoke/test_post_provision_azure.py) passed 4 of 4: a sale settled through Redis, demo
switches answered 403, every container ran as uid 10001 on the deployed commit, and the CI-CD page
saw every service on main. The Deploy button then signed in with OIDC and correctly rebuilt
nothing. Everything was removed with make teardown the same evening, and make verify passed.
The screenshots from Azure are in patterns 3, 7
and 9 above. Details: issue #11.
Lessons from the run: GitHub now presents an OIDC subject with account and repo ids, so the
identity trusts both forms (PR #14);
make verify can time out while Azure removes an empty Container Apps environment, which takes
longer than everything else and bills nothing.
- docs/PLAN.md: the agreed plan, the M3 review decisions and the code review outcomes.
- cost_estimate.md: every Azure resource, its SKU and its cost.
- CLAUDE.md: the project's working notes, ground rules and gotchas.
- Issues: the M3b tickets, all closed.
















