QuickCart Stage 8: Splitting the Monolith Into Services

// infrastructure: an adapter (the vendor-facing names are Pseudocode)
public class ProviderPaymentGateway implements PaymentGateway {
    private final ProviderClient client;
    public ProviderPaymentGateway(ProviderClient client) { this.client = client; }

    public AuthorizationResult authorize(AuthorizationRequest r) {
        try {
            ProviderResponse resp = client.charge(r.idempotencyKey(), r.amountMinorUnits(),
                                                  r.currency(), r.paymentMethodToken());
            return resp.approved()
                ? new AuthorizationResult.Approved(resp.id())
                : new AuthorizationResult.Declined(resp.code());
        } catch (ProviderTimeoutException e) {
            return new AuthorizationResult.Unavailable("provider timeout");
        }
    }
}

Two details matter. A timeout becomes the explicit Unavailable result, so the use case must decide what to do, and the idempotency key travels through the port so the provider can recognise a retry (stage 6). A test passes a fake PaymentGateway that returns a canned result and needs no network.

Figure 4. Ports and adapters inside the Payments service.

How to read this: arrows show runtime calls. Source-code dependencies point the other way for the outbound side: the adapters import the port the core defines, never the reverse.

The front door and the network between services

API gateway

An API gateway is the single entrance for outside callers (north-south traffic). It routes /v1/catalogue/... to Catalogue and /v1/orders/... to Orders, terminates TLS, verifies the caller's token once and passes a verified identity inward, applies rate limits and can aggregate several backend calls into one response for a mobile screen. The gateway lesson covers the mechanics (API gateway and service mesh); here are QuickCart's decisions.

• Authentication offload, not authorisation. The gateway proves who the caller is. Each service still decides what that caller may do. The gateway must strip any identity header an outside client sends, or a client can forge one.
• Aggregation only for read screens. The home screen combines Catalogue highlights and the shopper's active order into one response. Checkout is never aggregated.
• A coarse limit at the edge. Per-IP and per-shopper limits live here; finer per-store limits live in the services.

The risk is the smart gateway: discount rules, delivery-fee maths or order validation creeping in because "it already sees every request." Then every team edits one deployable, and its outage takes down everything. QuickCart's rule: if removing a feature would change a business outcome, it does not belong in the gateway.

Figure 5. One checkout through the gateway.

How to read this: only the price lookup is a synchronous service-to-service call, and it has a deadline. Everything after "pending" (stock, payment, courier) happens through the order pipeline of stage 5.

Service discovery

Instances start, stop and move, so a caller cannot hard-code addresses. Service discovery answers: which healthy instances serve Inventory right now? There are three styles. DNS-based discovery resolves a name to addresses. In client-side discovery the caller asks a registry and chooses an instance itself, which saves a hop but puts discovery logic in every client. In server-side discovery the caller talks to a stable proxy or load balancer, which consults the registry.

Kubernetes (stage 10 will run QuickCart on it) takes the server-side route. Per its documentation, a Service gives a set of pods a stable virtual IP, the cluster IP, and a DNS name of the form <service>.<namespace>.svc.cluster-domain, where the default cluster domain is cluster.local. A controller keeps EndpointSlices in step with the pods that match the Service's selector, and kube-proxy on each node configures rules that redirect traffic for the cluster IP to one of those endpoints.

apiVersion: v1
kind: Service
metadata:
  name: inventory
  namespace: shop
spec:
  selector:
    app: inventory
  ports:
    - port: 80
      targetPort: 8080

Callers in the shop namespace reach it as http://inventory, and from other namespaces as inventory.shop.svc.cluster.local (with the default domain). The documentation explains why Kubernetes does not rely on plain DNS round-robin: some DNS implementations ignore record TTLs, some applications cache a lookup forever, and very low TTLs would load the DNS servers. A headless Service (clusterIP: None) instead returns the set of pod addresses and leaves choosing to the client.

Discovery data is a cache and can be slightly stale. Callers therefore need timeouts and a retry to a different instance (stage 9).

Service mesh

A service mesh moves east-west networking concerns out of application code. A small proxy, the sidecar, runs beside every service instance and carries its traffic; a control plane pushes configuration and certificates to the proxies. A mesh typically gives mutual TLS (both sides present certificates), uniform retries and timeouts, traffic shifting (send 5 percent of requests to a new version) and per-call telemetry.

Istio's documentation describes the mechanism: each workload gets an X.509 identity tied to its Kubernetes service account, an agent beside each Envoy proxy requests and rotates certificates from istiod, and the PERMISSIVE mode accepts both plaintext and mTLS so a migration can move to STRICT gradually.

The costs are real: extra CPU and memory per pod, a control plane to upgrade and keep available, one more layer in every incident, and a retry policy that can multiply load if layered with application retries. For seven services and a small platform team, QuickCart defers the mesh. It relies on the gateway, TLS to each service and library-level timeouts, and revisits at stage 10 when security requirements and Kubernetes arrive together. See the gateway and mesh lesson.

Talking to each other

REST, gRPC, GraphQL and WebSockets

Each style fits a different conversation.

• REST over HTTP and JSON models resources and uses standard verbs and status codes. It is cacheable, tool-friendly and the default for public APIs.
• gRPC uses HTTP/2 and protocol buffers as its default interface definition language. It supports unary calls and three streaming kinds, and a client can set a deadline after which the call ends with DEADLINE_EXCEEDED. Browsers reach it through gRPC-Web and a proxy.
• GraphQL exposes a typed schema, and the client asks for exactly the fields it needs. It reduces round trips for varied screens but moves cost control to the server: unbounded queries need depth or cost limits, and HTTP caching is harder.
• WebSockets (RFC 6455) start as an HTTP request that upgrades to a long-lived two-way connection, so either side can send at any time. The price is per-connection state and more care in load balancers and deploys. Server-Sent Events are a simpler one-way option.

QuickCart does not adopt GraphQL at this stage. The one screen that would benefit, the home screen, is served by a small aggregation endpoint. The decision is revisited if several client teams start needing different shapes of the same data.

API design

Versioning. Put the major version in the path (/v1/) and treat additive changes (a new optional field) as non-breaking. Removing or renaming a field is breaking and needs /v2/ plus a deprecation window.

Pagination. Offset pagination (?offset=99980&limit=20) makes the database find and discard 99,980 rows before returning 20, and rows can shift between pages if data changes. Cursor (keyset) pagination remembers the last row seen and asks for rows after it. For a shopper's order history sorted newest first:

SELECT order_id, placed_at, total_minor
FROM orders
WHERE shopper_id = $1
  AND (placed_at, order_id) < ($2, $3)
ORDER BY placed_at DESC, order_id DESC
LIMIT 20;

With an index on (shopper_id, placed_at, order_id), PostgreSQL can walk to the cursor position instead of skipping rows. $2 and $3 come from an opaque cursor token returned with the previous page. Orders are sharded by shopper id (stage 4), so this query stays on one shard. The cost: no jumping to page 50 directly.

Idempotency. RFC 9110 defines PUT, DELETE and the safe methods such as GET as idempotent; POST is not. A checkout is a POST, and mobile networks retry. The caller sends an Idempotency-Key header, and the server stores the first result under that key, so a retry returns the same response instead of creating a second order. The same key with a different body is rejected as a conflict. At the time of writing, the header is described in an IETF draft (draft-ietf-httpapi-idempotency-key-header, an Internet-Draft rather than a published RFC), though it is already a common convention. Stage 6 shows how Payments applies the key.

Error format. RFC 9457 (which obsoletes RFC 7807) defines application/problem+json with type, title, status, detail and instance.

{
  "type": "https://quickcart.example/problems/out-of-stock",
  "title": "Item out of stock",
  "status": 409,
  "detail": "Only 2 units of SKU 8841 remain at store 17.",
  "instance": "/v1/checkouts/c_5521"
}

One shape for every error lets clients and the gateway handle failures uniformly. Never put a stack trace or an internal hostname in detail.

Rate limiting

Rate limiting rejects callers that exceed an agreed rate, with 429 Too Many Requests (RFC 6585), optionally with a Retry-After header. Worked example, an illustrative policy of 5 checkout attempts per shopper per minute:

• Fixed window. Count per calendar minute, reset at the boundary. Cheap, but a shopper sends 5 requests at 12:00:58 and 5 more at 12:01:02: ten in four seconds, all allowed.
• Sliding window log. Store each request's timestamp, drop those older than 60 seconds, count the rest. At 12:01:02 the five from 12:00:58 still count, so the sixth is rejected. Exact, but memory grows with the limit for every key.
• Sliding window counter. Keep two counters and weight the previous one. At 12:01:15 (25 percent into the window) with 5 in the previous minute and 1 now: 5 x 0.75 + 1 = 4.75, below 5, so allow. An approximation with tiny memory.
• Token bucket. A bucket holds up to 5 tokens and gains one every 12 seconds. A request spends a token. Five requests at t = 0 pass (bucket empty), a sixth at t = 3 s is rejected (0.25 tokens), and one at t = 12 s passes. It allows bursts up to capacity and holds the long-run rate. Amazon API Gateway documents using this algorithm.
• Leaky bucket. Requests queue in a bucket of 5 and are released one every 12 seconds, the first at t = 12 s. A burst of 5 at t = 0 fills it and a sixth at t = 1 s is rejected. Output is perfectly smooth, but queued requests wait.

QuickCart picks the token bucket at the gateway because shoppers legitimately click quickly in short bursts. Counters sit in a shared store (a Redis-style cache) so every gateway instance sees the same count. See rate limiting.

Where functions fit, and where they do not

Serverless and event-driven design

Serverless functions run your code on demand, scale with the number of events and bill by use, with no servers to manage. They are event-driven: something happens (an object is uploaded, a webhook arrives, a message is published) and a function reacts.

Two good fits in QuickCart:

1. Image resizing. A store uploads a product photo, the object store emits an event, and a function writes thumbnails. The work is bursty, stateless and not on a shopper's request path.
2. Webhooks. The payment provider and courier partners call QuickCart with status changes at unpredictable times. A function verifies the signature, writes the event to the broker and returns quickly, and the saga takes over.

Limits, stated generally. A cold start is the extra latency when the platform must prepare a new execution environment before running your handler. AWS's Lambda documentation describes the lifecycle (initialisation, invocation, shutdown), notes that environments are reused but must not be assumed to persist, and offers provisioned concurrency to pre-initialise environments. Functions also have maximum run times, and many concurrent instances can exhaust a relational database's connections. Platforms differ, so read your provider's current quotas.

So QuickCart does not run checkout in functions: it is latency-sensitive, steady and stateful. Event delivery is at least once, so every handler must be idempotent.

Many stores, one platform

Multi-tenancy

Multi-tenancy means one running system serves many customers, called tenants, whose data must stay apart. In QuickCart each of the 5,000 stores is a tenant. To keep the lesson simple, assume each cart and order belongs to one store (illustrative; a multi-store cart would become several orders).

QuickCart is pooled by default with a siloed option later for a very large chain that demands it. Three rules make pooling safe:

1. The tenant id comes from the verified token, never from the request body. A store user's token carries a store_id claim.
2. Every row and every query carries it. Repositories take the tenant as a required argument.
3. The database enforces it too. PostgreSQL row-level security applies a policy to every query, as a second line of defence.

ALTER TABLE stock ENABLE ROW LEVEL SECURITY;
ALTER TABLE stock FORCE ROW LEVEL SECURITY;

CREATE POLICY store_isolation ON stock
  USING (store_id = current_setting('app.store_id', true));

-- per request, inside the transaction:
SELECT set_config('app.store_id', 'store_17', true);

Per the PostgreSQL documentation, table owners bypass policies unless FORCE is set, and superusers and roles with BYPASSRLS always bypass them, so the service must connect as an ordinary role. If the setting was never set, current_setting(..., true) returns NULL; a reused connection may return an empty string instead. Neither matches a store, so no rows show. The third argument true to set_config makes the value local to the transaction, which matters when connections are pooled.

Noisy neighbours are tenants whose load harms others. The defences are per-tenant rate limits, a separate queue and worker pool for bulk imports (a bulkhead, stage 9), per-tenant quotas on batch size, and metrics grouped by tenant tier rather than 5,000 separate labels.

Figure 6. Tenant identity from token to row.

How to read this: the store id is set once at the edge from a verified claim and enforced twice more: in the service code and by the database policy. A bug in any one layer does not expose another store's rows.

Migrating safely

The strangler-fig path from the monolith

Martin Fowler named the strangler fig pattern after vines that grow around a host tree and gradually replace it. You build new components alongside the legacy system, route traffic to them piece by piece and retire the old parts, delivering value at each step instead of in one big rewrite.

QuickCart's sequence:

1. Put the gateway in front of the monolith, routing everything to it. No behaviour changes, and the seam exists.
2. Make the modules real inside the monolith. Seven modules, no cross-module table access, enforced by an automated architecture test.
3. Extract the cheapest, most valuable context first. Catalogue: read-heavy, about 2,300 requests per second at peak, and already on its own document store from stage 3. Reads move before writes.
4. Shift traffic gradually. First shadow the traffic and compare responses, then route 1, 10, 50 and finally 100 percent by path or weight at the gateway. Rollback is a routing change.
5. Move data ownership, then delete. The new service owns its store; the monolith calls its API instead of reading its tables; then the old code is removed.
6. Repeat for Delivery, Inventory, Payments and Notifications. Orders goes last: it is the most coupled and the sharded one.

Figure 7. Mid-migration: Catalogue extracted, the rest still in the monolith.

How to read this: the monolith still serves most paths but no longer touches catalogue data directly. Each extraction moves one more path to the right and shrinks the ochre box.

Decisions and trade-offs

In practice: QuickCart at this stage

The situation

Twenty-four engineers in four teams ship QuickCart weekly from one release train. This week the delivery team needs a fix to courier assignment before the evening peak, but the catalogue team's half-finished category change is on the same branch. Meanwhile, large stores upload their full price lists overnight, and checkout latency rises while they run.

Starting architecture

The first step needs no new service. The gateway goes in front, and the monolith becomes seven enforced modules.

Figure 8. Starting point for the split: gateway in front, seven modules inside.

How to read this: still one release, but each module owns its own schema and nothing reads another module's tables.

Options considered

The decision

Rollout and verification

For each extraction: shadow the traffic and compare responses; route 1 percent, then 10, 50 and 100, watching error rate, p99 latency and the shadow mismatch count at every step; keep the monolith path for one release, then delete it. Verify tenancy with a test that logs in as store A and tries to read store B (it must return nothing), and confirm the application's database role is not a superuser. Dashboards: per-service latency and error rate, gateway 429 rate, per-store request rate.

The 2 a.m. failure

At 02:00 a large store starts its nightly import of a full price list. Imports go through the same Catalogue instances that serve price lookups, and the Checkout service calls Catalogue with no deadline. Catalogue slows, Checkout threads wait on it, and checkouts begin to fail with 5xx. The alert reads: "Checkout error rate above 5 percent for 5 minutes."

First three checks: the latency and error rate of the Checkout to Catalogue call; the import queue and the per-store request rate (one store dominates); and PostgreSQL pg_stat_activity for long-running statements from the import. Mitigation: pause the import consumer, and serve cached last-known prices for a short, stated window while Catalogue recovers. Follow-ups: a deadline on every inter-service call, a separate worker pool for imports, a per-store limit on import rate and batch size, and an alert on the per-store share of Catalogue load.

Architecture after this stage

Figure 9. QuickCart after stage 8: seven services behind a gateway.

How to read this: rust-outlined boxes are new in this stage. Payments, Delivery and Notifications are reached through the broker, and the gateway also fronts Delivery for tracking connections (not drawn, to keep the figure readable).

What QuickCart looks like now

Architect's notes

• Boundaries before deployables. Redrawing a module boundary is far cheaper than redrawing a service boundary.
• Count synchronous hops. Each hop adds latency and a failure mode.
• Ask who owns each table. If the answer is two teams, the boundary is wrong.
• Defer the mesh and GraphQL. Pick them when a measured pain names them.
• Test tenancy adversarially. A test that tries to read another store's data beats a policy review.

Common mistakes

• Splitting by technical layer (a "database service", a "validation service") instead of by business context.
• A shared database between services. It is a monolith with extra network hops.
• Business logic in the gateway. Every team edits it and its failure takes everything down.
• Synchronous chains. Service A calls B calls C calls D, and the slowest one sets everyone's latency.
• Trusting a tenant id from the request body. Take it from the verified token.
• Moving everything at once. There is no rollback for a big bang.

Key takeaways

• Split by bounded context, where language and data ownership change, not by layer.
• Modules first; a service only where release, scale or isolation pays for the costs of distribution.
• Use ports and adapters so the domain survives a change of database or provider.
• The gateway handles authentication, routing, limits and aggregation, and no business rules.
• Choose the communication style per conversation: REST outside, gRPC between services, events for the saga, WebSockets for tracking.
• Prefer cursor pagination, an idempotency key on POST and one error format (RFC 9457).
• Token bucket tolerates bursts; fixed windows leak at the boundary.
• Pooled tenancy needs the tenant id in the token, in every row and enforced by the database.
• Migrate with a strangler fig: gateway first, one context at a time, with a rollback at every step.

Practice exercises

Exercise 1 (30 minutes): List what the word order means in Orders, Payments, Delivery and Notifications. Write one sentence for each and decide which fields each context really needs.

Exercise 2 (1 hour): For a token bucket of capacity 10 refilling 2 tokens per second, trace 15 requests arriving at t = 0 and then 1 request each second for 5 seconds. List which are allowed.

Exercise 3 (2 hours): Add Returns and Refunds as an eighth context. Place it on the context map, name what it owns, pick its relationships to Orders and Payments, and say whether it should be a module or a service on day one.

Exercise 4 (half day): Write a port and a fake adapter for Delivery's courier-assignment partner, then test the use case with no network.

Related reading

• Stage 5: The order pipeline for the saga this stage's services take part in.
• Stage 6: Payments and the ledger for idempotency in depth.
• Stage 9: Surviving failure, which adds timeouts, circuit breakers and bulkheads.
• Stage 10: Secure and operate, where the mesh decision returns.
• Architecture styles, API gateway and service mesh, API design, rate limiting and distributed transactions.

Official documentation

• Kubernetes: Service and DNS for Services and Pods
• Istio: security concepts
• RFC 9457: Problem Details for HTTP APIs
• PostgreSQL: row security policies
• AWS Lambda: execution environment lifecycle
• gRPC: core concepts