Event-Driven Diagrams and Concept Maps

This appendix collects the main visual shapes that appear throughout the guide and turns them into one review page. The goal is not to teach Mermaid syntax. The goal is to help you recognize recurring event-driven patterns quickly by their flow shape, dependency shape, and recovery shape.

Use this appendix when the prose starts to feel abstract. A good diagram often answers one of three questions faster than text:

• what flows where
• who owns the next action
• where failure, replay, or contract risk enters the system

One Fact, Many Reactions

The publish/subscribe fan-out shape is the first visual pattern to recognize. One fact leaves the producer once and several independent consumers react to it.

    flowchart LR
	    A["Producer publishes domain event"] --> B["Topic or subject"]
	    B --> C["Consumer A"]
	    B --> D["Consumer B"]
	    B --> E["Consumer C"]

What to notice:

• the producer publishes once
• each consumer gets the same fact independently
• this is a good fit when consumers do not need to coordinate with each other to process the event

The main warning sign here is uncontrolled fan-out. If many consumers subscribe casually, one useful event can become a platform-wide coupling surface.

One Work Item, One Worker

The queue or competing-consumer shape is different. The system is not broadcasting one fact to everyone. It is distributing work so one available worker handles one work item.

    flowchart LR
	    A["Queue"] --> B["Worker 1"]
	    A --> C["Worker 2"]
	    A --> D["Worker 3"]
	    B --> E["One worker completes one task instance"]
	    C --> E
	    D --> E

What to notice:

• this is a work-distribution pattern, not a fact fan-out pattern
• throughput improves by adding workers
• idempotency still matters because retries and redelivery can happen even in queue-driven systems

If a design calls this publish/subscribe when only one worker should actually act, the queue shape is usually the better mental model.

Durable Stream and Replay

The stream-log shape is central to event systems that care about retention, replay, analytics, or projection rebuild. Instead of treating messages as transient handoffs, the architecture treats the event sequence as retained history.

    flowchart TD
	    A["Producer"] --> B["Durable stream"]
	    B --> C["Live consumer"]
	    B --> D["Projection builder"]
	    B --> E["Replay or backfill path"]

What to notice:

• the stream supports both live processing and historical reuse
• replay is a built-in capability of the shape, not an afterthought
• once history exists, schema evolution and side-effect control become much more important

This is the diagram to remember whenever the guide talks about retained history, backfills, and reconstructable derived state.

Outbox and Reliable Publication

The outbox pattern is one of the most practical visual patterns in the whole guide because it solves a very common failure gap: state committed locally but event publication not safely aligned.

    sequenceDiagram
	    participant App as Service
	    participant DB as Local Database
	    participant Relay as Outbox Relay
	    participant Bus as Broker
	
	    App->>DB: Commit business state and outbox row
	    Relay->>DB: Read pending outbox rows
	    Relay->>Bus: Publish event
	    Relay->>DB: Mark outbox row sent

What to notice:

• business state and pending publication are committed together
• publication may still happen later, but it has a durable source
• the relay itself can retry without guessing whether the business state exists

This is the visual antidote to “just publish after commit and hope the broker call works.”

Choreography and Orchestration

Workflow diagrams are where many event systems become hard to reason about. The key visual distinction is where the process logic lives.

Choreography looks like this:

    flowchart LR
	    A["order.placed"] --> B["Inventory reacts"]
	    B --> C["inventory.reserved"]
	    C --> D["Payment reacts"]
	    D --> E["payment.authorized"]
	    E --> F["Shipping reacts"]

Orchestration looks like this:

    flowchart TD
	    A["Orchestrator"] --> B["Reserve inventory"]
	    B --> A
	    A --> C["Authorize payment"]
	    C --> A
	    A --> D["Create shipment"]

What to notice:

• choreography distributes process progress across services
• orchestration keeps the workflow visible in one control component
• both can be valid, but the risk profile is different

If the process is hard to explain from the first diagram, that is often a clue that hidden choreography is becoming a real problem.

Replay and Recovery Pipeline

This is the operations diagram to keep in mind during incidents. Replay is useful, but it is not automatically safe. The right question is always what kind of output the replay will touch.

    flowchart TD
	    A["Historical events"] --> B{"Replay target"}
	    B -->|Projection rebuild| C["Recompute derived state"]
	    B -->|External side-effect consumer| D["High-risk replay path"]
	    C --> E["Validate rebuilt output"]
	    D --> F["Require isolation, dry run, or alternative recovery"]

What to notice:

• replay is safe more often for internal derived views than for outward side effects
• the difference between those two targets matters more than the replay tool itself
• this is the diagram to remember when deciding whether to rebuild, quarantine, or selectively replay

Schema Evolution and Compatibility

Schema diagrams matter because event contracts are not private code. A change at the producer boundary can affect several types of consumers and several versions of retained history.

    flowchart TD
	    A["Producer changes schema"] --> B{"Backward compatible?"}
	    B -->|Yes| C["Older consumers still parse new events"]
	    B -->|No| D["Versioned migration or parallel contract"]
	    A --> E["Retained history still exists"]
	    E --> F{"Can newer consumers read older events?"}
	    F -->|No| G["Replay and rebuild risk"]

What to notice:

• compatibility is not only about today’s live traffic
• retained history makes forward and replay compatibility important too
• this is the visual summary of why schema change should be treated as a platform contract decision

A One-Page Concept Map

When you want the whole guide in one picture, this is the simplest concept map to review.

    flowchart TD
	    A["Business fact"] --> B["Event contract"]
	    B --> C["Transport shape"]
	    C --> D["Consumer behavior"]
	    D --> E["Projection or side effect"]
	    C --> F["Replay and retention"]
	    B --> G["Schema governance"]
	    D --> H["Idempotency and recovery"]

What to notice:

• meaning comes first, then transport
• consumers are where business effect and reliability concerns meet
• replay, governance, and idempotency are not optional edge topics; they are structurally connected to the event model

How to Study with These Diagrams

Use the fan-out and queue diagrams when deciding whether the system is distributing facts or tasks. Use the stream and outbox diagrams when reasoning about retention and reliable publication. Use the choreography and orchestration diagrams when a workflow feels hard to trace. Use the replay and schema diagrams when recovery or contract change becomes risky. Use the final concept map when you need to reconnect event meaning, transport, and operations in one mental picture.