distributed-systems-patterns
/distributed-systems-patterns
Use when designing or reviewing multi-service, message-driven, or eventually consistent systems. Covers service boundaries, consistency tradeoffs, event workflows, outbox and inbox patterns, sagas, ordering, and idempotency.
- Author
- peterbamuhigire ↗
- Repository
- chwezi-dev-engine ↗
- Licence
- MIT
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 2
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Use when designing or reviewing multi-service, message-driven, or eventually consistent systems. Covers service boundaries, consistency tradeoffs, event workflows, outbox and inbox patterns, sagas, ordering, and idempotency.
Original author description
Use when designing or reviewing multi-service, message-driven, or eventually consistent systems. Covers service boundaries, consistency tradeoffs, event workflows, outbox and inbox patterns, sagas, ordering, and idempotency.
How it works
- Use When
- Do Not Use When
- Required Inputs
- Workflow
- Quality Standards
- Outputs
- Evidence Produced
- References
- Load Order
- Decision Workflow
SKILL.md preview
--- name: distributed-systems-patterns description: Use when designing or reviewing multi-service, message-driven, or eventually consistent systems. Covers service boundaries, consistency tradeoffs, event workflows, outbox and inbox patterns, sagas, ordering, and idempotency. metadata: portable: true compatible_with: - claude-code - codex --- # Distributed Systems Patterns Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178. <!-- dual-compat-start --> ## Use When - Use when designing or reviewing multi-service, message-driven, or eventually consistent systems. Covers service boundaries, consistency tradeoffs, event workflows, outbox and inbox patterns, sagas, ordering, and idempotency. ## Do Not Use When - The change is a single-process transaction with no remote dependency, asynchronous delivery, or independently failing component. - The task is mainly service decomposition or API shape; use `system-architecture-design` or `api-design-first` and return here for cross-boundary failure semantics. ## Required Inputs | Input | Required | Why it matters | |---|---|---| | Workflow steps and system boundaries | yes | Identifies where atomicity ends and partial failure begins | | Delivery, ordering, and consistency requirements | yes | Determines idempotency, sequencing, and reconciliation choices | | Failure and recovery expectations | yes | Sets timeout, retry, compensation, and operator intervention rules | | Throughput and latency constraints | conditional | Tests whether the coordination pattern is viable | ## Workflow Draw state transitions and ownership boundaries, enumerate failure windows, choose consistency and coordination patterns, define idempotency and recovery, then verify duplicate, reordered, delayed, and partially applied events. ## Quality Standards Every remote interaction has a timeout and failure policy. Every retried side effect has an idempotency rule. Consistency claims state their scope, and recovery does not assume exactly-once delivery. ## Outputs | Output | Consumer | Acceptance condition | |---|---|---| | Distributed workflow model | Architecture and implementation teams | Shows state ownership, message boundaries, consistency guarantees, and failure windows | | Failure-handling contract | Service owners | Defines timeout, retry, deduplication, compensation, replay, and reconciliation behavior | | Verification scenarios | Test and operations teams | Cover duplicates, reordering, concurrency, dependency outage, and partial completion | ## Evidence Produced | Category | Artifact | Format | Example | |----------|----------|--------|---------| | Operability | Service consistency and idempotency note | Markdown doc covering chosen consistency model, idempotency keys, and saga sequences | `docs/dist/consistency-note-checkout.md` | | Operability | Failure-mode catalogue | Markdown doc listing partition, retry, and replay failure modes with mitigations | `docs/dist/failure-modes-checkout.md` | ## References - Use the `references/` directory for deep detail after reading the core workflow below. - Load `references/event-driven-architecture.md` for event choreography, event contracts, brokers, and asynchronous workflow design. - Load `references/realtime-systems.md` for WebSocket, SSE, pub/sub, and realtime delivery concerns. <!-- dual-compat-end --> Use this skill when a design crosses process, service, queue, or region boundaries. The goal is to keep distributed complexity deliberate and bounded rather than accidental. ## Load Order 1. Load `world-class-engineering`. 2. Load `system-architecture-design` first for the overall shape. 3. Load this skill only when the system genuinely needs multiple services, asynchronous workflows, or weakly consistent boundaries. ## Decision Workflow ### 1. Justify Distribution State why distribution is necessary: - team ownership and release independence - scaling asymmetry - fault isolation - compliance or tenancy isolation - long-running or bursty workflows If none of these are strong, prefer a modular monolith. ### 2. Define Boundaries and Contracts For each service or asynchronous component, define: - owned data - API or event contracts - consistency expectation - failure effect on upstream and downstream flows - observability and ownership requirements ### 3. Choose Interaction Patterns Use: - synchronous calls when the caller needs immediate confirmation - messaging when work is slow, bursty, or naturally eventual - outbox and inbox patterns when reliability across boundaries matters - sagas or compensations when one business workflow spans multiple durable states ### 4. Design Consistency and Recovery Make explicit: - source of truth - ordering requirements - deduplication strategy - reconciliation path - timeout and retry policy - compensation or manual repair path ### 5. Prove the Design Before calling it production-ready, provide: - consistency model - failure-mode examples - idempotency and replay notes - contract evolution rules - operational signals for stuck or divergent workflows ## Non-Negotiable Standards ### Service Boundaries - Each service owns its data and rules. - Do not share databases across services as a convenience. - Keep contracts narrow and versionable. - Avoid chatty request chains on critical paths. ### Messaging - Assume at-least-once delivery unless proven otherwise. - Design consumers to be idempotent and replay-safe. - Define ordering needs explicitly; unordered by default is safer to assume. - Include correlation IDs and causation metadata. ### Consistency - Strong consistency has operational cost; use it where business correctness needs it. - Eventual consistency requires visible user and operator handling. - If divergence is possible, define reconciliation before shipping. ### Sagas and Compensation - Use compensation when the workflow spans multiple irreversible boundaries. - Compensation must be explicit, auditable, and tested. - Never describe a workflow as atomic if it crosses systems that cannot commit atomically. ## Deliverables For distributed-system work, produce: - service and ownership map - contract list - consistency decision table - event and retry flow notes - reconciliation or compensation plan - stuck-workflow and replay detection signals ## Review Checklist - [ ] Distribution is justified by real constraints. - [ ] Data ownership is explicit and not undermined by shared persistence shortcuts. - [ ] Idempotency and replay behavior are defined. - [ ] Ordering assumptions are explicit. - [ ] Consistency and compensation strategy match business risk. - [ ] Operational detection exists for stuck, duplicated, or divergent workflows. ## References - [references/consistency-decision-matrix.md](references/consistency-decision-matrix.md): How to choose synchronous, asynchronous, strong, or eventual consistency. - [references/messaging-checklist.md](references/messaging-checklist.md): Event, queue, and saga review prompts. ## Capability contract Model boundaries, messages, and failure semantics by default. Do not provision brokers, replay events, or mutate production state unless explicitly authorised. ## Degraded mode If topology or failure evidence is unavailable, return a read-only pattern comparison and assumptions register; withhold recommendations dependent on unknown delivery guarantees. ## Domain Anti-Patterns - Assuming exactly-once delivery. Fix: define idempotency and deduplication. - Sharing one database across autonomous services. Fix: assign data ownership. - Publishing before the state change commits. Fix: use a transactional outbox. - Retrying non-idempotent commands blindly. Fix: add keys and retry limits. - Omitting poison-message handling. Fix: define dead-letter and replay controls.
Files in this package (5)
- SKILL.md 8 KB
- references/consistency-decision-matrix.md 1 KB
- references/event-driven-architecture.md 18 KB
- references/messaging-checklist.md 1 KB
- references/realtime-systems.md 13 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · peterbamuhigire/chwezi-dev-engine | 100 | MIT |
| ajyadav013/claude-kit | 100 | MIT |
| ajyadav013/claude-kit | 100 | MIT |
Database snapshot: 13.11.2026 · package version 8d8a3f6a4b3c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100microservices-patterns
Decompose systems into microservices and apply canonical distributed-systems patterns. Use this skill whenever the user wants to split a monolith into services, design service boundaries, choose between microservices and a modular monolith, implement sagas or the outbox pattern,… - 90rs-domain-distributed
Use when a design spans processes or machines — retries, timeouts, idempotency, outbox/inbox, sagas, distributed transactions, consensus, leader election, distributed locks, clocks and ordering, delivery guarantees, partitions, deadlines, load shedding, deterministic simulation… - 90event-driven-architecture
Guides event-driven systems—pub/sub, point-to-point, event sourcing, CQRS, schema versioning (Avro/JSON Schema), ordering, partitioning, delivery guarantees, idempotency, exactly-once tradeoffs, transactional outbox/inbox, choreography vs orchestration, sagas, dead-letter… - 100microservices
Microservices and distributed systems patterns: service boundaries, sagas, CQRS, resilience, and monolith trade-offs. Use to decompose a monolith or design service communication. - 100masstransit
Use when building message-based distributed systems with MassTransit for pub/sub, request/response, sagas, and outbox patterns in .NET. USE FOR: distributed messaging, pub/sub consumers, request/response over message brokers, saga orchestration, outbox pattern, RabbitMQ/Azure… - 100event-driven
Event-driven architecture patterns and best practices. Covers Saga, Outbox, CQRS, Event Sourcing, and messaging patterns for distributed systems. USE WHEN: user mentions "event-driven", "Saga", "Outbox pattern", "CQRS", "Event Sourcing", "distributed transactions", "eventual…