Coupling is the enemy.
Everything else is tactics.

Every architectural move in this stage — splitting a monolith, drawing a service boundary, replacing a function call with an event, putting a gateway at the edge — is the same move: reduce the number of things that must change together, deploy together, or be up at the same instant. That is all coupling is. The rest is vocabulary.

Architectures are usually argued about on one axis — "monolith or microservices?" — and that framing is what produces the disaster. There are two independent axes, and the interesting information is in which quadrant you land.

Where coupling hides at each stage

Decision tree — which session should you act on first?

The sessions are ordered for teaching, but a real system usually has one problem that dominates. If you are here to fix something rather than to study in order, start where the pain is.

What you'll be able to do at the end

• Decide monolith vs microservices for a specific system, with a defensible reason that isn't "Netflix does it".
• Draw service boundaries around business capabilities rather than database tables, and say why a given boundary is too big or too small.
• Design an event-driven flow and judge honestly when async is worth its complexity.
• Recognise a distributed monolith in an architecture diagram in under a minute.
• Pick queue vs topic vs event bus on any of the three clouds, and know the ordering and delivery guarantee you just signed up for.
• Place a gateway, a BFF, and a CDN correctly — and know when each is the wrong answer.
• Critique your own FastAPI gateway and inference router against all of the above.

Field notes — what changed recently

Four things differ from the plan as given:

A team of forty ships once every three weeks. Every release is a negotiation: the payments change has to wait for the search re-index, which is blocked on a schema migration owned by a third team. Nobody wrote a bad line of code. The problem is that everything is in one deployable unit, so everything moves at the speed of the slowest thing in it.

Microservices are the response — but the response is organisational before it is technical. The point is not smaller programs. The point is that a team can decide, build, test, and release without asking anyone's permission. Every technical property people quote — independent scaling, polyglot stacks, failure isolation — is downstream of that.

Which means the decisive question of this session isn't "how do I split this?" It's "where do the seams go so that most changes land inside exactly one of them?" Get that wrong and you have built the distributed monolith: forty people who now need more coordination than before, plus a network between them.

Cohesion and coupling, in one kitchen

Picture a restaurant kitchen. Cohesion is how much the things at one station belong together: the grill station has the grill, the tongs, the meat, and the person who knows how meat behaves. High cohesion means everything you need for one job is within arm's reach.

Coupling is how much one station has to interrupt another to get its job done. If the grill cook has to shout across the room every thirty seconds to ask the pastry station what temperature to use, those two stations are coupled — and neither can be replaced, retrained, or moved without disrupting the other.

A monolith is one enormous station where everybody works on the same bench. A good microservices architecture is a set of stations where each one can be re-staffed mid-service without the others noticing. A distributed monolith is what you get when you put the stations in separate buildings but keep the shouting.

Cohesion

How strongly the things inside one boundary belong together. High is good. If a service handles "pricing rules" and "PDF generation", it has low cohesion — two unrelated reasons to change live in one unit.

Coupling

How much a change on one side of a boundary forces a change on the other. Low is good. Two services are coupled if you cannot deploy a change to one without also releasing the other.

Monolith

An application built, deployed, and scaled as a single unit. Calls between modules are in-process function calls. It fails as a unit and it scales as a unit.

Microservice

An independently deployable service, owned by one small team, organised around a business capability, with its own datastore, reached through a defined API. Sam Newman's definition reduces to the first three words: independently deployable service.

Distributed monolith

Services that are separately deployed but not separately deployable — because of shared databases, lock-step release trains, or synchronous call chains. The failure mode this whole stage exists to prevent.

The three architectures, drawn so the difference is visible

These diagrams get drawn wrong constantly: microservices and distributed monoliths look identical in most slide decks, because both are "boxes with arrows". The difference is not the number of boxes. It is where the data lives and what has to ship together.

The design sequence: from conversation to service boundary

the patterns catalog's source is unusual in that it does not start from technology at all. It starts from a room full of people with sticky notes, and it insists that if you skip that step you will derive your services from your existing database schema and call them microservices.

What an aggregate looks like on paper

Short enough to be the mechanism itself rather than a console step — this is a consistency boundary written as a data shape:

# AGGREGATE ROOT: Order — one transaction, one owner, one service
Order
  id, customer_ref        # a REFERENCE, not an embedded Customer object
  status, placed_at
  LineItem[]              # inside the boundary: no life of its own
    sku_ref, qty, price_at_time_of_order
  invariant: sum(line_items.qty) > 0 and status transitions are legal

Two details carry the whole design. customer_ref is an identifier, not an embedded object — the Customer lives in another context and you refuse to hold a copy of its model. And price_at_time_of_order is a snapshot, not a lookup — because the Catalogue context is free to reprice tomorrow and your order must not silently change.

How big should a service be? Bounds, not vibes

"Two-pizza team" and "small enough to rewrite in two weeks" are folklore. the patterns catalog's source gives an actual pair of bounds, and they are the most useful thing in the section:

IDEALS — the design principles behind those bounds

The material's mnemonic for microservice design, the service-level counterpart to SOLID. Two of the six are the entire argument of this stage:

API design and versioning: where coupling survives the split

You can draw perfect boundaries and still re-couple everything through the contract. Three rules that carry most of the weight:

Decision tree — monolith or microservices for this system?

Worked example — the same domain, split two ways

An online bookstore. Six nouns: users, orders, items, payments, inventory, shipments. Watch what happens when you decompose by table versus by business capability, and count the network hops needed to place one three-line order.

What happened when real teams did this

Critiquing your FastAPI gateway and intelligent router against the patterns

You have already built one of the things this section describes, before reading the section. Here is what the patterns say about it — the good and the exposed.

The bounded contexts hiding in your fintech document pipeline

Ingest → analyse → score reads like three services because it is three steps. Steps are not boundaries. Apply the two bounds from Pass 3:

• Ingest owns a genuine aggregate: the Document, with its pages, source metadata, and upload lifecycle. Different vocabulary ("page", "OCR confidence", "source system"), different failure modes, different scaling profile — it is I/O and storage bound. A real bounded context.
• Analyse and score are far more suspect as separate services. If scoring always immediately follows analysis on the same document, passes large extracted structures between the two, and neither is independently useful, that boundary buys nothing and costs a serialisation hop. The upper-bound litmus test: if Analyse goes down, does more than one business capability fail? If the answer is "no, only scoring, which is meaningless without it", they are one context.
• The strongest boundary in that pipeline is probably not between the steps at all. It is between the synchronous request path and the long-running work — which is an S2 question, not an S1 one.

S1 ended on a number: nine synchronous hops at 99.9% each gives you six and a half hours of downtime a month. Drawing better boundaries got that to two hops. But two is not zero, and every remaining hop still carries the same hidden requirement — the callee must be up, right now, at the exact moment the caller needs it.

A service API decouples what from how: swap the implementation, the caller never knows. What it does not decouple is when and where. The caller must locate the provider. The caller waits while the provider works. If the provider fails, the caller must handle it or fail too. That is coupling in time and space, and no amount of interface design removes it.

The material's motivating example is employee onboarding. A new hire triggers an email account, a payroll entry, a welcome package, a badge, an equipment order — and HR policy keeps adding to that list. Written synchronously, some onboarding service must know every downstream system, call each one, and be updated every time the list changes. It is coupled to all of them and it cannot run unless they are all available.

The alternative is to stop calling and start announcing: publish EmployeeHired and let whoever cares react. The onboarding service no longer knows who is listening. New listeners appear without it changing. That inversion — from invocation to notification — is the whole session.

Phone call, voicemail, noticeboard

That third column is the definition of an event-driven architecture, and it explains the one rule people get wrong: an event is not an instruction. "Employee hired" is an event. "Create an email account" is a command. If your "events" are secretly commands — if the publisher knows and expects what the subscriber will do — you have built a synchronous system with extra latency and no stack trace.

Synchronous

The caller blocks until the callee responds. Both must be available simultaneously. One logical transaction, one thread held open.

Asynchronous

The sender hands off and continues immediately. Sender and receiver need never be up at the same instant. Separate transactions on each side.

Pseudosynchronous (the trap)

Putting a request on a queue and then blocking while waiting for the reply. You have taken on all the complexity of messaging — correlation IDs, two transactions, crash recovery — and kept the blocking. The material names it specifically as a thing to avoid. If your "async" code awaits a response before returning, check which one you built.

Queue

Point-to-point. A message goes to exactly one consumer, and is removed once acknowledged. N consumers on a queue means work is shared among them. This is a load distributor.

Topic

Publish-subscribe. A published message is copied to every subscription. N subscribers means N independent copies. This is a broadcast.

Event

An immutable statement that something happened, in the past tense, with no expectation of a particular reaction. Carries what changed, not what to do about it.

Command

A request that something specific should happen, addressed to a known handler. Legitimate — but it belongs on a queue, not a topic, and it re-introduces identity coupling.

Event backbone

The shared infrastructure carrying all topics, so emitters and listeners connect to it rather than to each other. Kafka, EventBridge, Pub/Sub, Service Bus, Event Grid all play this role. The material is candid that it is a logical single point of failure.

Idempotency

The property that processing the same message twice produces the same result as processing it once. Non-negotiable in practice, for reasons in Pass 3.

Dead-letter queue (DLQ)

A side queue where messages go after N failed delivery or processing attempts, so one bad message cannot block the queue forever or be silently discarded.

The same business flow, twice

Step through an order being placed as a synchronous chain, then as events. Same domain, same work performed — different failure behaviour, different latency, different blast radius.

Queue versus topic — the diagram that settles most arguments

What an event actually looks like on the wire

The schema is the mechanism here — this is the contract that stays coupled after everything else has been decoupled, so it earns its place in Pass 2:

{
  "specversion": "1.0",               // CloudEvents — a portable envelope
  "type": "com.acme.order.placed.v1",  // past tense + VERSION in the type
  "source": "/ordering",               // who emitted, not who should react
  "id": "01JH9Q...ULID",               // the dedup key consumers store
  "time": "2026-07-28T14:02:11Z",
  "data": { "orderId": "A-4471", "total": 4299, "currency": "USD" }
}

Three deliberate choices. The version lives in the type, so v1 and v2 can coexist on one topic and consumers filter. The id is what makes idempotency possible at all. And data carries a thin payload — enough to act on, not the whole aggregate, because every field you publish becomes a field you can never remove.

The idempotency check, in five lines

def handle(event):
    if seen.add_if_absent(event["id"], ttl=7*86400) is False:
        return ACK          # duplicate — already done, ack and move on
    do_the_work(event["data"])   # must be safe if we crash right here
    return ACK

The subtlety is the crash between line 4 and line 5: the ID is recorded, the work is done, the ack is lost. On redelivery you correctly skip. But if you crash between recording the ID and doing the work, you skip work that never happened. The robust version makes the dedup record and the business write part of the same local transaction — which is possible precisely because each service owns its own database.

Delivery guarantees: pick two lies you can live with

Ordering is more expensive than it looks

Global ordering across a topic and parallel consumption are fundamentally in tension: if any message may need to be processed before any other, you can only have one consumer. Every broker resolves this the same way — partial ordering within a key. Messages sharing an ordering key (a partition key, message group ID, ordering key) are strictly ordered relative to each other; messages with different keys are not, and can be processed in parallel.

Choosing that key is a real design decision. Key by orderId and every order's events are ordered while different orders run in parallel — usually correct. Key by customerId and you get ordering per customer but a single high-volume customer becomes a hot partition that no amount of scaling relieves. S3 shows what each cloud charges you for ordering, and the throughput ceilings are real.

Sagas — what replaces the transaction you just lost

A saga is a sequence of local transactions where each step publishes an event that triggers the next, and every step has a compensating action that semantically undoes it. There is no rollback, because there is no shared transaction to roll back. There is only "do the opposite, afterwards, and hope that is meaningful."

Event sourcing and CQRS, at intuition level

Dead-letter queues, and the trap inside them

A message fails. The broker retries. It fails again. Without a DLQ you get one of two disasters: on an ordered queue, the poison message blocks everything behind it forever; on an unordered one, it is retried until the retention window silently drops it. A DLQ moves the message aside after N attempts so the flow continues and the failure is preserved.

Decision tree — synchronous call or asynchronous event for this interaction?

Worked example 1 — availability, four services, both ways

Worked example 2 — count the failure modes a 4-step saga must handle

Order → reserve inventory → charge card → allocate shipping → notify. In a monolith this is one BEGIN … COMMIT. Distributed, here is the actual surface area:

Grounding — where this shows up in practice

Your fintech pipeline is already asking to be event-driven

Ingest → analyse → score, run synchronously, has all four properties from the decision tree pointing the same way. Reframed as events:

• DocumentIngested — the ingest context's aggregate reached a terminal state. Payload is a document ID and a storage reference, not the document. This is the claim-check pattern, and it is mandatory at these payload sizes for reasons S3 quantifies.
• Analysis subscribes, does the expensive extraction, emits DocumentAnalysed.
• Scoring subscribes to that. So — later and for free — does an audit-log consumer, a metrics consumer, and whatever compliance asks for next quarter, none of which requires touching ingest.
• The user-facing API returns 202 plus a document ID within milliseconds, and a status endpoint reports the state. Your slowest stage no longer determines your API's timeout.

The honest counter-argument, which you should weigh: if this pipeline runs at low volume, has exactly one consumer per stage, and nobody is waiting on it, the synchronous version is simpler and the decision tree's default box applies. The trigger to convert is a real one — a stage that takes longer than a request should, or a second consumer appearing.

Batch and long-running inference: the poster child

S2 gave you three primitives — queue, topic, event bus — and the rules for choosing between them. Those rules are portable. What is not portable is the fact that each cloud gives you three to five products that all look like "messaging", with overlapping capabilities, different delivery guarantees, and size limits that differ by two orders of magnitude.

The failure mode here is not picking the "wrong" product. It is picking one without noticing which guarantee you just signed up for. A team that assumes ordering because the product is called a queue, or assumes exactly-once because the console has a checkbox labelled that, has built a correctness bug that will surface only under load, only in production, and only intermittently.

Three shapes, and a fourth that pretends to be one of them

Strip the branding away and there are only a few things a messaging product can be. Learning to classify a service in ten seconds is worth more than memorising any feature matrix.

How a message actually moves, and where it can be lost

Every managed broker runs the same six-beat cycle. Knowing it tells you exactly which config value causes which production incident.

One message, three clouds — the same flow in each vocabulary

Before the comparison table, walk a single concrete case through all three. Scenario: an inference job is submitted, one worker must process it exactly once in effect, and a poison message must not block the queue.

The three-cloud comparison — queues, topics, and event buses

Every service named with a one-line statement of what it is and which layer it sits in. Verified against current vendor documentation in July 2026.

The four settings that cause almost every incident

Decision tree — queue, topic, event bus, or log for this message?

Worked example — size a queue for an inference traffic spike

A model endpoint runs at a steady 50 req/s. A product launch drives it to 800 req/s for five minutes. You have 20 GPU replicas, each sustaining 12 req/s with continuous batching. Nothing can be dropped. Size the queue.

Grounding — three current sources that change the answer

Async patterns for long-running and batch inference in your stack

Three shapes, in increasing order of how much they change your architecture. All three assume the claim-check rule: references in messages, payloads in object storage.

Which product, given your preferences

You want open-source-first, equal AWS and GCP fluency, working Azure literacy. On GCP, use Pub/Sub — one product covers queue and topic shapes, the 10 MB ceiling means you rarely fight the limit for prompts, and it is global so there is no regional topology to design. On AWS, use SQS alone for a job queue, and add SNS in front only when a second consumer appears; skip EventBridge until routing rules actually change. On Azure, Service Bus — despite the material barely covering it — because sessions and scheduled delivery are genuinely useful for tenant-ordered inference and delayed retries. If you want the portable answer: RabbitMQ or NATS on Kubernetes speaks AMQP everywhere and keeps your consumer code identical across clouds, at the cost of operating it yourself. That is a real trade, not an obvious win.

# Billing → Budgets & alerts → Create budget. Do this BEFORE creating resources.
gcloud billing budgets create \
  --billing-account=$BILLING_ACCOUNT \
  --display-name="s3-messaging-lab" \
  --budget-amount=5USD \
  --threshold-rule=percent=0.5 --threshold-rule=percent=0.9

S1 through S3 decomposed the inside of the system. Now look at it from outside. A client — a browser, a mobile app, a partner's integration, your own CLI — needs to use this thing. What it sees is a constellation of services with changing addresses, changing APIs, and no single place to knock.

When the server was a monolith this was trivial: one process, one endpoint, one address that never moved. A microservices application is dynamic by construction — replicas come and go on ephemeral addresses, services get split and merged, APIs evolve. The material puts the problem precisely: how does a client get easy, stable access to a set of services that is deliberately unstable?

And there is a second, harder asymmetry. Deploying a new service version is routine. Updating every mobile app already installed on a phone is not. If your service APIs are your public contract, then every internal refactor becomes a forced migration for people you cannot reach. The edge layer exists to absorb that.

The hotel, the concierge, and the neighbourhood branch

Three edge components, three jobs, and they are routinely confused because all three sit "in front of" your services.

API gateway

A managed service at the edge of your architecture that terminates client connections and routes them to backend services, handling cross-cutting concerns — authentication, rate limiting, request/response transformation, logging, API keys — so each service doesn't re-implement them. It sits outside your services and inside your perimeter.

Backend for frontend (BFF) · the material's Dispatcher

A thin server-side component built for one client type, exposing exactly the API that client needs and implementing it by calling several microservices. One BFF per client type — web, mobile, partner, CLI. Built and deployed by the same team that owns the client. Contains no domain logic.

Public API

§8's separate pattern: a deliberately coarser, more stable API for third parties outside your organisation. Distinct from a BFF because it must change far more slowly — you cannot coordinate a release with strangers.

CDN · content delivery network

A globally distributed cache of edge locations (points of presence, "PoPs") that serve copies of your content from near the user. Sits in front of everything, including the gateway.

Origin

The materialitative source the CDN pulls from on a cache miss — your bucket, load balancer, or gateway.

Cache key

What the CDN uses to decide whether two requests are "the same object". Usually the URL path, plus whichever query parameters, headers, and cookies you tell it to include. The single most consequential CDN setting there is.

Cache invalidation

Making the cached copy stop being served before its TTL expires. Two mechanisms: purge (tell the CDN to drop it) and versioned URLs (change the key so nobody asks for the old one).

Rate limiting

Capping how many requests a client may make in a window, to protect capacity and enforce fairness. Usually implemented as a token bucket: a refill rate plus a burst capacity.

Edge compute

Small programs running at the PoP itself — header rewrites, redirects, auth checks, A/B routing — executing before a request ever travels to a region.

The layers, in order, and what each one is allowed to do

The client side of §8 — what sits on the far side of the edge

§8's actual subject is the clients themselves, and the choice of client shape changes what the edge has to provide. Four patterns worth knowing, and the one architectural principle underneath all of them.

A cache hit and a cache miss, step by step

The three-cloud comparison — gateways and edge

Verified against current vendor documentation in July 2026. Retirement dates are called out because two of them fall inside a normal system's lifetime.

Cache invalidation, and why it is the hard one

The joke about it being one of the two hard problems in computer science is not about the mechanism — purging is an API call. It is that you must decide, in advance, how wrong you are willing for the world to be, and for how long. A TTL is a promise about staleness. Ninety seconds of stale pricing might be fine; ninety seconds of stale account balance is not.

The design move that dissolves most of the problem is to stop invalidating: make the URL contain a content hash so that a change produces a new key and the old object simply stops being requested. Anything you cannot version — an entry-point HTML file, a stable API path — gets a short TTL and a purge on deploy. And two cheap directives buy a lot: stale-while-revalidate hides refresh latency, stale-if-error keeps you serving through an origin outage.

Rate limiting: which algorithm, and where

API versioning through the gateway — the Public API problem

§8 makes a distinction worth holding onto. A BFF's API can evolve fast, because the same team owns the client and can ship both together. A Public API must evolve slowly, because its consumers are strangers who will not move on your schedule. The material reports teams supporting up to six concurrent versions because third parties could not keep up.

The gateway is where you make that survivable. Route /v1/* and /v2/* to different backend versions and the split is infrastructure config, not application code — so old and new can run side by side, traffic can shift gradually, and a bad v2 can be rolled back by changing a route rather than redeploying. It also gives you the data to end the migration: per-version request metrics tell you which consumers are still on v1 and whether the sunset date is realistic. Announce the sunset when you launch the new version, not when you are tired of the old one.

Decision tree — direct, gateway, or BFF for this client?

Worked example 1 — what seven points of hit ratio actually cost

Worked example 2 — rate limits that add up to more than you have

Your inference backend sustains 240 req/s (the 20 replicas from S3). You have 20 tenants and want to be generous. Watch the arithmetic fail.

Grounding — three current sources

Exposing and versioning your model endpoint through a gateway

The concrete shape for your FastAPI gateway

S1 flagged four exposures in what you have built. Here is what the edge patterns say to do about each, in the order I would do them:

1. Version the path first. Move to /v1/generate today, even with one consumer. This is a fifteen-minute change now and a coordinated multi-team migration later. Route /v1/* at the gateway so v2 can run beside it.
2. Split the two lanes at the route, not in the handler. From S3's Shape B: /v1/generate stays synchronous with a short timeout; /v1/batches returns 202 and publishes to Pub/Sub. Different timeouts, different rate limits, different scaling — same GPU pool underneath. Doing this at the route level is what lets the two evolve independently.
3. Move auth and rate limiting out of FastAPI. These are the reference text cross-cutting concerns a gateway exists for. Keeping them in application code means every future service re-implements them, inconsistently.
4. Add the global concurrency cap from worked example 2, alongside per-tenant limits. Per-tenant alone does not protect the fleet.
5. Decide whether your router is a BFF or a gateway — and don't let it be both. This is the important one. Right now your intelligent router does two different jobs: edge concerns (accepting, authenticating, limiting) and domain-ish concerns (choosing which model should serve this request). The §4 rule says a Dispatcher holds no domain logic. Model selection based on prompt complexity, cost tier, or context length is domain logic — it is your product's routing policy. Put the gateway concerns in a real gateway and keep the router as a service behind it, with its policy testable in isolation. The vLLM Semantic Router project treats routing as its own component for exactly this reason.
6. Only then consider a BFF — and only if a second client type appears with genuinely different needs. A notebook client wanting streamed tokens and a batch client wanting job handles is a real second type. One client does not justify one.

Which stack, given your preferences

Open-source-first and portable: Envoy Gateway or Kong on GKE, configured through the Kubernetes Gateway API, keeps your edge config portable across all three clouds and runs the same locally. This is also the direction the LLM serving ecosystem has gone — llm-d and the inference-gateway projects build on Gateway API HTTPRoute, so a route-level split between interactive and batch is idiomatic rather than bespoke. Managed alternative on GCP: API Gateway in front of Cloud Run or GKE, escalating to Apigee only if you ever expose the endpoint to external customers. Put Cloud CDN or CloudFront in front for TLS and DDoS, not for caching.

# Gateways and CDN profiles charge for EXISTING, not just for serving.
# APIM Developer tier is roughly $48/month whether you use it or not.
gcloud billing budgets create \
  --billing-account=$BILLING_ACCOUNT \
  --display-name="s4-edge-lab" \
  --budget-amount=5USD \
  --threshold-rule=percent=0.5 --threshold-rule=percent=0.9