microservices

When this skill is activated, always start your first response with the 🧢 emoji.

Microservices Architecture

Microservices is an architectural style that structures an application as a collection of small, independently deployable services, each owning its domain and data. Each service runs in its own process and communicates through lightweight mechanisms like HTTP/gRPC or async messaging. The style enables teams to develop, deploy, and scale services independently, reducing coupling and increasing resilience. It trades the simplicity of a monolith for the operational complexity of distributed systems - that trade-off must be made deliberately.

When to Use This Skill

Trigger on these scenarios:

• Decomposing a monolith into services (strangler fig, domain extraction)
• Designing inter-service communication (sync vs async, REST vs gRPC vs events)
• Implementing distributed transaction patterns (saga, two-phase commit alternatives)
• Applying CQRS or event sourcing to a service or domain
• Designing an API gateway layer (routing, auth, rate limiting, aggregation)
• Setting up a service mesh (Istio, Linkerd, Consul Connect)
• Implementing resilience patterns (circuit breaker, bulkhead, retry, timeout)
• Defining service boundaries using Domain-Driven Design (bounded contexts)

Do NOT trigger for:

• Simple CRUD apps or early-stage products with a single team - a monolith is the right choice
• Tasks that are purely about infrastructure provisioning without architectural decisions

Key Principles

1. Single responsibility per service - Each service owns exactly one bounded context. If you need to join data across services in the database layer, your boundaries are wrong.
2. Smart endpoints, dumb pipes - Business logic lives in services, not in the message broker or API gateway. Pipes carry data; they do not transform it.
3. Design for failure - Every network call can fail. Services must handle partial failures gracefully using timeouts, retries with backoff, circuit breakers, and fallbacks.
4. Decentralize data ownership - Each service owns its own database. No shared databases. Cross-service queries are done through APIs or events, never direct DB access.
5. Automate everything - Microservices require CI/CD pipelines, automated testing, health checks, and observability from day one. Without automation, operational overhead becomes unmanageable.

Core Concepts

Service Boundaries

Define boundaries using Domain-Driven Design bounded contexts. A bounded context is a logical boundary within which a domain model is consistent. Map organizational structure (Conway's Law) to service boundaries. Services should be loosely coupled (change one without changing others) and highly cohesive (related behavior stays together).

Communication Patterns

| Style | Protocol | Use When | |-------|----------|----------| | Synchronous | REST, gRPC | Immediate response needed, simple request-response | | Asynchronous | Kafka, RabbitMQ, SQS | Decoupling, fan-out, event-driven workflows | | Streaming | gRPC streams, SSE | Real-time data, large payloads, subscriptions |

Prefer async for cross-domain operations. Use sync only when the caller truly cannot proceed without the response.

Data Consistency

Distributed systems cannot guarantee both consistency and availability simultaneously (CAP theorem). Embrace eventual consistency for cross-service data. Use the saga pattern for distributed transactions. Never use two-phase commit across service boundaries - it creates tight coupling and is a single point of failure.

Service Discovery

Services find each other through a registry (Consul, Eureka) or via DNS with Kubernetes. Client-side discovery puts load-balancing logic in the client. Server-side discovery delegates to a load balancer. In Kubernetes, use DNS-based discovery with Services objects.

Observability

The three pillars: logs (structured JSON, correlation IDs), metrics (RED: Rate, Errors, Duration), traces (distributed tracing with OpenTelemetry). Every service must emit all three from day one. Correlation IDs must propagate across all service calls.

Common Tasks

Decompose a Monolith

Use the strangler fig pattern: incrementally extract functionality without a big-bang rewrite.

1. Identify bounded contexts in the monolith using event storming or domain modeling
2. Stand up an API gateway in front of the monolith
3. Extract the least-coupled domain first as a new service
4. Route traffic for that domain through the gateway to the new service
5. Repeat domain by domain, shrinking the monolith over time
6. Decommission the monolith when empty

Key rule: never split by technical layer (all controllers, all DAOs). Split by business capability.

Implement Saga Pattern

Use sagas to manage distributed transactions without two-phase commit. Two variants:

Choreography saga (event-driven, no central coordinator):

• Each service listens for domain events and emits its own events
• Compensating transactions roll back on failure
• Good for simple flows; hard to trace complex ones

Orchestration saga (central coordinator drives the flow):

• A saga orchestrator sends commands to each participant and tracks state
• On failure, the orchestrator issues compensating commands in reverse order
• Prefer for complex multi-step flows - easier to reason about and observe

Compensating transactions must be idempotent. Design them upfront, not as an afterthought.

Design API Gateway

The API gateway is the single entry point for external clients. Responsibilities:

• Routing - map external URLs to internal service endpoints
• Auth/AuthZ - validate JWTs or API keys before forwarding
• Rate limiting - protect services from abuse
• Request aggregation - combine multiple service calls into one response (BFF pattern)
• Protocol translation - REST externally, gRPC internally

Do NOT put business logic in the gateway. Keep it thin. Use the Backend for Frontend (BFF) pattern when different clients (mobile, web) need different response shapes.

Implement Circuit Breaker

The circuit breaker pattern prevents cascading failures when a downstream service is unhealthy.

States: Closed (requests flow normally) -> Open (fast-fail, no requests sent) -> Half-Open (probe with limited requests).

Implementation checklist:

• Set a failure threshold (e.g., 50% error rate over 10 requests)
• Set a timeout for the open state before transitioning to half-open
• Log all state transitions as events
• Expose circuit state in health endpoints
• Pair with a fallback (cached response, default value, or degraded mode)

Libraries: Resilience4j (Java), Polly (.NET), opossum (Node.js), circuitbreaker (Go).

Choose Communication Pattern

| Decision | Recommendation | |----------|---------------| | Need immediate response | REST or gRPC (sync) | | Decoupling producer from consumer | Async messaging (Kafka, SQS) | | High-throughput, ordered events | Kafka | | Simple task queuing | RabbitMQ or SQS | | Internal service-to-service (low latency) | gRPC (contract-first, strongly typed) | | Public-facing API | REST (broad tooling, human readable) | | Fan-out to multiple consumers | Pub/sub (Kafka topics, SNS) |

Never mix sync and async in a way that hides latency - if you call an async system synchronously (poll or long-poll), make that explicit.

Implement CQRS

Command Query Responsibility Segregation separates read and write models.

• Write side: accepts commands, validates invariants, persists to write store, emits domain events
• Read side: subscribes to domain events, builds denormalized read models optimized for queries

Steps to implement:

1. Separate command handlers from query handlers at the code level first (logical CQRS)
2. Introduce separate read and write datastores when read/write performance profiles diverge
3. Populate the read store by consuming domain events