Microservices Design

Microservices Design

Microservices trade local complexity for distributed complexity: every boundary you draw buys independent deployment and ownership at the price of network latency, partial failure, and eventual consistency. The costly mistake this skill prevents is the distributed monolith - a system with all the operational cost of microservices and none of the independence, usually created by splitting along technical layers or by letting two services share a database.

Operating procedure

Step 1: Gather inputs

1. Team topology: how many teams, and who owns what today. Label guesses as guesses.
2. The bounded contexts of the domain (orders, inventory, billing…), and which change together.
3. Scaling asymmetries: which module needs 10x the resources of the rest.
4. Deploy friction evidence: how often does one team's change block another's release.
5. Operational maturity: CI/CD, observability with distributed tracing, on-call. Without these, more services means more outages.

Step 2: Apply the extraction criteria - team ownership first, size never

Start from a modular monolith and extract only when a criterion is met. In priority order:

1. Team ownership boundary: a distinct team needs to deploy and be on call for this capability without coordinating releases. This is the strongest reason - services exist to give teams autonomy. One team owning six services is usually five services too many; a service split across two teams is a coordination bug.
2. Independent scaling: the module needs materially different resources (a 10x difference, not 20%).
3. Isolation: a failure or security domain that must be blast-radius-limited (payment processing, untrusted-code execution).
4. Technology mismatch: the capability genuinely requires a different runtime.

"It's getting big" is not a criterion. Lines of code never justify a network boundary; team cognitive load does.

Step 3: Draw boundaries on business capabilities

• Align services to bounded contexts (Order, Inventory, Billing), never technical layers (API service, DB service, "utils service").
• Each service owns its data exclusively; no other service touches its database. Shared DB = distributed monolith, full stop.
• High cohesion inside, loose coupling across. Litmus test: if two services always change in the same PR-pair, they are one service - merge them.
• Duplicate small amounts of data across services rather than creating a chatty synchronous dependency; a copied customer_name is cheaper than a runtime call on every request.

Step 4: Choose communication per edge

• Synchronous (REST/gRPC) only where the caller cannot proceed without the answer (auth check, inventory reservation at checkout). Every sync edge couples your availability: two services at 99.9% in series give 99.8%.
• Asynchronous (events/queues) for everything else - workflows, notifications, read-model updates. Prefer async by default for resilience.
• Contracts are explicit and versioned (OpenAPI, protobuf, AsyncAPI); backward-compatible changes only, additive schema evolution, tolerant readers. Never break an existing event consumer.

Order Service --(OrderPlaced event)--> Inventory Service
                                   --> Notification Service

• Rule of thumb: if a request fans out synchronously to more than 2 downstream services, redesign - either the boundary is wrong or the read belongs in a CQRS read model fed by events.

Step 5: Design consistency deliberately

• Distributed transactions are off the table; use the Saga pattern - a sequence of local transactions with compensating actions for rollback (e.g. CancelReservation compensates ReserveStock). Every step must have a written compensation before the saga ships.
• Use the Outbox pattern to publish events atomically with the local DB write; a bare "write then publish" loses events on crash.
• Make every consumer idempotent and deduplicate by event id - at-least-once delivery is the reality of every broker.
• Embrace eventual consistency and design UIs to tolerate it (optimistic "order received" states, not spinners waiting on five services).

Step 6: Apply the resilience defaults on every remote call

• Timeout on every call - no exceptions; 1-5s for user-facing sync calls, never "infinite".
• Circuit breakers on dependencies so a failing service isn't hammered into a longer outage.
• Retries with exponential backoff and jitter, for transient errors only, and only on idempotent operations.
• Bulkheads: separate connection/thread pools per dependency so one slow dependency can't exhaust the caller.
• Propagate a correlation/trace id across every hop; without distributed tracing, debugging n services is guesswork.
• Externalize service discovery and config; never hardcode endpoints.

Worked artifact: boundary decision - good/bad pair

Bad: an e-commerce team of 8 engineers splits into api-gateway, user-service, product-service, order-service, payment-service, email-service, search-service, admin-service - eight services, one team, one shared Postgres. Result: every feature touches four repos, releases are lockstep, one DB migration blocks everyone. Distributed monolith.

Good: the same team ships a modular monolith with enforced module boundaries (orders, catalog, identity) plus exactly one extracted service: payment-service, because it is a PCI isolation domain with its own database and an async PaymentCaptured event. When the company later adds a dedicated search team, search-service is extracted along that ownership line, fed by ProductUpdated events.

Extraction verdict template:

CANDIDATE: [FILL: capability]
Owning team (exactly one): [FILL]           -> no single team? STOP, fix org first
Criterion met: ownership / scaling(10x?) / isolation / tech  [FILL + evidence]
Data owned exclusively: [FILL: tables/entities moving with it]
Edges: sync -> [FILL: callers + why sync]   async -> [FILL: events in/out]
Consistency: sagas touching it: [FILL], compensations written: yes/no
Verdict: EXTRACT / KEEP AS MODULE / MERGE WITH [FILL]

Deliverable

Produce a boundary map: the list of services (and modules deliberately kept in the monolith), each with owning team, exclusive data, sync and async edges, saga/compensation notes, and an extraction verdict with the criterion that justified it.

Do NOT

• Do not split by technical layer - an "API layer service" and "data layer service" couple every change across both.
• Do not share a database between services; it silently welds their schemas and deploys together.
• Do not extract because a module is large; size is a refactoring problem, not a network-boundary problem.
• Do not default to synchronous calls - each one multiplies unavailability and latency down the chain.
• Do not ship a saga without written compensations for every step.
• Do not give one small team many services; the operational load per service is roughly constant and it lands on them.
• Do not start microservices without tracing, centralized logging, and per-service CI/CD already working.

Quality bar

• Every service maps to a business capability and exactly one owning team.
• No shared databases anywhere on the map; every arrow is labeled sync or async with a reason.
• Every sync chain is ≤ 2 hops deep from the entry point.
• Every cross-service write path names its saga and compensations; every consumer is idempotent by event id.
• Timeouts, retries-with-jitter, and circuit breakers are stated defaults, not aspirations.

Escalation

For the migration sequencing off an existing monolith, use monolith-decomposer and strangler-fig-planner - this skill decides the target, those decide the path. Individual API contracts go to api-design or graphql-schema; event pipeline design to kafka-pipelines; circuit-breaker implementation detail to circuit-breaker-builder; idempotent consumers to idempotency-enforcer.