What is the Decompose by Subdomain pattern?
Use domain-driven design to find the subdomains of the business (orders, billing, catalog, shipping) and the bounded contexts where each term has one meaning. Each service owns one context end to end: its API, its logic and its data. A team can change it without coordinating with others.
What problem does the Decompose by Subdomain pattern solve?
Splitting by layer (a validation service, a database service) or by entity (one CRUD service per table) makes almost every feature touch several services. Boundaries that follow the business keep most changes inside one service, which is the whole payoff of microservices.
How do you implement the Decompose by Subdomain pattern?
- Map business capabilities and subdomains with the people who run them. Event storming workshops are a fast way to do it.
- Find the bounded contexts: places where the same word (customer, product, order) means something different.
- Start with coarse services. Split further only when you have evidence, such as different scaling needs or constantly colliding teams.
- Define each context's public contract as an API or a set of events, and keep the model behind it private.
- Align team ownership with the boundary so one team can build, deploy and run each service.
When should you use it?
- You are breaking up a monolith or designing a system with a rich business domain.
- Several teams need to ship independently.
- Features regularly cut across technical layers and cause merge conflicts and release coordination.
When should you avoid it?
- The team is small and the domain simple. A modular monolith gives you the same boundaries at a fraction of the cost.
- The domain is not yet understood. Wrong boundaries are expensive to move once they are network calls.
What do you gain?
- Changes stay local to one service and one team
- Clear ownership and language
- Matches how the organisation actually works
What does it cost?
- Needs real domain knowledge up front
- Wrong boundaries produce a distributed monolith
- Moving a boundary later means moving data and contracts
What are common mistakes with the Decompose by Subdomain pattern?
- Nano-services: dozens of tiny services that cannot do anything alone.
- One service per database table, which turns every business operation into a chain of calls.
- A shared 'common' library that forces every service to share one domain model.
Decompose by Subdomain in practice
Larkspur Audio
Playback, playlists and royalty accounting shared one User model. A change to how playback tracked listeners quietly changed the numbers royalty reports were built on.
The team split the system into bounded contexts, each with its own model of a listener. Royalty accounting now receives play events through a published contract instead of reading playback's tables.
Example decision record
- Context
- Several teams disagree about what a Customer is, and changes to the shared model keep breaking each other.
- Decision
- Use bounded contexts from domain-driven design as the primary rule for drawing service boundaries.
- Consequences
- Each service keeps a private model in its own language.
- Exchanging data between contexts needs explicit translation, such as an anti-corruption layer.