Skip to main content

Domain Events

Table of Contents​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Component Details
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendix

Introduction​

This document focuses on domain events in the Sparrow framework, systematically explaining event modeling, event creation, publishing, subscription, event-driven architecture, event sourcing, and CQRS patterns. The target audience is architects and senior developers who need to design and implement event-driven systems and domain event processing flows.

Project Structure​

Domain event-related code is distributed across multiple modules, including the entity layer (event definition and base implementation), use case layer (event store interface), infrastructure layer (event storage and message bus), and interface adapter layer (HTTP endpoints).

  • DomainEvent Interface: Defines the core metadata and behavior of domain events, including event ID, type, creation time, aggregate ID, aggregate type, and version control.
  • BaseEvent: Provides a concrete implementation of the DomainEvent interface, including serialization/deserialization and payload processing.
  • EventStore Interface: Defines event persistence, query, snapshot, and batch operation capabilities, supporting both database and event stream storage modes.
  • Event Bus and Publisher: Responsible for event publishing and subscription, supporting eventual consistency and distributed systems integration.
  • HTTP Handler: Provides RESTful APIs for event management, including event creation, query, and processing.

Domain events follow the event-driven architecture pattern: commands drive aggregate roots to generate domain events, events are persisted through the event store, and then published to subscribers via the event bus, enabling loose coupling between components and eventual consistency.

DomainEvent Interface and BaseEvent​

  • DomainEvent Interface
    • Event Identification: Event ID and event type for unique identification and classification.
    • Aggregate Binding: Aggregate ID and aggregate type to associate events with their source aggregates.
    • Version Control: Version number for optimistic concurrency control and event ordering.
    • Timestamp: Creation time for event ordering and auditing.
  • BaseEvent
    • Implements the DomainEvent interface with concrete fields and methods.
    • Provides serialization/deserialization capabilities for event payloads.
    • Includes helper methods for event construction and metadata management.
  • Event Creation
    • Events are created by aggregate roots in response to commands, capturing state changes and business actions.
    • Event payloads should be immutable and contain all necessary information for event processing.
  • Event Publishing
    • Events are published to the event bus after being persisted in the event store.
    • The event bus distributes events to subscribed components, enabling loose coupling.
  • Event Subscriptions
    • Subscribers register interest in specific event types and process events asynchronously.
    • Subscription patterns include point-to-point, publish-subscribe, and request-reply.
  • Event Sourcing
    • Aggregate state is reconstructed by replaying historical events from the event store.
    • Snapshots are used to optimize reconstruction performance for aggregates with many events.
  • CQRS (Command Query Responsibility Segregation)
    • Commands modify state and generate events, while queries read from optimized projections.
    • Enables independent scaling and optimization of read and write operations.
  • Event Store Implementations
    • Database-based: Stores events in relational or document databases, suitable for strong consistency scenarios.
    • Event stream-based: Uses message brokers like Kafka or NATS, suitable for high throughput and distributed systems.
  • Event Bus and Publisher
    • NATS-based implementation for reliable event delivery and scalability.
    • Supports both direct publishing and request-reply patterns.

  • HTTP Endpoints

    • Provide RESTful APIs for event management, including event creation, query, and processing.
    • Integrate with the event store and business services to handle event-related operations.

  • Component Coupling

    • The DomainEvent interface and BaseEvent provide a common contract for event handling, reducing coupling between components.
    • The EventStore interface abstracts event storage, allowing different implementations to be used based on requirements.

  • External Dependencies

    • NATS for event bus and publisher implementation.
    • Database or event stream systems for event persistence.
  • Event Storage
    • Database-based storage may experience performance issues under high event throughput; consider batch operations and indexing.
    • Event stream-based storage provides better scalability but may require additional tools for event replay and snapshot management.
  • Event Processing
    • Asynchronous event processing can introduce latency; use dead-letter queues and retry mechanisms to handle failures.
    • Event ordering is crucial for consistent state reconstruction; ensure events are processed in the correct order.
  • Serialization
    • Event payloads should be serialized efficiently to minimize storage and network overhead.
    • Use compact serialization formats like Protocol Buffers or MessagePack for better performance.

Troubleshooting Guide​

  • Event Publishing Failures
    • Check NATS connection status and network connectivity.
    • Verify event payload serialization and metadata consistency.
  • Event Reconstruction Issues
    • Ensure events are stored in the correct order and with consistent metadata.
    • Use snapshots for aggregates with many historical events to improve reconstruction performance.
  • Subscription Processing Errors
    • Implement dead-letter queues and retry mechanisms for failed event processing.
    • Monitor event processing latency and error rates to identify bottlenecks.

Domain events are a fundamental building block of event-driven architectures, enabling loose coupling, eventual consistency, and scalable systems. In the Sparrow framework, domain events are modeled through the DomainEvent interface and BaseEvent implementation, persisted via the EventStore interface, and distributed through the event bus and publisher. By following event sourcing and CQRS patterns, developers can build systems that are more resilient, scalable, and maintainable.

Appendix​