Microservices and Distributed Systems

Microservices architecture splits a system into independently deployable services, each owning a specific business capability. This approach trades the simplicity of a monolith for flexibility in scaling, deployment, and technology choice -- but only when the organizational and technical complexity is justified.

When to Use Microservices vs Monolith

There is no universal answer. The decision depends on team size, domain complexity, and operational maturity.

Factor Monolith Favored Microservices Favored

Team size Small team (fewer than 10 developers) Multiple autonomous teams that need independent release cycles

Domain complexity Simple or poorly understood domain Well-understood domain with clear bounded contexts

Deployment cadence Infrequent releases are acceptable Different parts of the system need to ship at different speeds

Scaling needs Uniform load across the application Specific components need independent scaling

Operational maturity Limited infrastructure automation Mature CI/CD, monitoring, and container orchestration

Data isolation Shared database is manageable Services need independent data stores and schemas

Start monolithic unless you have a clear reason not to. A well-structured modular monolith can be decomposed later. A premature microservices architecture adds distributed systems complexity without proportional benefit.

Service Decomposition Strategies

Deciding where to draw service boundaries is the hardest part. Get it wrong and you end up with a distributed monolith -- all the costs of distribution with none of the benefits.

By Business Capability

Align services to what the organization does rather than how the software is structured. Each service maps to a business function: order management, inventory, billing, notifications. Services change when the business capability they represent changes.

By Subdomain (Domain-Driven Design)

Use bounded contexts from domain-driven design to identify natural boundaries. Each bounded context has its own ubiquitous language and internal model. A "Customer" in the billing context may carry different attributes than a "Customer" in the shipping context -- and that is fine.

Strangler Fig Migration

When migrating from a monolith, extract services incrementally rather than doing a big-bang rewrite. Route traffic through a facade that delegates to the monolith by default but redirects specific capabilities to new services as they are built. Over time, the monolith shrinks until it can be retired entirely. An anti-corruption layer translates between old and new models during the transition.

Decomposition Heuristics

• High coupling between candidates -- keep them together, they are likely one service

• Different rates of change -- separate them, they will benefit from independent deployment

• Different scaling profiles -- separate them, they need different resource allocation

• Shared data -- if two candidates always read and write the same tables, splitting them creates unnecessary network chatter

Communication Patterns

Services must communicate, and the choice between synchronous and asynchronous interaction shapes the entire system's behavior.

Style Mechanism Strengths Weaknesses

Synchronous request-reply REST, gRPC, GraphQL Simple mental model, immediate response Temporal coupling, cascading failures

Asynchronous messaging Message queues (point-to-point) Decouples sender from receiver, buffering under load Added infrastructure, eventual consistency

Event-driven Event bus, pub/sub Loose coupling, multiple consumers possible Harder to debug, event ordering challenges

Rule of thumb: Use synchronous calls for queries that need an immediate answer. Use asynchronous messaging for commands and events where the sender does not need to wait for the result.

See Communication Patterns Reference for detailed coverage of API gateways, service discovery, gRPC, service mesh, and sidecar patterns.

Data Management in Distributed Systems

Each service should own its data. Shared databases create hidden coupling that defeats the purpose of service independence. This creates new challenges around consistency and cross-service transactions.

Key Principles

• Database per service -- each service has its own data store, accessed only through its API

• No direct database sharing -- if another service needs data, it requests it through the owning service's interface

• Eventual consistency is the norm -- strong consistency across services requires distributed transactions, which are fragile and slow

• Choose the right data store -- different services may use different database technologies based on their access patterns

Core Data Patterns

Pattern Purpose

CQRS Separate read and write models to optimize each independently

Event Sourcing Store state as a sequence of immutable events instead of overwriting current state

Saga Coordinate multi-service transactions using a sequence of local transactions with compensating actions

Outbox Guarantee reliable event publishing by writing events to a local table within the same database transaction

Eventual Consistency Accept that data across services will converge over time rather than being immediately consistent

See Data Patterns Reference for implementation details with multi-language examples.

Resilience Patterns

In a distributed system, failures are inevitable. Network partitions, slow dependencies, and overloaded services are normal operating conditions, not exceptional events. Resilience patterns prevent localized failures from cascading through the entire system.

Pattern Summary

Pattern Purpose

Circuit Breaker Stop calling a failing dependency; fail fast and give it time to recover

Bulkhead Isolate resource pools so one slow dependency cannot exhaust resources needed by others

Retry with Backoff Automatically retry transient failures with increasing delays and randomized jitter

Timeout Set upper bounds on how long to wait for a response; never block indefinitely

Fallback Provide degraded but functional behavior when a dependency is unavailable

Health Checks Expose liveness and readiness endpoints so orchestrators can route traffic and restart unhealthy instances

See Resilience Patterns Reference for implementation details with multi-language examples.

Reference Files

Reference Contents

Data Patterns CQRS, event sourcing, saga orchestration vs choreography, outbox pattern, eventual consistency with multi-language examples

Resilience Patterns Circuit breaker, bulkhead, retry with backoff, timeout, fallback, health checks with multi-language examples

Communication Patterns REST, gRPC, GraphQL federation, message queues, API gateway, service discovery, sidecar and service mesh with multi-language examples

Integration with Other Skills

Situation Recommended Skill

Domain modeling and bounded context design Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for clean architecture guidance

Testing microservices (contract tests, integration tests) Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for testing strategies

API design for service interfaces Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for API design principles

Performance tuning individual services Install knowledge-virtuoso from krzysztofsurdy/code-virtuoso for performance optimization