event-driven-design
Design an event-driven flow — event catalog, choreography vs orchestration, saga + compensation, the outbox pattern for dual-writes, idempotent consumers, and CQRS read models.
- License 许可
- MIT
- 最近更新
- 2026-10-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- event-driven-design
- description
- Design an event-driven flow — event catalog, choreography vs orchestration, saga + compensation, the outbox pattern for dual-writes, idempotent consumers, and CQRS read models.
02 资源文件 1
- 参考文档routing.yaml480 B
03 SKILL.md 正文
event-driven-design
Events decouple services in space and time — and move every hard problem to delivery semantics. Design the failure paths first; the happy path is the easy 10%.
Mode: analytical — judgment inside a fixed frame. Keep the output shape; every verdict cites its evidence; unknowns are marked [TBD] or [VERIFY], never filled in.
When to use
- A business process spans services and you are choosing between synchronous calls and events.
- A write must update the database and publish a message and you are about to do both in one block (the dual-write trap).
- A workflow invokes
polymath-architecture:event-driven-design.
Not this when: the integration is two services and request/response is fine — that is integration-design. For the broker's partitioning/throughput tuning, that is polymath-streaming:streaming-design.
For event schema compatibility and versioning, polymath-streaming:event-schema-evolution; for worker/queue sizing, retries, and DLQs, polymath-scalability:async-workload-design.
Inputs
- The end-to-end process and its steps, with which service owns each.
- Consistency and ordering requirements; what "must never happen".
Procedure
- Catalog the events — past-tense, business-meaningful (
OrderPlaced,PaymentCaptured), not CRUD (OrderRowUpdated). Each has an owner, a schema, and a versioning rule. - Choreography vs orchestration: choreography (services react to events) for loose, simple flows; orchestration (a coordinator/saga drives steps) when the process is long, needs status, or has complex compensation. State the choice and why.
- Design the saga for any multi-step process that can fail midway: list each step and its compensating action (refund, release, cancel). There is no distributed rollback — only compensation.
- Kill the dual-write with the transactional outbox: write the event to an outbox table in the same DB transaction as the state change; a relay publishes it. Never write DB + broker in two separate commits.
- Make consumers idempotent: dedupe on event id / idempotency key; assume at-least-once delivery and out-of-order arrival. Define what a duplicate must do (nothing).
- Decide ordering: if order matters, partition by aggregate id so one entity's events are serialized; do not assume global ordering.
- (CQRS) if reads and writes diverge sharply, derive a read model from the events and state its staleness budget and rebuild path.
- Name the observability: a correlation id threaded through every event so a flow can be traced end to end.
Output
Event-driven design: order fulfillment
Events (past tense · owner · schema · version rule)
OrderPlaced Ordering orders.v3 additive-only; breaking → OrderPlaced.v4 dual-published 90 d
PaymentCaptured Payments payments.v2 additive-only
ShipmentCreated Fulfillment fulfil.v1 additive-only
Coordination: orchestration — a fulfillment saga (needs status + multi-step compensation)
Saga
step compensation
reserve stock release stock
capture payment refund payment
create shipment cancel shipment (cannot fail after carrier pickup → manual review queue)
Dual-write: transactional outbox in each service DB; Debezium relay → Kafka
Idempotency: consumers dedupe on event_id (processed_events table, 7 d)
Ordering: partition key = order_id (one order's events in order; no global order assumed)
Correlation: correlation_id on every event, propagated to traces
Inline by default; when a workflow step or the user wants it kept, write it to docs/architecture/<slug>-events.md (slug from the system or context name, lowercased, non-a-z0-9 runs → -).
Quality bar
- No dual-write survives — every publish is outbox-backed or explicitly justified.
- Every saga step has a compensating action or a documented "cannot fail here" reason.
- Consumers are idempotent and tolerate reordering; the dedup key is named.
- Events are business facts, not table change-logs.
04 同仓库更多 Skills
runbook
Write or refresh an operational runbook for an alert/symptom; structured as TL;DR + Pre-checks + Steps + Verification + Rollback + Escalation.
rfc
Draft a lightweight design RFC to docs/rfcs/<slug>.md; Summary, Motivation, Detailed design, Drawbacks, Alternatives, Unresolved questions. A proposal to debate, not a recorded decision (adr).
editorial-pass
Review and tighten prose in a Markdown artifact for a target tone (terse, formal, friendly) without dropping information; preserve quotations and load-bearing constraints.
architecture-review-facilitation
Run an architecture review as a process — entry criteria, reviewer checklist, decision log, and follow-up actions — pairing the design artifact with a red-team pass.
architecture-doc
Write a C4-style architecture document; System Context + Containers (+ Components when interesting) with mermaid diagrams. Describes structure, not a decision (adr) or proposal (rfc).
adr
Write an Architecture Decision Record (Michael Nygard format) to docs/adrs/NNNN-<slug>.md; frontmatter validated by the ADR artifact schema. Records a made decision, not a proposal to debate (rfc).