Event-Driven Architecture Order Management System

A comprehensive Event Sourcing and CQRS implementation for order management using Java, Spring Boot, and modern architectural patterns.

🚀 Features

• Event Sourcing: Complete audit trail of all order changes
• CQRS Pattern: Separate command and query responsibilities
• Event Store: Persistent storage of all domain events
• Snapshot Mechanism: Performance optimization for large event streams
• Event Replay: Reconstruct order state from historical events
• RESTful API: Full CRUD operations for order management
• Event Timeline Dashboard: Visualize order event history
• Real-time Updates: Event-driven architecture for real-time state changes

🏗️ Architecture

Event Sourcing

• All state changes are captured as events
• Complete audit trail of order modifications
• Event replay capabilities for state reconstruction
• Snapshot mechanism for performance optimization

CQRS (Command Query Responsibility Segregation)

• Commands: Handle write operations (CreateOrder, AddItem, UpdateStatus)
• Queries: Handle read operations (GetOrder, GetAllOrders)
• Separate data models for read and write operations
• Optimized for different performance characteristics

Domain Events

• OrderCreatedEvent: When a new order is created
• OrderItemAddedEvent: When items are added to an order
• OrderStatusChangedEvent: When order status changes

🛠️ Technologies

• Java 17+
• Spring Boot 3.2.0
• Spring Data JPA
• H2 Database (in-memory for development)
• Jackson for JSON serialization
• Maven for dependency management

📁 Project Structure

src/main/java/com/ordersystem/
├── OrderManagementApplication.java          # Main application class
├── domain/                                 # Domain models
│   ├── Order.java                         # Order entity
│   ├── OrderItem.java                     # Order item entity
│   ├── OrderStatus.java                   # Order status enum
│   └── OrderAggregate.java                # Order aggregate root
├── eventsourcing/                         # Event sourcing infrastructure
│   ├── Event.java                         # Base event class
│   ├── EventStore.java                    # Event store interface
│   ├── JpaEventStore.java                 # JPA event store implementation
│   ├── EventEntity.java                   # Event database entity
│   ├── SnapshotStore.java                 # Snapshot store interface
│   ├── JpaSnapshotStore.java              # JPA snapshot store implementation
│   ├── Snapshot.java                      # Snapshot class
│   ├── SnapshotEntity.java                # Snapshot database entity
│   └── events/                            # Domain events
│       ├── OrderCreatedEvent.java
│       ├── OrderItemAddedEvent.java
│       └── OrderStatusChangedEvent.java
├── cqrs/                                  # CQRS implementation
│   ├── Command.java                       # Command interface
│   ├── Query.java                         # Query interface
│   ├── CommandHandler.java                # Command handler interface
│   ├── QueryHandler.java                  # Query handler interface
│   ├── commands/                          # Command classes
│   │   ├── CreateOrderCommand.java
│   │   ├── AddOrderItemCommand.java
│   │   └── UpdateOrderStatusCommand.java
│   ├── queries/                           # Query classes
│   │   ├── GetOrderQuery.java
│   │   └── GetAllOrdersQuery.java
│   └── handlers/                          # Command and query handlers
│       ├── OrderCommandHandler.java
│       └── OrderQueryHandler.java
└── api/                                   # REST API controllers
    ├── OrderController.java               # Order management API
    └── EventTimelineController.java       # Event timeline API

🚀 Getting Started

Prerequisites

• Java 17 or higher
• Maven 3.6 or higher

Installation

1. Clone the repository

   git clone https://github.com/imaad/event-sourcing-order-management.git
   cd event-sourcing-order-management

2. Build the project

   mvn clean install

3. Run the application

   mvn spring-boot:run

4. Access the application

   • Application: http://localhost:8080
   • H2 Console: http://localhost:8080/h2-console
   • API Documentation: Available at /api/orders

📚 API Documentation

Order Management Endpoints

Create Order

POST /api/orders
Content-Type: application/json

{
  "customerId": "CUST001",
  "customerName": "John Doe"
}

Add Item to Order

POST /api/orders/{orderId}/items
Content-Type: application/json

{
  "productId": "PROD001",
  "productName": "Laptop",
  "price": 999.99,
  "quantity": 1
}

Update Order Status

PUT /api/orders/{orderId}/status
Content-Type: application/json

{
  "status": "CONFIRMED"
}

Get Order

GET /api/orders/{orderId}

Get All Orders

GET /api/orders?customerId=CUST001&status=CONFIRMED&page=0&size=10

Event Timeline Endpoints

Get Order Event Timeline

GET /api/events/timeline/{orderId}

Get Order Events from Version

GET /api/events/timeline/{orderId}/from/{fromVersion}

Get Order Events in Range

GET /api/events/timeline/{orderId}/range/{fromVersion}/{toVersion}

Replay Order Events

GET /api/events/replay/{orderId}

🔧 Configuration

The application uses the following configuration (see application.properties):

• Database: H2 in-memory database
• Port: 8080
• Event Store: JPA-based with JSON serialization
• Snapshot Interval: Every 10 events
• Max Events per Replay: 1000

🧪 Testing

Unit Tests

mvn test

Integration Tests

mvn verify

📊 Event Timeline Dashboard

The system includes a web-based event timeline dashboard that provides:

• Real-time Event Visualization: See events as they occur
• Order State Reconstruction: Replay events to see order evolution
• Event Filtering: Filter events by type, date, or version
• Snapshot Viewing: View snapshots for performance optimization

🔄 Event Sourcing Benefits

1. Complete Audit Trail: Every change is recorded as an event
2. Temporal Queries: Query order state at any point in time
3. Event Replay: Reconstruct order state from historical events
4. Debugging: Easy to debug by replaying events
5. Compliance: Full compliance with audit requirements

🚀 Performance Optimizations

• Snapshots: Periodic snapshots reduce replay time
• Event Batching: Efficient event storage and retrieval
• CQRS: Separate read/write models for optimal performance
• Async Processing: Non-blocking event processing

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Imaad - GitHub Profile

🙏 Acknowledgments

• Spring Boot team for the excellent framework
• Event Sourcing community for architectural patterns
• CQRS community for command/query separation patterns

---

Note: This is a demonstration project showcasing Event Sourcing and CQRS patterns. For production use, consider additional security, monitoring, and scalability features.