/service-decomposition

name: service-decomposition
description: This skill should be used when the user asks "monolith vs microservices", how to "split into services", set "service boundaries", find the right "service granularity", design an "API gateway / BFF", do "service discovery" or add a "service mesh", or worries that services are "too chatty" / "too fine-grained". It gives the recipe for carving a system into services (or deciding not to) and wiring how they find and call each other. Use it whenever a design has more than one service — or someone is tempted to add more — even if the user doesn't say "microservices".

Service Decomposition

Decide how to carve a system into deployable services — or whether to — and how those services find and call each other. This is the "application layer" of a design: it sits between the edge (`dns`/`load-balancing`/`content-delivery`) and the data tier. Getting the *granularity* wrong is one of the most expensive mistakes in distributed systems, in both directions.

> The trap cuts both ways. One giant service can't scale teams or components > independently; a swarm of tiny ones drowns you in network hops, partial > failures, and undebuggable cross-service traces. The skill is finding the > sweet spot for *this* system at *this* size — not maximizing service count.

When to reach for this

A second service is on the table; teams need to deploy independently; one part has a wildly different scaling profile than the rest; or an existing system is "too chatty" / hard to change. Also when someone proposes "microservices" by default.

When NOT to

A new product / small team / unproven domain — start with a **monolith** (or a modular monolith) and split later when a real seam and a real reason appear. Splitting prematurely buys distributed-systems cost (network failure, eventual consistency, ops) to solve a problem you don't have yet (YAGNI, GUIDE #7). Don't add a gateway/mesh/discovery layer before you have services that need them.

Clarify first

• **Team & deploy independence** — must parts ship on separate cadences/owners?
• **Differential scale** — does one component need 100× the others' resources?
• **Coupling** — which parts change together (belong together) vs evolve apart?
• **Latency budget** — how many in-process calls would become network hops?
• **Consistency across the seam** — can the split tolerate eventual consistency

between services? (→ `consistency-coordination`)

The options

• **Monolith** — one deployable. Use when: new/small, fast iteration, strong

cross-module transactions, one team.

• **Modular monolith** — one deployable, enforced internal module boundaries.

Use when: you want clean seams *without* network cost yet — the best default for "we might split later."

• **Microservices** — many small deployables split by business capability /

bounded context. Use when: independent deploy/scale/ownership genuinely pays for the distributed-systems tax.

• **Comms style** — decide only whether a given seam is **synchronous** (REST/gRPC,

request/response, simple but couples availability) or **asynchronous** (decoupled but eventually consistent). This block decides *sync-or-async per seam*; it does **not** own the async mechanics — once a seam is async, **invoke `messaging-streaming`** for the delivery guarantees, ordering, backpressure, and DLQ semantics that make it safe. Don't pick async from the one-line "no immediate answer needed" rule without opening those failure modes. Most systems are a mix.

• **Edge of the service tier** — an **API gateway / BFF** (one front door:

auth, routing, rate limiting, aggregation) vs direct exposure.

• **Finding each other** — **service discovery** (registry: DNS-based, or

etcd/Consul/ZooKeeper) and optionally a **service mesh** (sidecars for mTLS, retries, traffic shaping) vs library-level clients.

Trade-offs

| Option | What it solves | What it worsens | Change it when | |---|---|---|---| | Monolith | Simplicity; in-process calls; easy transactions/debugging | Couples deploy/scale; one team bottleneck; blast radius | Teams/scale profiles diverge → modular monolith → split a seam | | Modular monolith | Clean boundaries, no network cost, split-later optionality | Still one deploy; discipline required to keep modules clean | A module needs independent deploy/scale → extract it to a service | | Microservices | Independent deploy/scale/ownership per capability | Network failure, eventual consistency, distributed debugging, ops | Coordination/latency cost exceeds the independence benefit → merge | | Sync comms | Simple mental model, immediate result | Availability couples (caller fails if callee does); latency stacks | A call doesn't need an immediate answer → async (`messaging-streaming`) | | API gateway / BFF | One front door for auth/routing/rate-limit/aggregation | A new tier + potential SPOF/bottleneck; can become a mini-monolith | It accretes business logic → push logic back into services | | Service mesh | Uniform mTLS/retries/observability without app changes | Real operational + latency overhead (sidecars) | A handful of services → a library/gateway is enough |

Behavior under stress

• **Chatty services / fan-out:** one user request becomes N synchronous internal

calls; tail latency compounds and a single slow dependency stalls the chain. *Mitigate:* coarser boundaries, batching, async where an answer isn't needed now, and circuit breakers (→ `resilience-failure`).

• **Distributed-transaction pain:** a write spanning services can't be one ACID

transaction. *Mitigate:* saga / outbox, or **keep the data in one service** so the transaction stays local (→ `consistency-coordination`).

• **Retry storms across the mesh:** naive retries amplify an overload into a

cascade. *Mitigate:* backoff+jitter, budgets, circuit breakers (→ `resilience-failure`).

• **Debuggability collapse:** with no correlation IDs/tracing, a failure that

crosses 6 services is invisibl