Each pattern has a page that explains it, says when not to use it, and runs a live demo against the real
- services. {liveCount} of 12 are live; the last one, CI-CD, arrives in milestone M3b.
+ services. {liveCount} of 12 are live; every one has a working demo.
diff --git a/frontend/src/patterns/content.ts b/frontend/src/patterns/content.ts
index 1e073ab..8169dba 100644
--- a/frontend/src/patterns/content.ts
+++ b/frontend/src/patterns/content.ts
@@ -56,7 +56,29 @@ export const PATTERNS: PatternInfo[] = [
],
source: { label: "Martin Fowler — BoundedContext", url: "https://martinfowler.com/bliki/BoundedContext.html" },
},
- { n: 3, slug: "ci-cd-pipeline", name: "CI-CD Pipeline", what: "Builds, tests and deploys every service automatically.", milestone: "M3", live: false },
+ {
+ n: 3,
+ slug: "ci-cd-pipeline",
+ name: "CI-CD Pipeline",
+ what: "Builds, tests and deploys every service automatically.",
+ milestone: "M3",
+ live: true,
+ problem:
+ "With 5 services and a gateway, building and testing everything on every change is slow, and deploying by hand from a laptop is error-prone: nobody knows which version runs where, and one tired evening ships the wrong one.",
+ inThisProject: [
+ "Every pull request first plans its jobs from the changed files and the service table: a change to the payment service runs payment's tests and image only.",
+ "Shared code, CI itself or the service table run everything. Changing the contract consumer also runs every provider's contract check.",
+ "Every image is built for linux/amd64 in CI, started, health-checked, and rejected if it runs as root.",
+ "Deploy is a manual workflow on main. It signs in to Azure with OIDC (no stored password), rebuilds only the services that changed since the commit they run, and waits until each answers with the new commit.",
+ "Every running service reports the commit it was built from. This page marks a service behind main only when main changed its code since that build, the same rule Deploy uses.",
+ ],
+ whenNotToUse: [
+ "Path-based skipping trusts the folder layout. Code that one service imports from another folder must be declared, or a change can skip a test it should run.",
+ "Manual deploys suit a demo. A busy team usually deploys every merge automatically, behind tests and feature flags.",
+ "Rebuilding only what changed assumes services are independent. Breaking API changes still need contract tests and a deploy order.",
+ ],
+ source: { label: "Martin Fowler — Continuous Delivery", url: "https://martinfowler.com/bliki/ContinuousDelivery.html" },
+ },
{
n: 4,
slug: "circuit-breaker",
diff --git a/frontend/src/patterns/demos/CiCdDemo.tsx b/frontend/src/patterns/demos/CiCdDemo.tsx
new file mode 100644
index 0000000..b3635f8
--- /dev/null
+++ b/frontend/src/patterns/demos/CiCdDemo.tsx
@@ -0,0 +1,134 @@
+import { useEffect, useState } from "react";
+import { DeliveryStatus, DeliveryView, WorkflowRun, deliveryApi } from "../../api/gatewayClient";
+
+const PILL: Record
= {
+ current: "done",
+ unchanged: "done",
+ behind: "failed",
+ local: "pending",
+ unknown: "pending",
+};
+const LABEL: Record = {
+ current: "on latest main",
+ unchanged: "no changes since its build",
+ behind: "behind main: Deploy rebuilds it",
+ local: "local build",
+ unknown: "unknown",
+};
+
+function Run({ title, run }: { title: string; run: WorkflowRun | null }) {
+ return (
+
+
{title}
+ {run ? (
+
+
+ {run.conclusion ?? run.status}
+ {" "}
+ commit {run.commit} · {new Date(run.created_at).toLocaleString()} ·{" "}
+
+ open the run
+
+
+ ) : (
+
+ No run on main yet, or GitHub is unreachable.
+
+ )}
+
+ );
+}
+
+export default function CiCdDemo() {
+ const [view, setView] = useState(null);
+ const [error, setError] = useState(null);
+
+ useEffect(() => {
+ let active = true;
+ deliveryApi
+ .view()
+ .then((v) => active && setView(v))
+ .catch((err) => active && setError(String(err)));
+ return () => {
+ active = false;
+ };
+ }, []);
+
+ if (!view && !error) return Reading the running services and GitHub…
;
+
+ const behind = view?.services.filter((s) => s.status === "behind").length ?? 0;
+
+ return (
+
+ {error &&
{error}
}
+
+
What each running service was built from
+
+ Latest commit on main:{" "}
+ {view?.main ? (
+
+ {view.main.short}
+
+ ) : (
+ "unknown (GitHub unreachable)"
+ )}
+ . {behind > 0 ? `${behind} service(s) are behind main: the Deploy button rebuilds exactly those.` : ""}
+
+
+
+
+
+ | Service |
+ Built from |
+ Compared with main |
+
+
+
+ {view?.services.map((s) => (
+
+ |
+
+ {s.instance}
+ |
+
+ {s.git_sha ?? "–"}
+ |
+
+ {LABEL[s.status]}
+ |
+
+ ))}
+
+
+
+
+ Locally every process says "local build": make run starts the code from your working copy. In Azure, each
+ image carries the commit it was built from.
+
+
+
+
+
+
+
+
+
+
The pipeline
+
+ -
+ Pull request: a planning job reads the changed files and the service table, then runs only
+ the unit tests, contract checks and container builds that change touches. Shared code runs everything.
+
+ -
+ Merge to main: everything runs once more. One job, "CI ok", sums it all up.
+
+ -
+ Deploy (a person presses the button): signs in to Azure with OIDC (no stored password),
+ rebuilds only the services whose code changed since the commit they run, rolls them out, and waits until
+ each one answers with the new commit.
+
+
+
+
+ );
+}
diff --git a/gateway/app/main.py b/gateway/app/main.py
index e1ed06d..3d80996 100644
--- a/gateway/app/main.py
+++ b/gateway/app/main.py
@@ -4,7 +4,7 @@
from shop_common.discovery import DISCOVERY
from . import config, observability
-from .routers import patterns, resilience, services, shop
+from .routers import delivery, patterns, resilience, services, shop
app = FastAPI(
title="Microservices 12 Patterns — API Gateway",
@@ -32,6 +32,7 @@
app.include_router(shop.router)
app.include_router(patterns.router)
app.include_router(resilience.router)
+app.include_router(delivery.router)
app.include_router(services.router)
diff --git a/gateway/app/routers/delivery.py b/gateway/app/routers/delivery.py
new file mode 100644
index 0000000..1bb4b71
--- /dev/null
+++ b/gateway/app/routers/delivery.py
@@ -0,0 +1,112 @@
+"""Live demo endpoint for pattern 3 (CI-CD).
+
+Which commit each running service was built from, compared with the latest commit on main, and
+the latest CI and Deploy runs. GitHub data comes from its public REST API (this repo is public, so
+no token). Anonymous callers get 60 requests an hour, so every answer is reused for 5 minutes and
+then re-checked with its ETag: an unchanged answer (304) does not count against that limit. If
+GitHub refuses or fails, the last good answer is kept.
+"""
+import asyncio
+import os
+import time
+
+import httpx
+from fastapi import APIRouter, Request
+
+from .resilience import collect_runtimes
+
+router = APIRouter(prefix="/api/patterns", tags=["patterns"])
+
+GITHUB_REPO = os.environ.get("GITHUB_REPO", "MAOFILHO/Microservices-12-Patterns")
+CACHE_SECONDS = 300
+WORKFLOWS = {"ci": "ci.yml", "deploy": "deploy.yml"}
+TRANSPORT: httpx.AsyncBaseTransport | None = None # tests swap in a fake GitHub
+_cache: dict[str, dict] = {} # path -> {"body", "etag", "fetched_at"}; a handful of fixed paths
+
+# The same rule the Deploy workflow uses (scripts/ci_changes.py, not shipped in this image): a
+# service needs a new build when a change touches its folder or code every service shares.
+EVERY_SERVICE = ("shared/", "scripts/service_table.py")
+
+
+def _folder(service: str) -> str:
+ return "gateway/" if service == "gateway" else f"services/{service}/"
+
+
+async def github_get(path: str):
+ """GET api.github.com, reused for CACHE_SECONDS, then revalidated with its ETag."""
+ entry = _cache.get(path)
+ if entry and time.monotonic() - entry["fetched_at"] < CACHE_SECONDS:
+ return entry["body"]
+ headers = {"Accept": "application/vnd.github+json"}
+ if entry and entry.get("etag"):
+ headers["If-None-Match"] = entry["etag"]
+ try:
+ async with httpx.AsyncClient(timeout=5, transport=TRANSPORT) as client:
+ response = await client.get(f"https://api.github.com{path}", headers=headers)
+ if response.status_code == 304 and entry:
+ body, etag = entry["body"], entry.get("etag")
+ elif response.status_code == 200:
+ body, etag = response.json(), response.headers.get("ETag")
+ else: # rate limited or down: keep the last good answer, if any
+ body, etag = (entry or {}).get("body"), (entry or {}).get("etag")
+ except (httpx.HTTPError, ValueError):
+ body, etag = (entry or {}).get("body"), (entry or {}).get("etag")
+ _cache[path] = {"body": body, "etag": etag, "fetched_at": time.monotonic()}
+ return body
+
+
+async def _latest_run(name: str, file: str) -> dict | None:
+ body = await github_get(f"/repos/{GITHUB_REPO}/actions/workflows/{file}/runs?branch=main&per_page=1")
+ runs = body.get("workflow_runs") if isinstance(body, dict) else None
+ run = runs[0] if runs else None
+ if not isinstance(run, dict) or not run.get("html_url"):
+ return None
+ return {"workflow": name, "status": run.get("status"), "conclusion": run.get("conclusion"),
+ "commit": (run.get("head_sha") or "")[:12], "url": run["html_url"], "created_at": run.get("created_at")}
+
+
+async def _changed_files(commit: str, main_sha: str) -> list[str] | None:
+ body = await github_get(f"/repos/{GITHUB_REPO}/compare/{commit}...{main_sha}")
+ files = body.get("files") if isinstance(body, dict) else None
+ return [f.get("filename", "") for f in files] if isinstance(files, list) else None
+
+
+def _status(process: dict, main_sha: str | None, changed: dict[str, list[str] | None]) -> str:
+ """current: built from main. behind: main has changes for it (Deploy would rebuild it).
+ unchanged: built from an older commit, but nothing of its code changed since. local / unknown."""
+ commit = process.get("git_sha")
+ if process.get("unreachable") or not commit or commit == "unknown":
+ return "unknown"
+ if commit == "local":
+ return "local"
+ if main_sha is None:
+ return "unknown"
+ if main_sha.startswith(commit):
+ return "current"
+ files = changed.get(commit)
+ if files is None:
+ return "unknown"
+ touches = (_folder(process["service"]), *EVERY_SERVICE)
+ return "behind" if any(f.startswith(touches) for f in files) else "unchanged"
+
+
+@router.get("/delivery")
+async def delivery(request: Request):
+ head, ci, deploy, processes = await asyncio.gather(
+ github_get(f"/repos/{GITHUB_REPO}/commits/main"),
+ _latest_run("ci", WORKFLOWS["ci"]),
+ _latest_run("deploy", WORKFLOWS["deploy"]),
+ collect_runtimes(request),
+ )
+ main_sha = head.get("sha") if isinstance(head, dict) else None
+ main = {"sha": main_sha, "short": main_sha[:12], "url": head.get("html_url")} if main_sha else None
+
+ older = sorted({p.get("git_sha") for p in processes
+ if p.get("git_sha") and p.get("git_sha") not in ("local", "unknown")
+ and not (main_sha or "").startswith(p.get("git_sha"))})
+ compared = await asyncio.gather(*(_changed_files(c, main_sha) for c in older)) if main_sha else []
+ changed = dict(zip(older, compared))
+
+ services = [{"service": p["service"], "instance": p["instance"], "git_sha": p.get("git_sha"),
+ "status": _status(p, main_sha, changed)} for p in processes]
+ return {"repo": GITHUB_REPO, "main": main, "services": services, "runs": {"ci": ci, "deploy": deploy}}
diff --git a/gateway/app/routers/resilience.py b/gateway/app/routers/resilience.py
index d20caa5..eaaf201 100644
--- a/gateway/app/routers/resilience.py
+++ b/gateway/app/routers/resilience.py
@@ -178,8 +178,7 @@ async def set_bus(body: BusSwitch):
# --- Pattern 9: Containerization ---------------------------------------------------------------
-@router.get("/runtime")
-async def runtime(request: Request):
+async def collect_runtimes(request: Request) -> list[dict]:
"""How every process runs: as root or not, in a container or not, which build (git SHA)."""
async def one(service: str, base: str) -> dict:
try:
@@ -191,4 +190,9 @@ async def one(service: str, base: str) -> dict:
async with _client() as client:
targets = [(n, url) for n in config.SERVICE_BASE_URLS for url in config.urls_for(n)]
services = await asyncio.gather(*(one(n, url) for n, url in targets))
- return {"processes": [runtime_info("gateway", "gateway"), *services]}
+ return [runtime_info("gateway", "gateway"), *services]
+
+
+@router.get("/runtime")
+async def runtime(request: Request):
+ return {"processes": await collect_runtimes(request)}
diff --git a/gateway/tests/test_delivery.py b/gateway/tests/test_delivery.py
new file mode 100644
index 0000000..a4b4973
--- /dev/null
+++ b/gateway/tests/test_delivery.py
@@ -0,0 +1,107 @@
+"""Pattern 3 page: which commit each service runs, compared with main the way Deploy decides, plus
+the latest CI and Deploy runs. GitHub is faked at the HTTP layer: no network in unit tests."""
+import asyncio
+
+import httpx
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+from app.routers import delivery
+
+client = TestClient(app)
+MAIN = "abc123def4567890abc123def4567890abc12345"
+REPO = delivery.GITHUB_REPO
+
+
+def github_reply(request: httpx.Request) -> httpx.Response:
+ """A fake api.github.com: main's head, a compare per old commit, the latest workflow runs."""
+ path = request.url.path
+ if path.endswith("/commits/main"):
+ return httpx.Response(200, json={"sha": MAIN, "html_url": "https://github.com/x/commit/abc"})
+ if "/compare/" in path:
+ old = path.split("/compare/")[1].split("...")[0]
+ files = {"0ld0ld0ld0ld": ["services/order/application/saga.py"], # order changed since
+ "5ame5ame5ame": ["README.md", "services/order/run.py"]}[old] # nothing of payment's
+ return httpx.Response(200, json={"files": [{"filename": f} for f in files]})
+ workflow = path.split("/workflows/")[1].split("/")[0]
+ return httpx.Response(200, json={"workflow_runs": [{
+ "status": "completed", "conclusion": "success", "head_sha": MAIN,
+ "html_url": f"https://github.com/{REPO}/actions/runs/{workflow}", "created_at": "2026-11-15T20:00:00Z"}]})
+
+
+@pytest.fixture(autouse=True)
+def _fake_github_and_services(monkeypatch):
+ delivery._cache.clear()
+ monkeypatch.setattr(delivery, "TRANSPORT", httpx.MockTransport(github_reply))
+
+ async def runtimes(request):
+ return [
+ {"service": "gateway", "instance": "gateway", "git_sha": "abc123def456"},
+ {"service": "order", "instance": "order-1", "git_sha": "0ld0ld0ld0ld"},
+ {"service": "payment", "instance": "payment-1", "git_sha": "5ame5ame5ame"},
+ {"service": "user", "instance": "user-5101", "git_sha": "local"},
+ {"service": "catalog", "instance": "catalog-1", "unreachable": True},
+ ]
+
+ monkeypatch.setattr(delivery, "collect_runtimes", runtimes)
+
+
+def test_behind_means_what_deploy_means():
+ """Deploy rebuilds only services whose code changed, so the page must not call the rest 'behind'."""
+ status = {s["instance"]: s["status"] for s in client.get("/api/patterns/delivery").json()["services"]}
+ assert status == {"gateway": "current", "order-1": "behind", "payment-1": "unchanged",
+ "user-5101": "local", "catalog-1": "unknown"}
+
+
+def test_latest_ci_and_deploy_runs_are_linked():
+ runs = client.get("/api/patterns/delivery").json()["runs"]
+ assert runs["ci"]["conclusion"] == "success" and runs["ci"]["url"].endswith("/runs/ci.yml")
+ assert runs["deploy"]["url"].endswith("/runs/deploy.yml")
+
+
+def test_github_answers_are_reused_for_five_minutes(monkeypatch):
+ calls = []
+ monkeypatch.setattr(delivery, "TRANSPORT", httpx.MockTransport(lambda r: calls.append(r) or github_reply(r)))
+ client.get("/api/patterns/delivery")
+ first = len(calls)
+ client.get("/api/patterns/delivery")
+ assert len(calls) == first
+
+
+def test_after_five_minutes_an_unchanged_answer_costs_no_rate_limit(monkeypatch):
+ """GitHub does not count a 304 Not Modified against the 60-per-hour limit."""
+ seen = []
+
+ def reply(request):
+ seen.append(request.headers.get("if-none-match"))
+ if request.headers.get("if-none-match") == '"v1"':
+ return httpx.Response(304)
+ return httpx.Response(200, json={"sha": MAIN, "html_url": "u"}, headers={"ETag": '"v1"'})
+
+ monkeypatch.setattr(delivery, "TRANSPORT", httpx.MockTransport(reply))
+ assert asyncio.run(delivery.github_get("/x"))["sha"] == MAIN
+ delivery._cache["/x"]["fetched_at"] -= delivery.CACHE_SECONDS + 1
+ assert asyncio.run(delivery.github_get("/x"))["sha"] == MAIN
+ assert seen == [None, '"v1"']
+
+
+def test_a_rate_limited_github_keeps_the_last_good_answer(monkeypatch):
+ monkeypatch.setattr(delivery, "TRANSPORT", httpx.MockTransport(github_reply))
+ assert asyncio.run(delivery.github_get(f"/repos/{REPO}/commits/main"))["sha"] == MAIN
+ delivery._cache[f"/repos/{REPO}/commits/main"]["fetched_at"] -= delivery.CACHE_SECONDS + 1
+ monkeypatch.setattr(delivery, "TRANSPORT", httpx.MockTransport(lambda r: httpx.Response(403)))
+ assert asyncio.run(delivery.github_get(f"/repos/{REPO}/commits/main"))["sha"] == MAIN
+
+
+def test_github_down_or_odd_still_shows_the_services(monkeypatch):
+ for transport in [httpx.MockTransport(lambda r: httpx.Response(503)),
+ httpx.MockTransport(lambda r: httpx.Response(200, json={"unexpected": True})),
+ httpx.MockTransport(lambda r: httpx.Response(200, text="not json"))]:
+ delivery._cache.clear()
+ monkeypatch.setattr(delivery, "TRANSPORT", transport)
+ r = client.get("/api/patterns/delivery")
+ assert r.status_code == 200
+ body = r.json()
+ assert body["main"] is None and body["runs"] == {"ci": None, "deploy": None}
+ assert {s["status"] for s in body["services"]} <= {"unknown", "local"}