Service Decomposition Strategies

Introduction

One of the hardest decisions in microservices is determining where to draw service boundaries. Through decomposing several monoliths and designing greenfield microservice systems, I've learned that poor decomposition leads to distributed monoliths—systems with all the complexity of microservices but none of the benefits.

This article covers practical strategies for identifying and defining service boundaries that align with your business and team structure.

The Decomposition Challenge

Poor decomposition results in:

• Distributed Monolith: Services that must be deployed together

• Chatty Communication: Excessive inter-service calls

• Shared Databases: Services coupled through data

• Circular Dependencies: Services that depend on each other

Bounded Contexts from Domain-Driven Design

The most reliable decomposition strategy comes from Domain-Driven Design (DDD). A bounded context is a boundary within which a particular domain model is defined and applicable.

Identifying Bounded Contexts

# Different contexts have different models for the same concept

# In Order Context - Product is just an ID and snapshot
from dataclasses import dataclass
from decimal import Decimal


@dataclass
class OrderLineItem:
    """Product in Order Context - minimal information needed for orders."""
    product_id: str
    product_name: str  # Snapshot at time of order
    unit_price: Decimal  # Snapshot at time of order
    quantity: int
    
    @property
    def total(self) -> Decimal:
        return self.unit_price * self.quantity


# In Inventory Context - Product is a rich domain object
@dataclass
class Product:
    """Product in Inventory Context - full product management."""
    id: str
    sku: str
    name: str
    description: str
    category_id: str
    base_price: Decimal
    cost: Decimal
    weight: float
    dimensions: dict
    is_active: bool
    
    def calculate_margin(self) -> Decimal:
        return self.base_price - self.cost
    
    def is_profitable(self) -> bool:
        return self.calculate_margin() > 0


# In Customer Context - might reference products as "purchased items"
@dataclass
class PurchaseHistory:
    """Product in Customer Context - focused on customer's view."""
    product_id: str
    product_name: str
    purchase_date: str
    purchase_price: Decimal

Context Mapping

When services need to interact, define explicit mappings:

# Anti-Corruption Layer - translates between contexts
from abc import ABC, abstractmethod


class ProductCatalogClient(ABC):
    """Port for accessing product information from Inventory Context."""
    
    @abstractmethod
    async def get_product_snapshot(self, product_id: str) -> dict:
        """Get product info needed for order creation."""
        pass


class InventoryServiceAdapter(ProductCatalogClient):
    """Adapter that translates Inventory Context to Order Context."""
    
    def __init__(self, http_client, inventory_service_url: str):
        self.client = http_client
        self.base_url = inventory_service_url
    
    async def get_product_snapshot(self, product_id: str) -> dict:
        # Call Inventory Service
        response = await self.client.get(
            f"{self.base_url}/products/{product_id}"
        )
        inventory_product = response.json()
        
        # Translate to Order Context's view
        return {
            "product_id": inventory_product["id"],
            "product_name": inventory_product["name"],
            "unit_price": inventory_product["base_price"],
            # Don't expose cost, margins, or inventory details
        }

Decomposition by Business Capability

Business capabilities represent what the business does, not how it does it.

Mapping Capabilities to Services

# Each capability becomes a candidate for a service

BUSINESS_CAPABILITIES = {
    "product_management": {
        "description": "Manage product catalog and pricing",
        "functions": [
            "Create and update products",
            "Manage categories",
            "Set pricing rules",
            "Handle product images",
        ],
        "data_owned": ["products", "categories", "pricing_rules"],
        "service": "product-service",
    },
    "inventory_management": {
        "description": "Track and manage stock levels",
        "functions": [
            "Track stock quantities",
            "Manage warehouses",
            "Handle reservations",
            "Low stock alerts",
        ],
        "data_owned": ["stock_levels", "warehouses", "reservations"],
        "service": "inventory-service",
    },
    "order_processing": {
        "description": "Handle customer orders",
        "functions": [
            "Create orders",
            "Manage order lifecycle",
            "Handle cancellations",
            "Order history",
        ],
        "data_owned": ["orders", "order_items", "order_status"],
        "service": "order-service",
    },
    "payment_processing": {
        "description": "Process payments and refunds",
        "functions": [
            "Process payments",
            "Handle refunds",
            "Manage payment methods",
            "Payment reconciliation",
        ],
        "data_owned": ["payments", "refunds", "payment_methods"],
        "service": "payment-service",
    },
}

The Strangler Fig Pattern

For existing monoliths, the Strangler Fig pattern allows incremental migration.

Implementing Strangler Fig

# Step 1: Create a facade that routes to monolith
from fastapi import FastAPI, Request
import httpx

app = FastAPI()


class RoutingConfig:
    """Configuration for routing between monolith and new services."""
    
    def __init__(self):
        self.routes = {
            # Initially, everything goes to monolith
            "/api/users": "http://monolith:8000",
            "/api/orders": "http://monolith:8000",
            "/api/products": "http://monolith:8000",
            "/api/payments": "http://monolith:8000",
        }
    
    def get_backend(self, path: str) -> str:
        for route_prefix, backend in self.routes.items():
            if path.startswith(route_prefix):
                return backend
        return "http://monolith:8000"


routing = RoutingConfig()


@app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def proxy(request: Request, path: str):
    """Proxy requests to appropriate backend."""
    backend = routing.get_backend(f"/{path}")
    
    async with httpx.AsyncClient() as client:
        response = await client.request(
            method=request.method,
            url=f"{backend}/{path}",
            headers=dict(request.headers),
            content=await request.body(),
        )
        return Response(
            content=response.content,
            status_code=response.status_code,
            headers=dict(response.headers),
        )


# Step 2: Extract a service and update routing
# After building user-service:
routing.routes["/api/users"] = "http://user-service:8000"

# Step 3: Continue extracting until monolith is empty

Migration Strategy

# Gradual migration with feature flags
from enum import Enum


class MigrationPhase(Enum):
    MONOLITH = "monolith"
    SHADOW = "shadow"  # New service receives traffic but responses discarded
    CANARY = "canary"  # Small percentage to new service
    FULL = "full"      # All traffic to new service


class ServiceRouter:
    """Route traffic based on migration phase."""
    
    def __init__(self):
        self.phases = {
            "user-service": MigrationPhase.FULL,
            "order-service": MigrationPhase.CANARY,
            "payment-service": MigrationPhase.SHADOW,
            "product-service": MigrationPhase.MONOLITH,
        }
        self.canary_percentage = 10
    
    def should_use_new_service(self, service: str, request_id: str) -> bool:
        phase = self.phases.get(service, MigrationPhase.MONOLITH)
        
        if phase == MigrationPhase.FULL:
            return True
        elif phase == MigrationPhase.CANARY:
            # Use request_id for consistent routing
            return hash(request_id) % 100 < self.canary_percentage
        elif phase == MigrationPhase.SHADOW:
            # Shadow mode: call both, return monolith response
            return False
        else:
            return False

Decomposition Heuristics

By Volatility

Separate components that change frequently from stable ones:

# High volatility - changes weekly
# → Separate service for faster deployment
class PricingService:
    """Pricing rules change frequently with promotions."""
    
    async def calculate_price(
        self, 
        product_id: str, 
        customer_segment: str,
        promo_codes: list[str]
    ) -> Decimal:
        base_price = await self.get_base_price(product_id)
        segment_discount = await self.get_segment_discount(customer_segment)
        promo_discount = await self.apply_promo_codes(promo_codes)
        return base_price * (1 - segment_discount) * (1 - promo_discount)


# Low volatility - changes rarely
# → Can stay in monolith longer
class TaxCalculationService:
    """Tax rules change rarely, usually annually."""
    
    def calculate_tax(self, amount: Decimal, jurisdiction: str) -> Decimal:
        rate = self.tax_rates.get(jurisdiction, Decimal("0.0"))
        return amount * rate

By Scalability Requirements

# High scale requirement - separate for independent scaling
# Product search might need 10x the resources of order processing

class ProductSearchService:
    """Needs horizontal scaling for high read volume."""
    
    def __init__(self, elasticsearch_client):
        self.es = elasticsearch_client
    
    async def search(self, query: str, filters: dict) -> list[dict]:
        # Handles millions of searches per day
        pass


# Lower scale requirement
class OrderService:
    """Lower volume, but higher consistency requirements."""
    
    async def create_order(self, order_data: dict) -> Order:
        # Handles thousands of orders per day
        pass

By Team Structure (Conway's Law)

# Team ownership model
SERVICE_OWNERSHIP = {
    "user-service": {
        "team": "identity-team",
        "slack_channel": "#identity-team",
        "on_call": "[email protected]",
        "repository": "github.com/company/user-service",
    },
    "order-service": {
        "team": "commerce-team",
        "slack_channel": "#commerce-team",
        "on_call": "[email protected]",
        "repository": "github.com/company/order-service",
    },
    "payment-service": {
        "team": "payments-team",
        "slack_channel": "#payments-team",
        "on_call": "[email protected]",
        "repository": "github.com/company/payment-service",
    },
}

Common Decomposition Mistakes

1. Too Fine-Grained

# ❌ Bad: Entity-per-service (nano-services)
# Results in excessive network calls

class AddressService:
    """Just manages addresses - too granular!"""
    pass

class PhoneNumberService:
    """Just manages phone numbers - too granular!"""
    pass

class EmailService:
    """Just manages emails - too granular!"""
    pass


# ✅ Good: Aggregate related entities
class ContactInfoService:
    """Manages all contact information for users."""
    
    async def update_address(self, user_id: str, address: dict): ...
    async def update_phone(self, user_id: str, phone: str): ...
    async def update_email(self, user_id: str, email: str): ...

2. Shared Database

# ❌ Bad: Services sharing the same database
# Creates hidden coupling

class OrderService:
    def create_order(self, user_id: str):
        # Directly accessing user table - hidden dependency!
        user = self.db.query("SELECT * FROM users WHERE id = ?", user_id)
        # ...


# ✅ Good: Each service owns its data
class OrderService:
    def __init__(self, user_client: UserServiceClient):
        self.user_client = user_client
    
    async def create_order(self, user_id: str):
        # Explicit dependency through API
        user = await self.user_client.get_user(user_id)
        # ...

3. Circular Dependencies

# ❌ Bad: Circular API calls
class UserService:
    async def get_user_with_orders(self, user_id: str):
        user = await self.get_user(user_id)
        # Calling back to Order Service - circular!
        orders = await self.order_client.get_user_orders(user_id)
        return {**user, "orders": orders}


# ✅ Good: Use events for reverse direction
class OrderService:
    async def create_order(self, order: Order):
        saved_order = await self.repository.save(order)
        # Publish event instead of callback
        await self.event_bus.publish(
            "order.created",
            {"order_id": saved_order.id, "user_id": saved_order.user_id}
        )
        return saved_order


class UserService:
    # Subscribe to order events if needed
    async def handle_order_created(self, event: dict):
        await self.update_user_stats(event["user_id"])

Practical Exercise

Exercise: Decompose an E-commerce Monolith

Given this monolith structure, identify service boundaries:

# Current monolith structure
"""
app/
├── models/
│   ├── user.py           # User, UserProfile, Address
│   ├── product.py        # Product, Category, ProductImage
│   ├── inventory.py      # Stock, Warehouse, Reservation
│   ├── order.py          # Order, OrderItem, OrderStatus
│   ├── payment.py        # Payment, Refund, PaymentMethod
│   ├── shipping.py       # Shipment, Carrier, TrackingInfo
│   └── notification.py   # Notification, EmailTemplate
├── services/
│   ├── user_service.py
│   ├── product_service.py
│   ├── inventory_service.py
│   ├── order_service.py
│   ├── payment_service.py
│   ├── shipping_service.py
│   └── notification_service.py
└── api/
    └── routes.py
"""

# Suggested decomposition:
PROPOSED_SERVICES = {
    "user-service": {
        "models": ["User", "UserProfile", "Address"],
        "bounded_context": "Identity & Access",
        "team": "identity-team",
    },
    "catalog-service": {
        "models": ["Product", "Category", "ProductImage"],
        "bounded_context": "Product Catalog",
        "team": "catalog-team",
    },
    "inventory-service": {
        "models": ["Stock", "Warehouse", "Reservation"],
        "bounded_context": "Inventory Management",
        "team": "fulfillment-team",
    },
    "order-service": {
        "models": ["Order", "OrderItem", "OrderStatus"],
        "bounded_context": "Order Management",
        "team": "commerce-team",
    },
    "payment-service": {
        "models": ["Payment", "Refund", "PaymentMethod"],
        "bounded_context": "Payments",
        "team": "payments-team",
    },
    "shipping-service": {
        "models": ["Shipment", "Carrier", "TrackingInfo"],
        "bounded_context": "Fulfillment",
        "team": "fulfillment-team",
    },
    "notification-service": {
        "models": ["Notification", "EmailTemplate"],
        "bounded_context": "Communications",
        "team": "platform-team",
    },
}

Key Takeaways

1. Use Bounded Contexts - DDD provides the most reliable decomposition strategy

2. Start with capabilities - Decompose by what the business does, not technical layers

3. Apply Strangler Fig - Migrate incrementally, not with big rewrites

4. Respect Conway's Law - Align services with team structure

5. Avoid common mistakes - No shared databases, no circular dependencies

What's Next?

With services identified, we need well-designed APIs for communication. In Article 3: API Design for Microservices, we'll cover REST principles, versioning strategies, and contract-first design with OpenAPI.

---

This article is part of the Microservice Architecture 101 series.