Microservices Architecture

Overview

Microservices architecture structures an application as a collection of loosely coupled, independently deployable services, each organized around a business capability. Each service owns its data, runs in its own process, and communicates over the network.

The canonical reference is Sam Newman's Building Microservices (O'Reilly, 2nd edition 2021), supplemented by Monolith to Microservices (Newman, 2019) for migration strategies.

The First Rule of Microservices: Don't start with microservices. Start with a monolith, understand your domain, and decompose when you have evidence that the benefits outweigh the operational costs. (See dev/architecture/monoliths for the monolith-first approach.)

Service Decomposition

By Business Capability

Align services to what the business does (e.g., Order Management, Inventory, Payments). This creates stable boundaries because business capabilities change less frequently than technical layers.

By Subdomain (DDD-Aligned)

Use Domain-Driven Design bounded contexts as service boundaries (see dev/architecture/domain-driven-design):

• Core subdomains -- Your competitive advantage; build custom services.
• Supporting subdomains -- Necessary but not differentiating; simpler services or libraries.
• Generic subdomains -- Commodity; buy or use off-the-shelf (auth, email, payments).

Decomposition Heuristics

Inter-Service Communication

Synchronous Communication

Asynchronous Communication

Rule of thumb: Prefer asynchronous communication for inter-service calls. Use synchronous only when a real-time response is required (e.g., user-facing request/response).

Communication Anti-Patterns

• Distributed monolith -- Services are "microservices" in name only; they deploy together, share databases, or cannot function independently.
• Chatty interfaces -- Excessive synchronous calls between services creating latency chains.
• Shared database -- Multiple services reading/writing the same tables destroys independent deployability.

API Gateway

An API gateway sits between external clients and internal services, providing:

• Request routing -- Routes client requests to the appropriate microservice
• Protocol translation -- External REST to internal gRPC, for example
• Authentication/Authorization -- Centralized security enforcement
• Rate limiting and throttling -- Protect services from traffic spikes
• Response aggregation -- Combine responses from multiple services for a single client call

Common implementations: Kong, AWS API Gateway, Azure API Management, Envoy, NGINX, Ocelot (.NET).

Service Mesh

A service mesh handles service-to-service networking concerns transparently via sidecar proxies:

┌──────────────────────┐    ┌──────────────────────┐
│  Service A           │    │  Service B           │
│  ┌────────────────┐  │    │  ┌────────────────┐  │
│  │ App Container  │  │    │  │ App Container  │  │
│  └───────┬────────┘  │    │  └───────▲────────┘  │
│          │           │    │          │           │
│  ┌───────▼────────┐  │    │  ┌───────┴────────┐  │
│  │ Sidecar Proxy  │──┼────┼─▶│ Sidecar Proxy  │  │
│  │ (Envoy)        │  │    │  │ (Envoy)        │  │
│  └────────────────┘  │    │  └────────────────┘  │
└──────────────────────┘    └──────────────────────┘
         Control Plane (Istio / Linkerd)

Capabilities: Mutual TLS, traffic management, retries, circuit breaking, observability (distributed tracing, metrics), canary deployments.

Implementations: Istio, Linkerd, Consul Connect, AWS App Mesh.

Saga Pattern -- Distributed Transactions

Since each microservice owns its data, distributed transactions (2PC) are impractical. The saga pattern manages data consistency across services through a sequence of local transactions with compensating actions.

Choreography (Event-Driven)

Each service publishes events that trigger the next step. No central coordinator.

Order Service ──(OrderCreated)──▶ Payment Service
Payment Service ──(PaymentProcessed)──▶ Inventory Service
Inventory Service ──(InventoryReserved)──▶ Shipping Service

On failure:
Inventory Service ──(ReservationFailed)──▶ Payment Service (refund)
Payment Service ──(RefundProcessed)──▶ Order Service (cancel)

Pros: Simple, decoupled, no single point of failure. Cons: Hard to understand the overall flow; debugging is difficult; risk of cyclic dependencies.

Orchestration (Central Coordinator)

A saga orchestrator (process manager) coordinates the steps explicitly.

┌─────────────────┐
│ Saga Orchestrator│
│ (Order Saga)     │
└────┬───┬───┬────┘
     │   │   │
     ▼   ▼   ▼
  Payment  Inventory  Shipping
  Service  Service    Service

Pros: Clear flow, easier to understand and debug, centralized compensation logic. Cons: Orchestrator is a coupling point; risk of becoming a "god service."

Guidance: Use choreography for simple sagas (2-3 steps). Use orchestration for complex flows (4+ steps or complex compensation).

Distributed Data Management

Service Discovery

Services need to find each other in a dynamic environment where instances come and go.

In Kubernetes environments, server-side discovery via Services and DNS is the default and usually sufficient.

Resilience Patterns

When NOT to Use Microservices

Microservices introduce significant operational complexity. Do not use them when:

• Your team is small (< 8-10 developers) -- The overhead exceeds the benefit.
• Your domain is not well understood -- You will draw the wrong boundaries and create a distributed monolith.
• You lack operational maturity -- You need CI/CD, monitoring, distributed tracing, container orchestration, and on-call practices before microservices are viable.
• Latency is critical -- Every network hop adds latency; monoliths have zero network overhead for internal calls.
• Strong consistency is required everywhere -- Microservices embrace eventual consistency; if your domain requires ACID transactions across multiple entities, a monolith may be simpler.
• You are building an MVP or prototype -- Speed of iteration matters more than scalability at this stage.

Tradeoffs Summary

Best Practices

• Design for failure from day one: circuit breakers, retries, timeouts, bulkheads.
• Own your data: one database per service, no shared database access.
• Make inter-service communication observable: distributed tracing (OpenTelemetry), centralized logging, metrics.
• Use consumer-driven contract testing (Pact, Spring Cloud Contract) to prevent breaking changes.
• Prefer asynchronous communication; use synchronous calls only when necessary.
• Keep services small enough to be owned by a single team, but large enough to justify the operational overhead.
• Deploy independently, test independently, fail independently.