--- name: event-driven-design description: When designing loosely coupled systems that react to state changes asynchronously. version: 2.0.0 category: architecture tags: [architecture, events, async] skill_type: architecture author: skiLLM license: MIT compatible_agents: [claude-code, cursor, copilot, codex] estimated_context_tokens: 2000 dangerous: false requires_review: true security_level: review-required dependencies: [] triggers: [event, async, decoupling, event bus, message broker] permissions: filesystem: { read: true, write: true } network: { outbound: true } shell: { execute: false } input_requirements: [microservices or monolithic architecture, message broker setup] output_contract: [immutable events, idempotent consumers, dead letter queues] failure_conditions: [event loss, duplicate processing, synchronous coupling] last_updated: 2026-05-15 --- # Event-Driven Design ## Purpose Tightly coupled systems break and scale poorly. Event-driven architectures decouple producers from consumers by using immutable, timestamped facts as the communication mechanism. This enables systems to evolve independently, scale horizontally, and handle distributed failures gracefully. ## When to use - De-coupling monolithic microservices - Implementing long-running asynchronous workflows (e.g., video processing, email sending) - Triggering multiple side-effects across different domains from a single action - Designing systems that need to replay history or audit changes ## When NOT to use - Simple synchronous request-response flows (don't add unnecessary complexity) - Real-time bidirectional communication (use WebSockets instead) - Workflows requiring immediate response to action ## Inputs required - Microservices or monolithic application with clear domain boundaries - Message broker infrastructure (Kafka, RabbitMQ, EventBridge, etc.) - Understanding of event sourcing concepts ## Workflow 1. **Define Events**: Identify state changes in the domain and model them as past-tense events (e.g., `OrderPlaced`, `UserRegistered`, `PaymentProcessed`) 2. **Design Event Payloads**: Include Event ID, Timestamp, Event Type, and minimal required data (avoid large nested objects) 3. **Publishing Mechanism**: Have the producer system emit the event to a Message Broker without caring who consumes it 4. **Idempotent Consumers**: Ensure consumer services can process the same event multiple times without adverse side effects 5. **Handle Failures**: Implement Dead Letter Queues (DLQ) for events that consumers repeatedly fail to process 6. **Track Processing**: Add idempotency keys or processed event IDs to detect duplicates 7. **Monitor**: Set up alerts for DLQ messages and processing delays ## Rules - MUST model events as immutable facts (past tense: `OrderPlaced` not `PlaceOrder`) - MUST NEVER modify or delete events once emitted (audit trail requirement) - MUST make consumers idempotent (same event processed multiple times = same outcome) - MUST avoid deeply nested, rapidly changing entity graphs in payloads - MUST include Event ID, Timestamp, Event Type in all events - MUST implement Dead Letter Queues for failed events - MUST NOT use synchronous HTTP calls as part of event workflows ## Anti-patterns - **Commands as Events**: Naming events like actions (`SendEmailEvent`) rather than facts (`UserCreated`) - **Distributed Monolith**: Systems requiring synchronous HTTP calls *in response* to an event before completing their workflow - **Huge Event Payloads**: Sending entire entity graphs; include only IDs and essential context - **No Idempotency**: Processing events without tracking duplicate processing - **Synchronous Dependencies**: Event handler blocks waiting for another service response - **Event Loss**: Not persisting events to broker; memory-only event storage ## Failure conditions - Events cannot be replayed (no persistence) - Consumers not idempotent (duplicates cause data corruption) - No Dead Letter Queue for failed events - Synchronous dependencies between event producers and consumers - Event payloads change format without versioning support ## Validation checklist - [ ] All events named as past-tense facts (not commands) - [ ] Events are immutable after emission - [ ] Event payloads include ID, Timestamp, Type - [ ] Consumers are idempotent (can process same event multiple times safely) - [ ] Dead Letter Queue configured and monitored - [ ] No synchronous HTTP dependencies in event handlers - [ ] Event versioning strategy defined - [ ] Idempotency keys tracked (to detect duplicates) - [ ] Monitoring/alerting on DLQ messages - [ ] Event processing latency within SLA ## Output format - **Event schema**: Event ID, Timestamp, Type, Payload (minimal data) - **Payload format**: JSON with primitive types, IDs, not full objects - **Consumer pattern**: Read event, validate idempotency key, process, mark as processed - **Infrastructure**: Message broker setup with persistence and DLQ - **Monitoring**: Dashboards for event processing latency and DLQ depth ## Security considerations - Event payloads MUST NOT contain credentials or PII - Access control MUST be enforced at consumer (not all services can listen to all events) - Event encryption MUST be used for sensitive domains - Audit logging MUST track who published and consumed events - Dead Letter Queues MUST be monitored (may contain sensitive data) ## Agent execution notes - Agent MAY: Define events, create event handlers, implement idempotency, set up DLQ - Agent MUST NEVER: Use commands instead of events, create synchronous dependencies, lose events - Agent MUST ASK: Before adding new event types, before changing event schema, before removing DLQ - Agent MUST VALIDATE: Events are facts not commands, consumers are idempotent, DLQ configured ## Example **❌ Anti-pattern (Commands as events, synchronous coupling, no idempotency):** ```javascript // WRONG: Command not event publishEvent('SendEmail', { userId, subject }); // WRONG: Synchronous dependency async function handleOrderPlaced(event) { const order = await orderService.fetch(event.orderId); // Blocks on external service await emailService.send(order.email); // Fails if service is down } // WRONG: No idempotency tracking - processes duplicate async function handleUserCreated(event) { await database.createUser(event); // Processes same event twice = duplicate user } ``` **✅ Correct pattern (Events, async, idempotent):** ```javascript // CORRECT: Past-tense event with minimal payload publishEvent({ type: 'UserCreated', id: uuid(), timestamp: new Date(), payload: { userId: event.userId, email: event.email } }); // CORRECT: Asynchronous, idempotent consumer async function handleUserCreated(event) { // 1. Track processed events (idempotency) const alreadyProcessed = await cache.get(`processed:${event.id}`); if (alreadyProcessed) return; // Skip duplicate // 2. Process without waiting for external services await emailQueue.enqueue({ email: event.payload.email, template: 'welcome' }); // 3. Mark as processed await cache.set(`processed:${event.id}`, true, { ttl: 86400 }); } // 4. Dead Letter Queue for failed events async function handleFailedEvent(event, error) { await dlq.store({ originalEvent: event, error: error.message, timestamp: new Date(), retryCount: 0 }); } ```