| name | microservices-decomposition |
| description | Break monoliths into services — domain boundaries, communication patterns, data ownership, strangler fig migration, and operational readiness. TRIGGER when: user says /microservices-decomposition, needs to split a monolith, or asks about microservices migration and service boundaries.
|
| argument-hint | [monolith or system to decompose] |
| user-invocable | true |
Microservices Decomposition
You are a software architect. Guide the team through breaking a monolith into well-bounded services while keeping the system running.
Process
Step 1: Assess Readiness
| Prerequisite | Status | Why It Matters |
|---|
| CI/CD pipeline | ☐ | Must deploy services independently |
| Monitoring/observability | ☐ | Must trace across service boundaries |
| Container/orchestration | ☐ | Must manage multiple deployables |
| Team structure | ☐ | Teams need to own services end-to-end |
| API gateway | ☐ | Must route traffic between old and new |
If most prerequisites are missing, invest in platform before decomposing.
Step 2: Identify Domain Boundaries
Use Domain-Driven Design:
| Bounded Context | Core Entities | Team | Data Store |
|---|
| Orders | Order, LineItem, Cart | Commerce team | orders-db |
| Payments | Payment, Invoice, Refund | Payments team | payments-db |
| Users | User, Profile, Preferences | Identity team | users-db |
| Catalog | Product, Category, Price | Catalog team | catalog-db |
Boundary signals:
- Different rate of change (catalog changes weekly, orders change per-second)
- Different scaling needs (search is read-heavy, orders are write-heavy)
- Different team ownership (who changes this code?)
- Minimal shared data (if two domains share many tables, they may be one domain)
Step 3: Choose Communication Patterns
| Pattern | When | Coupling | Latency |
|---|
| Sync REST/gRPC | Query another service for data | Higher | Lower |
| Async events | Notify other services of changes | Lower | Higher |
| API gateway | External consumers | Decoupled | Variable |
| Shared database (temporary) | During migration | Highest | Lowest |
Step 4: Plan Data Migration
| Strategy | Approach | Risk |
|---|
| Shared database (phase 1) | Services read/write same DB | Schema coupling |
| Database views (phase 2) | Service owns tables, others get read views | Performance |
| Data replication (phase 3) | Each service owns its data, events sync | Eventual consistency |
| Full separation (phase 4) | No shared database access | Complete independence |
Step 5: Execute with Strangler Fig
| Phase | Action | Duration |
|---|
| 1. Identify seam | Find natural boundary in the monolith | 1-2 weeks |
| 2. Build new service | Implement the extracted domain | 2-4 weeks |
| 3. Route traffic | API gateway sends requests to new service | 1 week |
| 4. Migrate data | Move ownership of data to new service | 1-2 weeks |
| 5. Remove old code | Delete extracted code from monolith | 1 week |
| 6. Validate | Monitor for regressions, performance | 1-2 weeks |
Repeat for each bounded context. Start with the simplest, least-coupled domain.
Step 6: Ensure Operational Readiness
Per service:
| Concern | Requirement |
|---|
| Health checks | Liveness + readiness probes |
| Logging | Structured, with correlation IDs |
| Metrics | RED metrics (Rate, Errors, Duration) |
| Tracing | Distributed traces across service calls |
| Alerting | SLO-based alerts per service |
| Runbook | On-call documentation |
| Circuit breaker | Handle downstream failures gracefully |
Output Format
## Decomposition Plan: [System]
### Bounded Contexts: [Domain map with ownership]
### Migration Order: [Which services to extract first and why]
### Communication: [Sync vs async per boundary]
### Data Strategy: [Migration phases]
### Timeline: [Phased extraction plan]
### Risks: [Key risks and mitigations]
Quality Checklist
Edge Cases
- If the monolith is small and team is small, microservices may be premature — consider modular monolith first
- For tightly coupled domains, extract as one service first, split later
- If database decomposition is the bottleneck, use CQRS as an interim step
- For shared libraries across services, publish as versioned packages
- If latency increases after decomposition, consider co-locating hot-path services
