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
| Heuristic | Description |
|---|---|
| Single Responsibility | Each service does one thing well |
| Data ownership | Each service owns its data; no shared databases |
| Independent deployability | Changing one service does not require deploying another |
| Team alignment | One team can own and operate the service end-to-end |
| Bounded context boundary | Service boundaries align with DDD bounded contexts |
Inter-Service Communication
Synchronous Communication
| Pattern | Protocol | When to Use |
|---|---|---|
| Request/Response (REST) | HTTP/JSON | Simple CRUD, external APIs, broad tooling support |
| Request/Response (gRPC) | HTTP/2 + Protobuf | Internal service-to-service; high throughput, strong typing, streaming |
| GraphQL | HTTP/JSON | Client-driven queries; aggregating multiple services for a frontend |
Asynchronous Communication
| Pattern | Mechanism | When to Use |
|---|---|---|
| Event Notification | Message broker (topic/pub-sub) | Decoupled notification; consumers decide what to do |
| Event-Carried State Transfer | Message broker with payload | Reduce synchronous callbacks; consumer has needed data |
| Command Message | Message broker (queue) | Tell a specific service to do something |
| Async Request/Response | Correlation ID + reply queue | Need a response but don't want to block |
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
| Pattern | Description |
|---|---|
| Database per Service | Each service has its own database; no shared access |
| API Composition | Query multiple services and aggregate results |
| CQRS | Separate read and write models for different optimization (see dev/architecture/event-driven) |
| Event Sourcing | Store state changes as events; derive current state (see dev/architecture/event-driven) |
| Saga | Manage distributed transactions through compensating actions |
| Outbox Pattern | Reliably publish events by writing to a local outbox table within the same transaction |
Service Discovery
Services need to find each other in a dynamic environment where instances come and go.
| Approach | Examples | Mechanism |
|---|---|---|
| Client-side discovery | Netflix Eureka, Consul | Client queries registry, picks instance |
| Server-side discovery | AWS ALB, Kubernetes Services | Load balancer/proxy routes to available instance |
| DNS-based | Consul DNS, Kubernetes CoreDNS | Resolve service name to IP(s) via DNS |
In Kubernetes environments, server-side discovery via Services and DNS is the default and usually sufficient.
Resilience Patterns
| Pattern | Purpose |
|---|---|
| Circuit Breaker | Stop calling a failing service; fail fast and allow recovery |
| Retry with Backoff | Retry transient failures with exponential backoff and jitter |
| Bulkhead | Isolate failures to prevent cascading (separate thread pools / connections) |
| Timeout | Set explicit timeouts on all remote calls; never wait forever |
| Fallback | Provide degraded but functional response when a service is unavailable |
| Health Check | Expose liveness and readiness endpoints for orchestrators |
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
| Benefit | Cost |
|---|---|
| Independent deployability | Operational complexity (CI/CD per service, monitoring, tracing) |
| Technology heterogeneity | Polyglot overhead; harder to maintain standards |
| Team autonomy | Coordination overhead; contract management |
| Scalability per service | Network latency; serialization/deserialization cost |
| Fault isolation | Distributed failure modes (partial failures, network partitions) |
| Organizational alignment | Requires mature DevOps culture |
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.