Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ ORDER_SERVICE_PORT=5103
PAYMENT_SERVICE_PORT=5104
INVENTORY_SERVICE_PORT=5105
GATEWAY_PORT=8100
REGISTRY_PORT=8500
FRONTEND_PORT=5273

# --- Service base URLs (used by the gateway and by services calling each other) ---
Expand All @@ -26,6 +27,19 @@ ORDER_SERVICE_BASE_URL=http://127.0.0.1:5103
PAYMENT_SERVICE_BASE_URL=http://127.0.0.1:5104
INVENTORY_SERVICE_BASE_URL=http://127.0.0.1:5105

# --- Service discovery (pattern 12) ---
# make run sets this; with it unset, callers use the fixed URLs above (as in unit tests and Azure).
# REGISTRY_URL=http://127.0.0.1:8500

# --- Demo switches (patterns 4, 10, 12) ---
# make run sets CHAOS_ENABLED=1 so the pages can stop a replica and break payment. Keep it off anywhere public.
# CHAOS_ENABLED=1

# --- Login tokens (pattern 10) ---
# The user service signs tokens with this RSA private key. Unset locally: it creates
# services/user/instance/jwt_private.pem on first start (git-ignored). Never commit a real key.
# JWT_PRIVATE_KEY_PEM=

# --- SQLite (local mode, default) ---
# Optional overrides — each path is relative to that service's own directory.
# Leave unset to use instance/<service>.sqlite3 inside each service folder.
Expand Down
16 changes: 16 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ jobs:
requirements: gateway/requirements.txt
tests: gateway/tests
shared: fastapi
- suite: registry
requirements: registry/requirements.txt
tests: registry/tests
- suite: user
requirements: services/user/requirements.txt
tests: services/user/tests
Expand All @@ -33,14 +36,17 @@ jobs:
requirements: services/catalog/requirements.txt
tests: services/catalog/tests
shared: flask
contracts: true
- suite: order
requirements: services/order/requirements.txt
tests: services/order/tests
shared: flask
contracts: true
- suite: payment
requirements: services/payment/requirements.txt
tests: services/payment/tests
shared: flask
contracts: true
- suite: inventory
requirements: services/inventory/requirements.txt
tests: services/inventory/tests
Expand All @@ -61,9 +67,19 @@ jobs:
if: matrix.shared
run: pip install "./shared[${{ matrix.shared }}]"

- name: Install Pact (contract tests)
if: matrix.contracts
run: pip install -r contracts/requirements.txt

- name: Run tests
run: python -m pytest ${{ matrix.tests }} -v

# The order suite regenerates the contracts it consumes. If they differ from the committed
# files, the consumer changed what it needs without committing the new contract.
- name: Contracts are up to date
if: matrix.suite == 'order'
run: git diff --exit-code contracts/pacts

frontend:
name: Frontend (build)
runs-on: ubuntu-latest
Expand Down
57 changes: 32 additions & 25 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,34 +27,41 @@ history, monolith dropped). The full agreed plan is in [`docs/PLAN.md`](docs/PLA
- Name prefix: `ms12p` (parent uses `flaskms`). Teardown deletes the whole resource group, so a
shared name would delete the other project.

## Current state (M1, foundation: patterns 1, 2, 5, 6 live)
## Current state (M2: patterns 1, 2, 4, 5, 6, 10, 11, 12 live)
- Folders: `services/{user,catalog,order,payment,inventory}/` (Flask, one DB each), `gateway/`
(FastAPI), `shared/` (`shop_common`), `frontend/`, `infra/`, `scripts/`, `tests/`.
- **One service table**: `scripts/service_table.py` lists every local process, folder and port.
`setup.py`, `run_local.py`, `provision.py` and the smoke tests all read it. Add a service there.
- Ports: user 5101, catalog 5102, order 5103, payment 5104, inventory 5105, gateway 8100,
frontend 5273 (registry 8500 arrives in M2).
(FastAPI), `registry/` (FastAPI), `shared/` (`shop_common`), `contracts/`, `frontend/`, `infra/`,
`scripts/`, `tests/`.
- **One service table**: `scripts/service_table.py` lists every local process, folder and port, plus
`REPLICA_PORTS` (order also on 5113) and `CONTRACT_SUITES`. `setup.py`, `run_local.py`,
`provision.py` and the smoke tests all read it. Add a service there.
- Ports: user 5101, catalog 5102, order 5103 + 5113, payment 5104, inventory 5105, gateway 8100,
registry 8500, frontend 5273.
- **`shop_common`** (`shared/`): every service calls `shop_common.flask_support.install(app, name, db)`
inside its app context. It adds `/health`, `/health/db`, `/debug/spans`, `/metrics`, OpenTelemetry
tracing (Flask, requests, SQLAlchemy per engine), JSON logs with trace/request IDs, and metrics.
The gateway uses `gateway/app/observability.py` (FastAPI + httpx). `setup.py` installs `shared/`
editable into every venv; `provision.py` stages it as `<service>/_shared` for `az acr build`.
- Traces: each process keeps its last 2,000 spans in memory (`SPAN_STORE`); the gateway stitches a
trace from every service's `/debug/spans`. Database span names are trimmed to the file name so
no local path leaks. Containers run gunicorn with 1 worker + 4 threads so one process holds all
spans. `OTEL_EXPORTER_OTLP_ENDPOINT` optionally exports too.
- Gotchas solved: FastAPI tracing middleware must be added AFTER the request-ID middleware (the
last-added Starlette middleware runs outermost); Flask-SQLAlchemy's engine is missed by the
global SQLAlchemy hook, so it is instrumented per engine; the httpx hook only loads where httpx
is installed.
- Gateway: `/api/shop/<path>` (GET/POST only) routed by `ROUTE_OWNERS`; `/api/order-summary`
aggregation; demo endpoints in `gateway/app/routers/patterns.py`. No auth check yet (JWT is M2).
- The catalog service keeps the `product` resource name in its API (`/api/product(s)`). The
unauthenticated `DELETE /api/product/<slug>` was removed.
- Frontend: `/patterns` grid, `/patterns/:slug` page from `frontend/src/patterns/content.ts`, demos
in `frontend/src/patterns/demos/`. Signed-in user is read from localStorage `shop_auth`.
inside its app context. It adds `/health`, `/health/db`, `/debug/spans`, `/metrics`,
`POST /debug/crash` (only with `CHAOS_ENABLED=1`), the `X-Instance-Id` header, tracing, JSON logs,
metrics, and registry heartbeats when `SERVICE_PUBLIC_URL` and `REGISTRY_URL` are set.
`auth.py` verifies RS256 tokens; `discovery.py` heartbeats and round-robins (urllib, so no spans);
`contract_testing.py` runs Pact provider verification. `setup.py` installs `shared/` editable;
`provision.py` stages it as `<service>/_shared` for `az acr build`.
- Tokens (pattern 10): the user service signs (key from `JWT_PRIVATE_KEY_PEM`, else
`services/user/instance/jwt_private.pem`, git-ignored). Gateway and order verify with
`/api/user/public-key`. Flask-Login and the `api_key` column are gone. Frontend sends `Bearer`.
- Gateway: rejects `order` paths with a bad token at the edge; `config.url_for()` round-robins via
the registry, falls back to `SERVICE_BASE_URLS`; the shop proxy fails over to the next replica on a
refused connection. Trace stitching and metrics read every replica (`config.urls_for()`).
- Circuit breaker (pattern 4): `services/order/application/order_api/api/clients.py`, pybreaker
(3 failures, 15 s) + tenacity (1 retry, 1 s timeout), only 5xx/timeouts count. Checkout prices from
catalog, charges payment, keeps the cart on 503. Payment has a `healthy|failing|slow` switch.
- Contracts (pattern 11): order's tests write `contracts/pacts/order-{payment,catalog}.json`; payment
and catalog verify them. CI fails if the regenerated files differ. Pact (pact-python 4.2) is
test-only, installed from `contracts/requirements.txt`, never in images.
- `make run` sets `REGISTRY_URL`, `CHAOS_ENABLED=1`, `INSTANCE_ID`, and restarts a stopped service
after 20 s. Registry TTL 10 s, heartbeat 2 s. Azure uses Container Apps DNS (no registry yet).
- Gotchas solved: FastAPI tracing middleware must be added AFTER the request-ID middleware; Flask-
SQLAlchemy's engine is instrumented per engine; Pact's `Verifier` needs `host="127.0.0.1"`; DB writes
inside a Pact state handler deadlock on SQLite (seed before verifying instead).
- Smoke tests create users and products in the local SQLite DBs; delete `services/*/instance/`
for a clean catalog.
for a clean catalog (this also deletes the local signing key, which logs everyone out).

## Stack
Python 3.12 (Flask 3.1 services, FastAPI gateway), Node 18+ (React 18, TypeScript 5, Vite 5),
Expand Down
9 changes: 8 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.PHONY: setup run provision pause resume teardown verify test smoke clean
.PHONY: setup run provision pause resume teardown verify test contracts smoke clean

setup:
python3.12 scripts/setup.py
Expand Down Expand Up @@ -29,6 +29,13 @@ test:
services/payment/.venv/bin/python -m pytest services/payment/tests -v
services/inventory/.venv/bin/python -m pytest services/inventory/tests -v
gateway/.venv/bin/python -m pytest gateway/tests -v
registry/.venv/bin/python -m pytest registry/tests -v

# Pattern 11 only: the order service writes its contracts, then payment and catalog verify them.
contracts:
services/order/.venv/bin/python -m pytest services/order/tests/test_contracts_consumer.py -v
services/payment/.venv/bin/python -m pytest services/payment/tests/test_contract_provider.py -v
services/catalog/.venv/bin/python -m pytest services/catalog/tests/test_contract_provider.py -v

smoke:
.venv/bin/python -m pytest tests/smoke -v
Expand Down
70 changes: 52 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@ A small Contoso e-commerce system that shows **12 microservices patterns working
Each pattern gets its own page with an explanation, when *not* to use it, and a live demo you
can click.

> **Status: M1, foundation.** 4 of 12 patterns are live: Database per Service, Bounded Context,
> API Gateway and Observability. The foundation is copied from
> **Status: M2, resilience and independence.** 8 of 12 patterns are live: M1's Database per
> Service, Bounded Context, API Gateway and Observability, plus M2's Circuit Breaker, Stateless
> Services, Contract Testing and Service Discovery. The foundation is copied from
> [Azure-Ecommerce-Monolith-Microservices-Migration](https://github.com/MAOFILHO/Azure-Ecommerce-Monolith-Microservices-Migration).
> The rest arrive in milestones M2 and M3. See [docs/PLAN.md](docs/PLAN.md).
> The last 4 arrive in milestone M3. See [docs/PLAN.md](docs/PLAN.md).

## The 12 patterns

Expand All @@ -16,36 +17,41 @@ can click.
| 1 | Database per Service | Gives each service its own database | **Live (M1)** |
| 2 | Bounded Context | Splits one large domain into clear business domains | **Live (M1)** |
| 3 | CI-CD Pipeline | Builds, tests and deploys every service automatically | M3 |
| 4 | Circuit Breaker | Stops calls to a failing service to prevent more failures | M2 |
| 4 | Circuit Breaker | Stops calls to a failing service to prevent more failures | **Live (M2)** |
| 5 | API Gateway | Routes client requests to the right service | **Live (M1)** |
| 6 | Observability | Collects logs, metrics and traces from every service | **Live (M1)** |
| 7 | Event-Driven Architecture | Services communicate by publishing and consuming events | M3 |
| 8 | Saga Pattern | Coordinates distributed transactions and rolls back failures safely | M3 |
| 9 | Containerization | Packages each service with all its dependencies | M3 |
| 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 |
| 10 | Stateless Services | Stores session data outside the service | **Live (M2)** |
| 11 | Contract Testing | Checks that APIs stay compatible across services | **Live (M2)** |
| 12 | Service Discovery | Finds service instances automatically at runtime | **Live (M2)** |

## Architecture today

```
Browser → API gateway ──┬──► user → user_db
(request IDs, ├──► catalog → catalog_db
tracing, metrics, ├──► order → order_db ──HTTP──► user (validates the caller)
aggregation) ├──► payment → payment_db
└──► inventory → inventory_db
Browser → API gateway ──┬──► user → user_db (signs login tokens)
(checks tokens, ├──► catalog → catalog_db
request IDs, ├──► order ×2 → order_db ──► catalog (prices)
tracing, metrics, │ └─► payment, behind a circuit breaker
aggregation, ├──► payment → payment_db
failover) └──► inventory → inventory_db

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.
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, and the `/health/db`, `/debug/spans`, `/metrics` endpoints every service exposes.
metrics, the `/health/db`, `/debug/spans`, `/metrics` endpoints, token checks and the discovery client.
- **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 and catalog to honour.
- **React + TypeScript** frontend (`frontend/`) with a page per pattern.

Still to come: service registry, JWT and replicas, circuit breaker, Pact contract tests (M2);
Redis Streams events with an outbox, checkout saga, hardened containers, deploy pipeline (M3).
Still to come (M3): Redis Streams events with an outbox, checkout saga, hardened containers,
deploy pipeline, and a real Azure run.

## The live demos

Expand Down Expand Up @@ -73,12 +79,39 @@ database queries, drawn as a waterfall. Metrics per service come from each `/met

<img width="100%" alt="Observability demo: a trace waterfall across gateway, user, order, catalog and inventory" src="docs/screenshots/p06-observability.jpg" />

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

<img width="100%" alt="Circuit Breaker demo: both order replicas' breakers open; failed calls take 2.2 s, short-circuited calls 0 ms" src="docs/screenshots/p04-circuit-breaker.jpg" />

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

<img width="100%" alt="Stateless Services demo: one order replica stopped, all 6 cart requests still succeed on the other" src="docs/screenshots/p10-stateless-services.jpg" />

### 11. Contract Testing
The order service's contracts with payment and catalog, read from the committed Pact files, and
the real CI output when payment renames one field the order service relies on.

<img width="100%" alt="Contract Testing demo: the contract break output and how CI runs consumer and provider checks" src="docs/screenshots/p11-contract-testing.jpg" />

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

<img width="100%" alt="Service Discovery demo: registry table and an expired then re-registered order replica" src="docs/screenshots/p12-service-discovery.jpg" />

## Run locally (no Docker)

```bash
make setup # one venv per service + gateway, shop_common, frontend packages
make run # frontend http://127.0.0.1:5273, gateway http://127.0.0.1:8100
make run # frontend http://127.0.0.1:5273, gateway http://127.0.0.1:8100, registry :8500
make test # unit tests, each suite in its own venv
make contracts # Pact: order writes its contracts, payment and catalog verify them
make smoke # end-to-end checks against the running stack
```

Expand All @@ -89,4 +122,5 @@ collector. Without it, traces stay in each process's memory and the Observabilit

Azure Container Apps (one app per service plus the gateway, all scale-to-zero) + MySQL Flexible
Server, provisioned with `make provision` and removed with `make teardown`. About $0.21 for an
8-hour session. See [cost_estimate.md](cost_estimate.md). Nothing from M1 has been deployed yet.
8-hour session. See [cost_estimate.md](cost_estimate.md). Nothing from M1 or M2 has been deployed
yet. In Azure, discovery uses Container Apps DNS (no registry), and the demo switches stay off.
82 changes: 82 additions & 0 deletions contracts/pacts/order-catalog.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
{
"consumer": {
"name": "order"
},
"interactions": [
{
"description": "a request for every product and its price",
"pending": false,
"providerStates": [
{
"name": "products exist"
}
],
"request": {
"method": "GET",
"path": "/api/products"
},
"response": {
"body": {
"content": {
"results": [
{
"id": 1,
"price": 1299
}
]
},
"contentType": "application/json",
"encoded": false
},
"headers": {
"Content-Type": [
"application/json"
]
},
"matchingRules": {
"body": {
"$.results": {
"combine": "AND",
"matchers": [
{
"match": "type",
"min": 1
}
]
},
"$.results[*].id": {
"combine": "AND",
"matchers": [
{
"match": "integer"
}
]
},
"$.results[*].price": {
"combine": "AND",
"matchers": [
{
"match": "integer"
}
]
}
}
},
"status": 200
},
"type": "Synchronous/HTTP"
}
],
"metadata": {
"pactRust": {
"ffi": "0.5.12",
"models": "1.3.16"
},
"pactSpecification": {
"version": "4.0"
}
},
"provider": {
"name": "catalog"
}
}
Loading
Loading