Skip to content
build-3000
backend

Event-Driven Architecture

Producers announcing facts, consumers reacting independently - events instead of synchronous chains.

Before this: Background Jobs and Queues

Objective

Replace synchronous call chains with published domain events: producers emit facts once, independent consumers react at their own pace, failures isolate per consumer - governed by explicit event schemas.

Vocabulary

The words to use when directing your agent.

event
A recorded fact that something happened, e.g. expense.created - past tense, immutable.
producer
The component that publishes events when facts occur.
consumer
A component subscribed to event types and reacting to them.
broker
Infrastructure storing and delivering events between producers and consumers.
event schema
The declared shape and versioning rules of an event's payload.

Understand it

From choreography to contracts

Each consumer owns its reaction to an event type; the producer neither knows nor cares who listens. The discipline keeping this sane is the schema: event name, fields, types, version. Adding optional fields is safe evolution; removing or repurposing fields breaks every consumer quietly. Treat schemas like API contracts because they ARE one - just asynchronous.

Failure isolation and the fine print

Five consumers listening means five independent failure domains: the notifier crashing never blocks the reporter. The fine print: deliveries are at-least-once (consumers need dedupe awareness), ordering guarantees vary by infrastructure, and a dead broker stops EVERYTHING - which is why broker health joins your observability board the day events go live.

Core concepts

Announce, do not ask

Synchronous design: creating an expense directly calls the notifier, the reporter, the auditor - coupling their fates together. Event-driven design: the creator announces expense.created ONCE and moves on; interested parties subscribe and react independently. Slow or broken consumers no longer hold up creation - the defining win.

Events are immutable history

An event records that something HAPPENED - it does not get edited, only superseded by new events. Consumers evolve independently because the fact stays true even as interpretations multiply. Schema discipline keeps this honest: additive changes with new fields, never silent rewrites of meaning.

Examples

Two consumers, zero coupling

expense.created publishes; the audit-log consumer appends a line while the digest-builder updates aggregates. Add a fraud-detector next month: subscribe it, touch nothing else. The producer's code never changed - that is the decoupling paying off.

Schema drift horror story

Someone renames amount to value in an event without versioning. One consumer silently reads undefined for weeks, corrupting totals. The fix is boring and absolute: versions on schemas, additive-only changes within a version, consumers validating what they receive.

Common mistakes

Common mistake

Chaining events secretly - consumer B publishing C triggering D - until nothing can be traced.

Fix

Keep flows visible: a written map of which event triggers which consumers. Hidden orchestration is undebuggable orchestration.

Common mistake

Mutating event meaning in place - same name, different payload semantics.

Fix

Version events explicitly; new shape earns a new version. Consumers migrate on their own schedule.

Working with your AI agent

Insist on an event catalog before wiring: event names in past tense, schema per event with version, producer, current subscribers, delivery guarantees assumed. When your agent proposes a new event, the catalog entry comes FIRST - code follows contracts here more than anywhere else.

Build it

The module’s real project. Your agent builds; you direct and inspect.

Project: Event Wire

Wire the Ledger for events: domain events publish from core writes through a local broker, two independent consumers react (audit trail, digest builder), consumer failures isolate cleanly - all governed by versioned schemas and a visible event catalog.

Requirements

  • Core writes publish domain events (at minimum: created, updated, deleted) through one broker abstraction
  • Two independent consumers: audit-log appender and weekly-digest builder - each owning its failures
  • Killing one consumer never blocks the producer or the other consumer - demonstrated live
  • Versioned event schemas documented in a catalog; payloads validated on consume
  • Duplicate delivery handled: replaying an event produces no duplicated side effects
  • Broker restart-safe: unpublished/pending events survive process death

Context for your agent

Add event-driven architecture to my Expense Ledger. Start with the event catalog: names in past tense, versioned schemas, producers and subscribers listed. Use a boring durable local broker (database-backed is fine) behind one publish/subscribe interface. Implement audit-log and weekly-digest consumers as fully isolated processes. Prove failure isolation by killing one consumer mid-stream, prove duplicate safety by replaying events, and persist pending events across restarts. Show me the catalog before any wiring.

Verify it - twice

Check every item yourself first. Then hand your agent the prompt and compare verdicts.

Self-verified0/10
Functional
Architecture
Security
Testing
Production

Verification prompt - paste into your AI agent

Chaos-audit my Event Wire as a skeptical platform engineer who has been burned by hidden couplings. Attempt each probe and report results: (1) kill the audit consumer mid-stream - does the digest builder keep flowing and events queue for the dead one?, (2) replay the same event ten times - any duplicated side effects anywhere?, (3) deliver events slightly out of order - what breaks, honestly?, (4) diff my event catalog against actual wire traffic - any undocumented event or field? Grade each DoD item, then tell me which consumer would rot first in production and what early-warning signal I am missing.

Run this against “Event-Driven Architecture” after your own checklist pass. Where the agent and you disagree, investigate before moving on.

Review questions

Answer out loud. If you cannot, revisit before moving on.

  1. Contrast asking services directly versus announcing facts - what changed in your code?

  2. Why must event schemas version instead of mutating?

  3. Where did duplicate delivery try to bite you, and what absorbed it?

You can now

  • Decouple features with published events and independent consumers
  • Govern event shapes with versioned schemas
  • Isolate consumer failures so one sink never drags down the flow

Up next

Idempotency and Retries