Service Boundaries — How to Split a Monolith Without Regret

Anti-pattern 1: Shared database
  Order Service ──┐
  Product Service ─┼── Same database
  User Service ───┘
  
  → One schema change breaks all three services
  → Teams step on each other's migrations
  → Not independently deployable at the data layer

Anti-pattern 2: Synchronous chain of calls
  API Request → Service A → Service B → Service C → Service D
  (if any service is slow or down, the whole request fails)
  (changing Service C's response shape breaks B and A)

Anti-pattern 3: Chatty services
  "Get user with their orders" requires:
  1. Call User Service
  2. Call Orders Service with userId
  3. For each order, call Product Service
  4. For each product, call Inventory Service
  → 4N+2 network calls for what should be one query

The word "Customer" means different things:

  In Sales context:
    Customer = { id, name, email, leadSource, salesRep, dealValue }
    
  In Support context:
    Customer = { id, name, email, ticketHistory, tier, SLA }
    
  In Shipping context:
    Customer = { id, name, deliveryAddresses, preferredCarrier }

High cohesion:
  Order Service owns:
    - Create order
    - Update order status  
    - Cancel order
    - Get order history
  All relate to the lifecycle of an order.

Low cohesion (bad):
  "Transaction Service" owns:
    - Create order
    - Process payment
    - Update inventory
    - Send email
  These all happen at checkout but belong to different domains.

Low coupling (good):
  Order Service needs to know: "payment was successful" (event)
  It does NOT need to know: how Payment Service processes cards,
    which gateway it uses, or what its internal data model looks like.

High coupling (bad):
  Order Service calls Payment Service and directly reads
  payment.internalState.processorResponse.cardNetwork.authCode
  → Any change to Payment Service's internals breaks Order Service

Correct:
  Order Service → Orders DB (PostgreSQL)
  User Service  → Users DB (PostgreSQL)
  Product Service → Products DB (MongoDB)
  (each service has exclusive access to its DB)

Incorrect:
  All services → Shared DB
  (anyone can read/write anyone else's tables)

Events (past tense — things that happened):
  CustomerRegistered → OrderPlaced → PaymentReceived
  → InventoryReserved → OrderShipped → OrderDelivered

Group events by the aggregate that owns them:
  Customer aggregate: CustomerRegistered, CustomerUpdated
  Order aggregate: OrderPlaced, OrderCancelled, OrderShipped
  Payment aggregate: PaymentReceived, PaymentRefunded
  Inventory aggregate: InventoryReserved, InventoryRestocked

Team structure often mirrors service structure:
  Checkout team → Cart Service, Order Service
  Catalog team → Product Service, Search Service
  Identity team → User Service, Auth Service
  Logistics team → Shipping Service, Inventory Service

Existing codebase analysis:
  /src
    /orders         ← touches: orders, order_items tables
    /products       ← touches: products, categories, images tables
    /users          ← touches: users, addresses, roles tables
    /payments       ← touches: payments, refunds tables (external gateway)
    /notifications  ← reads from orders, users — sends emails/SMS

Frontend Service
API Service
Database Service
Cache Service

UserProfileService
UserAddressService  ← do these need to be separate?
UserPreferencesService
UserRolesService
UserAuthService

┌─────────────────────────────────────────────────┐
│              API Gateway / BFF                   │
│  (auth validation, routing, rate limiting)       │
└──────┬──────────┬──────────┬──────────┬─────────┘
       │          │          │          │
  ┌────▼────┐ ┌───▼────┐ ┌───▼────┐ ┌──▼──────┐
  │  User   │ │Catalog │ │ Order  │ │ Payment │
  │ Service │ │Service │ │Service │ │ Service │
  │         │ │        │ │        │ │         │
  │  Users  │ │Products│ │ Orders │ │Payments │
  │  Auth   │ │Category│ │  Items │ │ Refunds │
  │ Profiles│ │Reviews │ │ Status │ │         │
  └─────────┘ └────────┘ └────────┘ └─────────┘
       │          │          │          │
  ┌────▼────┐ ┌───▼────┐ ┌───▼────┐ ┌──▼──────┐
  │Users DB │ │ Cat DB │ │ Ord DB │ │ Pay DB  │
  └─────────┘ └────────┘ └────────┘ └─────────┘

  ┌────────────────────┐  ┌──────────────────────┐
  │  Inventory Service │  │ Notification Service  │
  │  (stock levels,    │  │ (email, SMS, push —   │
  │   reservations)    │  │  reacts to events)    │
  └────────────────────┘  └──────────────────────┘

┌─────────────────────┐         ┌──────────────────────┐
│    Your Service     │         │   Legacy System /     │
│                     │──ACL──→ │   External API        │
│  Clean domain model │         │   (messy / alien      │
│                     │←──ACL── │    model)             │
└─────────────────────┘         └──────────────────────┘

// ACL: translate legacy payment gateway response into your domain model
public class StripePaymentAdapter : IPaymentGateway
{
    private readonly StripeClient _stripe;
    
    public async Task<PaymentResult> ChargeAsync(PaymentRequest request)
    {
        // Call external API in their format
        var charge = await _stripe.ChargeCreateAsync(new ChargeCreateOptions
        {
            Amount = (long)(request.Amount * 100),  // Stripe uses cents
            Currency = request.Currency.ToLower(),
            Source = request.PaymentToken,
        });
        
        // Translate to YOUR domain model — Stripe specifics don't leak in
        return new PaymentResult(
            TransactionId: charge.Id,
            Status: MapStatus(charge.Status),
            ProcessedAt: charge.Created
        );
    }
    
    private PaymentStatus MapStatus(string stripeStatus) => stripeStatus switch
    {
        "succeeded" => PaymentStatus.Successful,
        "pending"   => PaymentStatus.Pending,
        _           => PaymentStatus.Failed,
    };
}