Skip to content

About

12 microservices patterns, each with a live demo: Flask services, FastAPI gateway, React, Azure Container Apps

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Microservices 12 Patterns

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.

Project summary

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. main requires 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.

The 12 patterns

# 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

Architecture

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, /metrics endpoints, 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-server locally, 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.

The live demos

1. Database per Service

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.

Database per Service demo: 5 services each own their tables; the order service is blocked from reading the catalog's product table

2. Bounded Context

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.

Bounded Context demo: context map and one product seen by Catalog and by Inventory

3. CI-CD Pipeline

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":

CI-CD demo locally: each service is a local build, with the latest CI run on main

In Azure, every service runs the latest commit of main:

CI-CD page in Azure: every service on the latest commit of main

4. Circuit Breaker

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.

Circuit Breaker demo: both order replicas' breakers open; failed calls take 2.2 s, short-circuited calls 0 ms

5. API Gateway

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.

API Gateway demo: one browser call fans out to user, order, catalog and inventory

6. Observability

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.

Observability demo: a trace waterfall across gateway, user, order, catalog and inventory

7. Event-Driven Architecture

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.

Event-Driven demo: bus disconnected, 3 events waiting in the outbox, one mug held

In Azure, the same 3 events were published within a second through the Redis Container App, and inventory sold the reservation:

Event-Driven page in Azure: 3 events published within a second; inventory sold the reservation

8. Saga Pattern

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.

Saga demo: a declined card, with the stock hold released by the compensation step

9. Containerization

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.

Containerization demo locally: every process, its uid and platform, and the Dockerfile shape

In Azure, all 6 run in containers as uid 10001 on linux/x86_64, built from one commit, 67-69 MB each:

Containerization page in Azure: 6 containers, uid 10001, linux/x86_64, built from one commit, 67-69 MB

10. Stateless Services

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.

Stateless Services demo: one order replica stopped, all 6 cart requests still succeed on the other

11. Contract Testing

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.

Contract Testing demo: the contract break output and how CI runs consumer and provider checks

12. Service Discovery

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.

Service Discovery demo: registry table and an expired then re-registered order replica

13. Saga under a slow payment

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.

Demo 13: payment slowed mid-checkout; the order waits as pending, then settles as 1 charge, 1 order, 2 mugs sold

14. Compensation under fire

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.

Demo 14: inventory holds slowly; the saga's release arrives first, the late hold holds nothing, and the stock ends where it began

Run locally (no Docker)

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 stack

Optional: 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.

Run in Azure

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 left

The Azure run

make 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.

Project docs

  • 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.

About

12 microservices patterns, each with a live demo: Flask services, FastAPI gateway, React, Azure Container Apps

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages