Decomposition, modularity, cohesion, coupling, and boundaries
A useful module owns a coherent capability, protects invariants, exposes an intentional contract, and can change without coordinating with unrelated parts. Distribution does not create modularity.
Core ideas and patterns
| Idea | What it solves | Cost, limit, or warning |
|---|---|---|
| Functional decomposition | Groups steps or technical functions | Often scatters one business change across layers |
| Domain decomposition | Groups business language, rules, and data | Needs domain knowledge and careful boundary discovery |
| Volatility-based decomposition | Isolates things likely to change | Volatility predictions can be wrong |
| Afferent/efferent coupling | Shows incoming responsibility and outgoing dependency | Counts do not reveal semantic strength |
| Temporal coupling | Requires operations in an order or time window | Hidden timing creates brittle workflows |
| Data coupling | Connects modules through shared schema/state | A shared database can be stronger than API coupling |
| Connascence | Names what multiple parts must agree on | Move strong forms closer and weaken across boundaries |
| Bounded context | Protects a domain model and language | Not every context deserves a distributed service |
How to apply it
Map business capabilities, invariants, transactions, vocabulary, data ownership, change history, and team ownership. Cluster things that change and fail together. Make cross-boundary commands and events explicit. Start with in-process modules unless independent deployment, scaling, isolation, or governance has proven value.
Evidence, not opinion
Analyze repository co-change, cross-team coordination, cyclic dependencies, shared tables, runtime call graphs, incident propagation, and release coupling. A boundary should reduce at least one measurable form of coupling.
Small example
Inventory reservation owns available quantity and reservation expiry. Checkout may request a reservation but cannot update inventory tables. The boundary protects the no-oversell invariant.
Feynman check
Explain the design to a new engineer without using the pattern names. State the problem, the forces that conflict, the chosen boundary or mechanism, what can fail, and the evidence that would prove the choice still works.