A monolith that works is not a problem to delete. It is a system to grow out of, one route at a time. This lesson teaches the named moves I reach for when an app outgrows one codebase: the strangler fig, CQRS, the valet key, the ambassador, the BFF, geodes, deployment stamps, the claim check, the anti-corruption layer, the priority queue, the materialized view, and static content hosting. Event sourcing gets one paragraph here, because Lesson 28 already teaches it properly. The lesson closes with performance antipatterns, because every pattern in this list has a way to go wrong, and the wrong way has a name too.
Difficulty: Advanced · Know this first: Lesson 01, Lesson 07, Lesson 15, Lesson 26, Lesson 28
By the end of this lesson you will have run one checkout through thirteen named patterns and you will know which one to reach for next time. First, a strangler router script that routes 100 orders and proves the split is 60 new and 40 legacy. Second, a claim check script that stores a 480,000 byte receipt and sends a 59 byte ticket down the queue instead. Third, a retry schedule you can read out loud: three tries, waits of 100, 200, and 400 ms, then stop. You will also know the antipattern beside each pattern, so you can spot a retry storm before it pages you.
What you need: Python 3 on your own machine for the lab scripts. No cloud account, no live service, no API key. The scripts run locally and their outputs are shown exactly as they ran. The cloud pieces in this lesson, the stamps and the geodes, are designs you build in your own account, and the lesson says so where it matters.
Our ordering app started as one codebase. It worked. Then it grew, and the growth hurt in a specific way. New orders wanted a fast write path. Refunds wanted the old rules. The phone app wanted a small payload. The receipt was too big for the queue. The database served reads and writes from the same table, and both got slower together. No single rewrite fixes that. Thirteen small moves do.
Each move has a name, a job, and a place in the checkout you are about to walk. Learn the table first. The diagram after it is the same table, drawn as a trip.
| Pattern | The job it does | Where it sits in this checkout |
|---|---|---|
| Backend for Frontend (BFF) | Shapes one answer per client type | Hop 1. The phone gets a small payload. |
| Ambassador | Retries, timeouts, and logging beside the service | Hop 2. The sidecar that calls the network. |
| Strangler Fig | Moves one route at a time off the monolith | Hop 3. The router that picks new or legacy. |
| Anti-Corruption Layer | Translates the old model at the boundary | Hop 4. The old statuses never leak in. |
| CQRS | Splits the write side from the read side | Hop 5. The command side takes the order. |
| Materialized View | A read copy built for one question | Hop 6. The confirmation screen reads the copy. |
| Claim Check | Stores the big payload, sends a ticket | Hop 7. The receipt travels by ticket. |
| Deployment Stamps | One full copy of the system per region | Hop 8. The home stamp stores the order. |
| Geodes | Stamps placed close to the customer | Hop 8, by placement. The near stamp answers. |
| Priority Queue | Urgent work jumps the line, on purpose | Between hops 5 and 6. Paid orders first. |
| Valet Key | A short-lived key for a direct upload | Path 3. The client uploads straight to storage. |
| Static Content Hosting | Files served from storage, not from the app | Go deeper. The product images never touch the app. |
| Gateway Offloading | Auth and rate limits move to the gateway | Go deeper. The app stops checking tokens. |
| Event Sourcing | Every change is an event in the log | Taught in Lesson 28. One paragraph recap in Go deeper. |
Two names in that table get confused the most, so here is the split in one line each. The ambassador rides beside one service and speaks for it. The gateway sits in front of all services and speaks for the edge. The BFF shapes answers per client. The anti-corruption layer translates models per boundary. Four different jobs, four different places, and each one fails in its own way when it takes on the other's job.
Write down the three patterns your own system already uses, without looking them up. Most teams use at least three and name none of them. Then read the table again and name the one pattern your system needs most. That is the pattern to watch for in the diagram. The rest of the lesson is the same table, running.
The diagram above follows one checkout through nine hops. These four paths are the same idea drawn four ways. One checkout, clean. One checkout, sent the old way. One receipt, uploaded direct. One afternoon, retried into a storm. Run each path. One run takes 7.2 seconds across the path, so you can watch each hop light up in turn.
The return rule: the green dot only starts moving after the orange dot reaches the data hop. A return with no request is a lie. The diagram never draws one. The failure replay at the end of Run all four shows the other side of the rule. Run it and watch the orange dot stop at the ambassador and never come back.
One checkout walks the new path. BFF, ambassador, strangler, CQRS write, stamped store. The receipt is small here, so no claim check is needed. The write lands in 42 ms and the answer starts back.
Not run yet.
Same checkout, on a route the monolith still owns. The strangler sends it the old way, the anti-corruption layer translates fifteen status codes down to four, and the old database takes 120 ms to write. Run it and watch the dot stop at the legacy database. That is the failure this path replays.
Not run yet.
The receipt is 480 KB, so the app never touches the bytes. The BFF asks for a short-lived valet key, the client uploads straight to storage, and the stamped store records the order. The upload is the slow hop at 20 ms, and the app stayed out of the way.
Not run yet.
The same checkout while the write side is slow. The ambassador retries three times, so the write hop costs 180 ms instead of 42 ms. The rest of the hops do not change. A storm is an ambassador problem, and the diagram shows it in one hop.
Not run yet.
Every hop charges rent in milliseconds. The bar below is a worked example for one checkout through the new design, not a measurement from a live system, but the shape is honest. The write hop is the big one at 42 ms. The translation layer is the second biggest at 14 ms, because the old model has more words than the new one. Switch the scenario and watch the bar change. In the legacy story the write hop grows to 120 ms and the read view to 90 ms. In the storm story the ambassador hop grows to 48 ms and the write hop to 180 ms. Move a simulator slider and watch the translation, write, read, and claim hops move with it.
The budget bar above shows three fixed stories. This simulator lets you write your own. It answers the trade-off at the heart of this lesson: every order still on the monolith pays translation and a slow write, and every concurrent checkout pays queueing on the write hop. You set how many checkouts run at once, how much of the traffic the new service owns, how many orders are priority, and how big the receipt is. Move a slider and watch the four moving hops and the budget total change. The numbers are a teaching example, built from the formulas below, not live measurements. The shape is the lesson: the strangler percentage is the cheapest performance fix in the whole design.
How many checkouts run at once. Each one adds 0.6 ms to the write hop, because the write side queues.
The strangler share. Every point still on the monolith pays translation: 8 ms plus 0.15 ms per point left behind.
Orders that jump the queue. Each priority point cuts 0.8 ms off the read hop, because the view builds their answer first.
The receipt the worker needs. The claim check stores it, so the hop costs 6 ms plus 0.04 ms per KB, and the queue never sees it.
Try this: set 5 checkouts, 90% new, 20% priority, 50 KB, and watch the budget fall to 88.5 ms. Then set 80 checkouts, 20% new, 0% priority, 400 KB, and watch it climb to 174 ms. The strangler slider moves the total more than any other control. That is the migration, priced.
Do this now, on your own machine. You will run the strangler router, prove the 60/40 split, and run the claim check, proving the queue carries a ticket instead of a receipt. Both scripts run on Python 3 with no extra packages. Their outputs are shown exactly as they ran.
Save this file as strangler_router.py. It routes 100 orders by the table at the top: create, get, and cancel go to the new service, list, refund, and export stay on the monolith. Routing is deterministic, so a rerun gives the same split. Run it and check the counts.
"""Strangler router for Lesson 189.
One router, two systems. New orders go to the new service, old orders
stay on the monolith, and the cutover moves one route at a time.
Routing is deterministic: order id modulo 100, so a rerun gives the
same split and the numbers below are reproducible.
"""
NEW_SHARE = 60 # percent of orders routed to the new service
ROUTES = {
"create_order": "new",
"get_order": "new",
"cancel_order": "new",
"list_orders": "legacy",
"refund_order": "legacy",
"export_orders": "legacy",
}
def route(order_id):
"""Return 'new' or 'legacy' for one order id."""
return "new" if (order_id * 37) % 100 < NEW_SHARE else "legacy"
def main():
counts = {"new": 0, "legacy": 0}
first_ten = []
for order_id in range(1, 101):
dest = route(order_id)
counts[dest] += 1
if order_id <= 10:
first_ten.append((order_id, dest))
print("orders routed: 100")
print("new service:", counts["new"])
print("legacy monolith:", counts["legacy"])
print("first ten:", first_ten)
print("routes by name:")
for name, dest in ROUTES.items():
print(" ", name, "->", dest)
if __name__ == "__main__":
main()
Output, exactly as it ran:
orders routed: 100 new service: 60 legacy monolith: 40 first ten: [(1, 'new'), (2, 'legacy'), (3, 'new'), (4, 'new'), (5, 'legacy'), (6, 'new'), (7, 'new'), (8, 'legacy'), (9, 'new'), (10, 'legacy')] routes by name: create_order -> new get_order -> new cancel_order -> new list_orders -> legacy refund_order -> legacy export_orders -> legacy
Change NEW_SHARE to 80 and run it again. The split moves to 80 new and 20 legacy. That is the migration, one number at a time. Now change one route in the table, move refund_order to new, and run it again. The table is the switch. The code never changes.
Save this file as claim_check.py. It stores a 480,000 byte receipt, sends a ticket down the queue, and the worker fetches the receipt by ticket and deletes the ticket when it is done. Run it and check the two sizes.
"""Claim Check for Lesson 189.
The receipt is 480 KB. The queue message carries a ticket, not the
receipt. The worker fetches the receipt from the store by ticket,
then deletes the ticket so a redelivery cannot charge twice.
"""
import hashlib
STORE = {}
QUEUE = []
def store_receipt(order_id, receipt_text):
ticket = "ticket-" + hashlib.sha256(receipt_text.encode()).hexdigest()[:12]
STORE[ticket] = {"order_id": order_id, "receipt": receipt_text}
return ticket
def send_to_queue(ticket):
message = {"order_id": STORE[ticket]["order_id"], "ticket": ticket}
QUEUE.append(message)
return message
def process_next():
message = QUEUE.pop(0)
receipt = STORE.pop(message["ticket"])
return message, receipt
def main():
receipt = ("RECEIPT" * 68572)[:480000] # exactly 480,000 bytes
print("receipt bytes:", len(receipt.encode()))
ticket = store_receipt("order-1042", receipt)
message = send_to_queue(ticket)
print("queue message:", message)
print("queue message bytes:", len(str(message).encode()))
done, fetched = process_next()
print("worker fetched order:", fetched["order_id"])
print("receipt bytes fetched:", len(fetched["receipt"].encode()))
print("tickets left in store:", len(STORE))
print("messages left in queue:", len(QUEUE))
if __name__ == "__main__":
main()
Output, exactly as it ran:
receipt bytes: 480000
queue message: {'order_id': 'order-1042', 'ticket': 'ticket-c9c93cfd5bb9'}
queue message bytes: 59
worker fetched order: order-1042
receipt bytes fetched: 480000
tickets left in store: 0
messages left in queue: 0
The queue message is 59 bytes. The receipt is 480,000 bytes. The queue never saw the receipt. Now break it on purpose: comment out the line that deletes the ticket in process_next, run it twice, and watch the store keep a ticket. That is the leak the "When it breaks, I check" box warns about, and you just made it happen on your own machine.
Three questions. No score is saved anywhere. This is just you against the material.
Using cloud design patterns is not one skill. It is four levels of the same job, and every team I have worked with sits on one of them. The levels are not about how many pattern names you can recite. They are about whether the pattern changes what breaks at 2 AM. Read them in order. Each level fixes the failure that hurt the most at the level below it.
At the basic level, you pick one pattern and use it on one route. The strangler fig is the best first pick, because it moves traffic without a rewrite. You write the route table, you move create order to the new service, and you watch it for a week. The failure that ends this level is the second route. One moved route feels like a migration. It is not. It is a start.
Do this: run step 0 of the lab. Change NEW_SHARE to 80 and run it again. Write down the split. Then move one route in the table and run it a third time.
At the intermediate level, the split is real. CQRS separates the command side from the query side, the materialized view answers the confirmation screen, and the claim check keeps big payloads out of the queue. You design the screen for the lag, not against it. The screen says processing while the events are in flight, and it never shows a success the events have not confirmed. The failure that ends this level is the first stale read a customer reports. You learn the lag is a design input, not a bug report.
Do this: run step 1 of the lab. Write down the two sizes: 480,000 bytes in the store, 59 bytes in the queue. Then break it on purpose by leaving the ticket in the store, and watch the leak.
At the advanced level, the system runs in more than one place. Deployment stamps give each region its own copy and its own store. Geodes put the stamp close to the customer, so the write travels a short road. The priority queue gives paid orders the fast lane, and the valet key lets the client upload straight to storage. The ambassador carries the retry schedule, and the schedule has a cap. The failure that ends this level is the first cross-stamp order, an order that lands in the wrong stamp and shows up as a slow write.
Do this: draw your own system as stamps. Name the home stamp for each customer. Then write the retry schedule from Go deeper on one page, with the cap circled.
At the master level, you stop adding patterns and start removing failure. Every pattern gets a budget: the retry budget, the queue depth, the view lag, the ticket count. Each budget has an alert, and each alert has an owner. You can say what breaks at ten times the checkouts, in numbers, before it breaks. The strangler share, the write hop, and the read lag are the three numbers you watch. When a pattern costs more than it saves, you take it out, and the route table is how you take it out safely.
Do this: set the simulator to 80 checkouts, 20% new, 0% priority, 400 KB. Write down the 174 ms total. Then move the strangler slider to 90% and write down the new total. That difference is the migration, priced in milliseconds.
A deployment stamp is one full copy of the system in one region: its own app, its own queue, its own store. A geode is a stamp placed close to a group of customers. The order in this lesson lands in the home stamp, because the customer lives near it. The write travels a short road. The read travels a shorter one. The hard part is not the stamp. The hard part is the order that belongs to two stamps. You pick one home stamp per customer and you write it down. An order with two homes is an order with no owner, and it will show up as a slow write in the wrong region.
At 10x: one stamp per region becomes three stamps per region, and the stamp count is the scaling unit. You do not scale the stamp. You add stamps. At 100x: stamps get their own deploy pipelines, and a bad deploy takes down one stamp, not the whole system. The stamp is the blast radius, and that is the point.
Gateway offloading moves the edge work to the gateway: authentication, rate limiting, TLS, and request validation. The app behind it stops checking tokens and starts trusting the headers the gateway sets. That is the trade. The app gets simpler and faster. The gateway becomes the one place a token bug can lock everyone out. I offload the checks that are the same for every service, and I keep the checks that are specific to one service in that service. Auth at the edge, authorization in the service. That line is the whole pattern.
Product images, style sheets, and the receipt PDF are static files. They live in object storage, behind a CDN, and the app serves a link, not the bytes. The app never reads a file from disk to answer a request. The win is not speed, though the CDN is faster. The win is that a traffic spike on images cannot take down checkout. Static hosting separates the traffic that scales cheaply from the traffic that needs the app.
A queue with one lane treats a paid order and a nightly export the same. The priority queue gives paid orders the fast lane and lets the export wait. The rule is written down, not guessed: paid orders first, then everything else. The risk is starvation. A lane that never drains is a lane that is not a lane. I watch the low priority depth with an alert, and I drain it on a schedule, even at peak. A queue that starves is a queue that lies about being fair.
Event sourcing is taught in full in Lesson 28, so here is the recap, not the reteach. Every state change is an event in the log, the log is the system of record, and the databases are copies built from it. That gives you replay: fix the projection, re-read the log, rebuild the copy. It also gives you a bill, because the log grows by the event rate times retention. In this lesson, the CQRS write hop stores the event, and the materialized view is the copy rebuilt from it. If you want the replay exercise, with the runnable replay check, it lives in Lesson 28.
The ambassador retries on a schedule, and the schedule is code, not a hope. Three retries, waits that double, and a cap. Save this file as retry_schedule.py and run it.
"""Ambassador retry schedule for Lesson 189 (Go deeper).
Three tries, then stop. The wait doubles each time, and it is capped,
so a slow downstream service never gets a retry every 100 ms forever.
No jitter is added here, so the schedule is exact and checkable.
The lesson's point stands with jitter too: the cap is what saves you.
"""
BASE_WAIT_MS = 100
MAX_WAIT_MS = 400
MAX_TRIES = 3
def schedule():
waits = []
wait = BASE_WAIT_MS
for _ in range(MAX_TRIES):
waits.append(wait)
wait = min(wait * 2, MAX_WAIT_MS)
return waits
def main():
waits = schedule()
print("tries:", MAX_TRIES + 1, "(first try plus", MAX_TRIES, "retries)")
print("waits between tries (ms):", waits)
print("worst extra wait (ms):", sum(waits))
print("cap (ms):", MAX_WAIT_MS)
if __name__ == "__main__":
main()
Output, exactly as it ran:
tries: 4 (first try plus 3 retries) waits between tries (ms): [100, 200, 400] worst extra wait (ms): 700 cap (ms): 400
Four tries, 700 ms of worst extra wait, and the cap is 400 ms. Now compare that with no cap: waits of 100, 200, 400, 800, 1600, and the total runs away. The cap is the difference between a slow minute and a storm. Put the cap in the ambassador config, not in a runbook, because the config runs at 2 AM and the runbook does not.
Every pattern in this lesson has a way to go wrong, and the wrong way has a name. This section teaches six of them. Three already appear in this course in other framings. Retry Storm is covered in the retries lesson, and Noisy Neighbor and Chatty I/O appear in the Kubernetes and virtualization lessons. The other three have no treatment anywhere in the course until now. Learn the name, learn the fix, and learn the signal that tells you which one you are looking at.
Retry Storm. A slow downstream service gets retried by every caller at once, so one slow minute becomes four times the traffic. The signal is the ambassador retry count climbing while the downstream latency is flat. The fix is a retry budget and a cap, plus a circuit breaker that stops calling a service that is already down. This lesson's storm scenario is a retry storm, drawn hop by hop.
Noisy Neighbor. One tenant or one workload eats the shared CPU, memory, or disk, and every neighbor on the same box slows down. The signal is latency rising on services that changed nothing. The fix is limits and isolation: quotas per tenant, CPU and memory limits per service, and separate pools for the loud workloads. In the cloud the fix is also placement: the loud tenant gets its own stamp.
Chatty I/O. A request that needs one answer makes twenty small calls instead. The signal is a hop count that grows with the payload: more items, more calls, same work. The fix is batching: one call that takes a list, or one read model that already has the answer. The materialized view in this lesson is the fix, built as a pattern.
Cache Stampede. A popular cache entry expires, and a thousand requests all miss at once and all hit the database. The signal is a database spike at the exact second a key expires. The fix is a lock or a stagger: one request rebuilds the entry while the rest wait, or the entry refreshes before it expires. Never let expiry be a starting gun.
Hot Partition. One partition key takes most of the traffic, so one shard burns while the rest idle. The signal is one node at 100% CPU and nine nodes at 10%. The fix is a better key: split the hot key, add a suffix, or route the hot tenant to its own partition. A partition that cannot split is a partition that will burn.
Unbounded Queue Growth. The queue accepts work faster than the workers drain it, and the depth grows without a limit. The signal is queue depth climbing for an hour while the workers look healthy. The fix is a bound and a shed: a max depth, a dead letter queue for the overflow, and load shedding that says no early instead of failing late. A queue with no bound is a memory leak with a nicer name.
The pattern to remember: an antipattern is a good pattern with no budget. The retry has no cap. The cache has no stagger. The queue has no bound. The partition has no split. Put the budget in before the traffic arrives, because the traffic will not wait for the review.
A sale morning. Traffic tripled in an hour. The write side slowed down for one minute, from 42 ms to just over 200 ms. The ambassador did what it was told to do: it retried. Every slow call got three more tries. One checkout became four writes. The queue backed up behind the retries, and the write hop hit 180 ms and stayed there. The confirmation screen showed processing for orders that had already been charged. No data was lost. The idempotency key caught the duplicate writes. The customers saw a spinner, and the support queue filled up.
Three changes, all in config, none in a runbook. First, a retry budget: three tries, waits of 100, 200, and 400 ms, and a cap, in the ambassador config on every service. Second, a circuit breaker on the write path, so a slow downstream stops getting calls instead of getting four times the calls. Third, an alert on the ambassador retry count, owned by the on-call rotation, so the next storm gets named in one minute instead of sixteen. The idempotency key was already there, and it is the reason no customer was charged twice. The key is the hero of this incident, and it was written months before anyone needed it.
Design the checkout migration. A monolith takes all orders today: 100 checkouts a minute at peak, a 480 KB receipt per order, a phone app and a web page, and a confirmation screen that reads from the orders table. The team wants the new service to take new orders first, then refunds, then exports. The budget is 150 ms per checkout. Draw the nine hops from this lesson, name the pattern at each hop, and say what moves first.
Start with the strangler. Move create order first, behind a flag, at 60% of traffic. That is the simulator default, and the budget at 20 concurrent checkouts is 112 ms, inside the 150 ms budget. Refunds and exports stay on the monolith. The route table is the switch, and the flag is how you roll back.
Then split the read from the write. CQRS takes the write, the materialized view answers the confirmation screen, and the screen says processing while the events are in flight. The view lag is the number to agree with the team before you ship it, not after a customer reports it. Two seconds of lag is a design choice. A spinner with no explanation is a bug.
Then shrink the queue. The receipt goes to the store, the queue carries a 59 byte ticket, and the worker deletes the ticket when it is done. The phone gets its own BFF with a small payload, the web page gets the full order, and the receipt PDF goes to static hosting behind a CDN. The upload itself takes a valet key, so the app never touches the bytes.
Then cap the retries. Three tries, waits of 100, 200, and 400 ms, and a circuit breaker on the write path. At 80 concurrent checkouts with only 20% of traffic on the new service, the budget is 174 ms, over the 150 ms limit. Cut the concurrent checkouts to 40 with a queue limit and move the strangler share to 90%, and the budget is 139.5 ms, inside the limit. That is the migration, priced in milliseconds, and it is the argument for moving the next route.
Trade-offs to name. CQRS buys a fast read with lag, and the lag is the price. The claim check buys a small queue with a store to manage, and the ticket leak is the price. The stamp buys a short road with a home region to own, and the cross-stamp order is the price. The priority queue buys a fast lane for paid orders with starvation for the export lane, and the drain schedule is the price. Name each price before you ship, and the review writes itself.
Saved in this browser, so the Lessons index can show your progress across the course.