| name | system-decomposition |
| description | Break complex systems into bounded contexts with DDD. Map business capabilities to service boundaries, define ubiquitous language, assess cohesion/coupling. Use when refactoring monoliths or designing new architectures. |
| context | fork |
| agent | general-purpose |
| allowed-tools | Read, Grep, Glob, Write, Edit |
System Decomposition
Systematically decompose complex systems using Domain-Driven Design: identify business capabilities, define bounded contexts, evaluate cohesion/coupling, design integration patterns.
Context
You are decomposing a system into services or modules. Your role is to:
- Map business capabilities (not technical layers)
- Define bounded contexts with explicit boundaries
- Establish ubiquitous language (shared vocabulary per context)
- Assess cohesion (focus) and coupling (dependencies)
- Design integration patterns (sync API vs async events)
Good decomposition follows business domains, not technology layers. Anti-pattern: UserService, OrderService, PaymentService (implementation detail names) instead of Auth Realm, Commerce Hub, Payment Platform (domain names).
Domain Context
Based on Eric Evans' Domain-Driven Design and Sam Newman's Building Microservices:
- Bounded Context: Explicit boundary around business capability. Each context has its own domain model.
- Ubiquitous Language: Shared vocabulary within context (Order, Customer, Invoice). Prevents translation errors.
- Aggregate: Entity cluster within context. Single consistency boundary. Example: Order + OrderItems as one aggregate.
- Integration: How contexts communicate (Sync via API, Async via events, Shared database)
- Cohesion: Does everything in the context serve one purpose?
- Coupling: How many other services must it call?
When to Use This Skill
- Breaking monolith into services
- Designing new system architecture
- Refactoring tight coupling
- Aligning engineering teams to services
- Preparing for independent scaling/deployment
Prerequisites
- Understand business domains and pain points
- Know current system architecture (if refactoring)
- Have stakeholders available to discuss domain
- Can draw diagrams (whiteboard, miro, draw.io)
Instructions (Detailed)
1. Identify Business Capabilities
Ask: "What does the business do?"
Example (E-commerce):
- Authentication (who are you?)
- Commerce (what do you want?)
- Payment (how much does it cost?)
- Fulfillment (ship it)
- Analytics (understand customers)
- Support (help customers)
Each capability can become a bounded context.
2. Define Bounded Contexts
For each capability, establish boundary with explicit name and responsibilities.
Example:
Auth Realm (Authentication)
- User registration, login, session management
- Produces: authenticated identity tokens
- Language: User, Credential, Session, Auth Token
Commerce Hub (Order Processing)
- Order creation, cart management, inventory
- Consumes: Auth tokens
- Produces: Order events
- Language: Order, Customer, Product, Cart, OrderItem
Payment Platform (Payment Processing)
- Payment processing, refunds, accounting
- Consumes: Order events
- Produces: Payment status events
- Language: Payment, Invoice, Transaction, Settlement
3. Map Ubiquitous Language
Define key terms within each context:
Auth Realm:
- "User" = identity with credentials
- "Session" = authenticated connection
Commerce Hub:
- "Order" = customer purchase request
- "Customer" = entity that places orders (different from Auth's User)
Payment Platform:
- "Invoice" = billable entity (different from Order)
- "Settlement" = final accounting status
Contexts use same words differently. Clear boundaries prevent confusion.
4. Assess Cohesion & Coupling
Cohesion (within context):
- Do all functions serve one purpose? (high = good)
- Would we change them for the same business reason? (yes = high cohesion)
Coupling (between contexts):
- How many services must this call to complete a request?
- Sync vs Async: Sync = tight coupling, Async = loose coupling
- Target: Cohesion >80%, Coupling <3 sync calls/request
5. Design Integration Patterns
Synchronous (API call):
- Used for immediate results
- Tightly coupled
- Simple debugging
- Example: User creates order → Commerce Hub calls Payment Platform → charge card immediately
Asynchronous (event):
- Fire-and-forget
- Loosely coupled
- Difficult debugging
- Example: Order created → event published → Payment Platform subscribes and processes later
6. Create Context Diagram
Boxes = Contexts, Arrows = Synchronous calls, Events = Asynchronous communication.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Auth Realm │ │Commerce Hub │ │ Payment │
│ │ │ │ │ Platform │
│ - Register │──API───│ - Order │───API──│ - Process │
│ - Login │ │ creation │ │ payment │
│ - Session │ │ - Inventory │ │ - Refund │
└──────────────┘ │ │ └──────────────┘
│ Order Created│
│ Event ────────────────┐
└──────────────┘ │
Event Handler
(async payment)
7. Verify Against Anti-Patterns
- Distributed monolith: Services so tightly coupled they act as one → redraw boundaries
- Service per table: Data-driven decomposition (wrong) instead of domain-driven (right)
- Chatty services: Need >10 calls to complete request → larger bounded contexts
- God context: One service does everything → split into multiple contexts
Output Format
When decomposing, deliver:
- Business Capabilities: What the system does
- Bounded Contexts: Explicit boundaries with names
- Context Diagram: Visual showing contexts and integration
- Ubiquitous Language: Key terms per context
- Integration Patterns: Sync/Async by integration point
- Cohesion/Coupling Assessment: Scores for each context
- Deployment Plan: How to implement decomposition
Worked Example
Monolith: Single "UserService" handling everything (100K lines)
Issues:
- Changes to UI tier require payment code changes
- Teams can't deploy independently
- Database contention
Decomposition:
Bounded Contexts:
1. Auth Realm: Registration, login, profiles
2. Commerce Hub: Orders, cart, inventory
3. Payment Platform: Payments, invoicing, settlements
4. Analytics: User behavior, metrics
Cohesion Scores:
- Auth Realm: 95% (all about identity)
- Commerce Hub: 85% (order-related, but inventory is borderline)
- Payment Platform: 90% (all about money)
Coupling Analysis:
- Commerce → Payment (sync): Payment::charge(amount)
- Order Created → Analytics (async): Event subscriber
Integration:
Commerce Hub: POST /payment/charge with Order details
Response: Payment ID + status
On failure: Rollback order
Analytics: Subscribes to "OrderCreated" event
No coupling: Order doesn't wait for analytics
Decision Framework
- One large context or many small?: Start coarse; split when pain emerges
- Sync or Async?: Sync if needs immediate response (payment); Async if fire-and-forget (notifications)
- Shared data or separate databases?: Separate per context (independence); shared only for atomic transactions
- Communication overhead?: If sync calls >3 per request, reconsider boundaries
Anti-Patterns
- Premature Microservices: Break before understanding domains
- Technology-Driven: "Python team" vs "Python-for-ML domain"
- Ignoring Coupling: Services talk to every other service
- No Ubiquitous Language: Same word means different things
Quality Checklist
Further Reading
- Eric Evans, Domain-Driven Design (2003) — Foundational
- Sam Newman, Building Microservices (2nd ed., 2021) — Practical decomposition
- Dora et al., Accelerate — Impact of decomposition on deployment frequency
