Microservices Decomposition Guide

Plan the decomposition of a monolith into microservices with minimal disruption.

**Current Monolith:** [TECH STACK / FRAMEWORK / DATABASE / SIZE (lines of code or modules)]
**Team Structure:** [1 TEAM / 2-3 TEAMS / CROSS-FUNCTIONAL TEAMS]
**Business Domain:** [E-COMMERCE / SAAS / MARKETPLACE / FINTECH / HEALTHCARE]

**Decomposition Strategy:**

**Domain-Driven Design Boundaries:**
- Bounded context identification: map existing modules to business domains
- Context mapping: identify which contexts are shared, customer-supplier, or conformist relationships
- Aggregate boundaries: define transactional consistency boundaries within each service
- Anti-corruption layer design for integrating with legacy systems during transition

**Service Ownership Model:**
- Team-to-service mapping (one team owns one service end-to-end)
- Platform team for shared infrastructure (CI/CD, monitoring, service mesh)
- API contract ownership and versioning policy
- Service catalog with owner, SLA, and documentation links

**Inter-Service Communication:**
- Synchronous: REST/gRPC for real-time queries where consistency is needed
- Asynchronous: event-driven messaging (Kafka/RabbitMQ) for eventual consistency
- API Gateway pattern: single entry point for external clients, routing to appropriate services
- Service mesh consideration (Istio/Linkerd) for observability and traffic management
- Circuit breaker pattern implementation for fault tolerance
- Idempotency keys for all inter-service API calls

**API Gateway Pattern:**
- Request aggregation (bFF-style composition at gateway level)
- Authentication/authorization delegation at gateway
- Rate limiting per service and per client
- Response transformation (format normalization across services)
- GraphQL federation as alternative to REST gateway

**Distributed Tracing Setup:**
- OpenTelemetry instrumentation in all services
- Trace ID propagation through synchronous and asynchronous calls
- Span tagging with business context (user_id, order_id, tenant_id)
- Jaeger/Zipkin visualization for debugging cross-service flows
- Error rate and latency alerting on trace data

**Saga Pattern for Transactions:**
- Choreography-based sagas (event-driven, no central coordinator)
- Orchestration-based sagas (central orchestrator service manages flow)
- Compensating actions design for each step in the saga
- Saga timeout handling and manual intervention workflows
- Idempotent compensating actions (can be called multiple times safely)

**Data Ownership Per Service:**
- Database-per-service pattern (no shared databases between services)
- Data duplication strategy: denormalize what's needed for read performance
- Event sourcing for audit-critical data (order changes, financial transactions)
- CQRS pattern: separate write model from read model for high-throughput queries
- Data migration strategy during transition period (dual-write approach)

**Migration Patterns:**
- Strangler Fig pattern: gradually route traffic to new services alongside monolith
- Parallel run phase: both old and new paths execute, results compared
- Feature flag strategy for gradual rollout per service
- Rollback plan: each service migration is independently reversible
- Monitoring during migration: compare metrics between old and new implementations

**Team Topology Recommendations:**
- Stream-aligned teams for core business domains (ordering, inventory, payments)
- Platform team for shared infrastructure and developer experience
- Enabling team pattern for helping teams adopt microservices patterns
- Complexity segregation team for cross-cutting concerns (security, compliance)

How to Customize It

Replace each bracketed placeholder with your own details before running the prompt. The more specific you are, the better the output — vague inputs produce generic results.

• [TECH STACK / FRAMEWORK / DATABASE / SIZE (lines of code or modules)]Swap in your tech stack or framework or database or size (lines of code or modules).
• [E-COMMERCE / SAAS / MARKETPLACE / FINTECH / HEALTHCARE]Swap in your e-commerce or saas or marketplace or fintech or healthcare.

When to Use It

• A growing monolith where team ownership conflicts and deploy contention are real, and you need boundaries drawn on evidence.
• Extracting one hot module (payments, notifications) without committing to full microservices.
• Writing the architecture RFC for a decomposition, with the migration plan and rollback story leadership will ask about.

Tips for Better Results

• 1Describe your actual pain (deploy conflicts? scaling one module? team autonomy?) — decomposition that doesn't target a named pain is fashion, and the prompt should tell you if you don't need it.
• 2The database split is the hard part; push the conversation there early. Shared tables between "separate" services is the most common failure state.
• 3Extract one service end-to-end, including its data and observability, before planning the next. The first extraction teaches you the real cost.