Event-Driven Architecture Design Template

Use EDA when services need to react to the same business event independently, when you need to decouple services for independent scaling or deployment, or when you need to buffer spikes in traffic. If one service simply needs data from another with a direct request/response, a synchronous [REST API](/glossary/rest-api) call is simpler and easier to debug. Many systems use both: synchronous for queries and event-driven for state changes.

Use backward-compatible changes only: add new optional fields, never remove or rename existing fields. Include a `version` field in your event envelope. Consumers should ignore fields they do not recognize. If you need a breaking change, publish a new event type (e.g., `order.created.v2`) and run both versions in parallel during migration.

Event-driven architecture is a communication pattern where services exchange events. Event sourcing is a data storage pattern where the system stores every state change as an immutable event, and the current state is derived by replaying the event log. You can use event-driven architecture without event sourcing, and vice versa. They are complementary but independent concepts.

Distributed tracing is essential. Every event should carry a `correlationId` that traces the full business transaction and a `traceId` for infrastructure-level tracing. Use a centralized logging platform (Datadog, Elasticsearch, Honeycomb) where you can search by `correlationId` to see every event and consumer action in a single transaction. The [observability glossary entry](/glossary/observability) covers monitoring best practices in more detail. ---