Skip to main content

Example Project

Overview​

This example project demonstrates how to use the Sparrow framework to build a scalable order system using DDD (Domain-Driven Design), CQRS (Command Query Responsibility Segregation), and Event Sourcing patterns.

Project Structure​

The example project is located in examples/order-system with the following structure:

  • cmd: Application entry points (demo and full versions)
  • configs: Configuration files (application, logging, database, event bus, HTTP)
  • pkg:
    • domain/entities: Domain models (aggregate roots, value objects, events, errors)
    • usecases: Use case layer (commands, queries, repository interfaces, application services)
    • adapters: Adapter layer (HTTP handlers, routers)
    • infrastructures: Infrastructure layer (in-memory repositories, etc.)

Core Components​

Domain Model​

  • Aggregate Root: Order (contains customer ID, order items, total price, status, shipping address)
  • Value Object: Address (contains street, city, state, zip code, country)
  • Domain Events: OrderCreated, OrderConfirmed, OrderCancelled, OrderShipped, OrderDelivered
  • Error Types: OrderStatusError

Use Case Layer​

  • Commands: CreateOrderCommand, ConfirmOrderCommand, CancelOrderCommand, ShipOrderCommand, DeliverOrderCommand
  • Repository Interface: OrderRepository (supports querying by customer ID and status)
  • Application Service: OrderApplicationService (encapsulates business processes)

Adapter Layer​

  • HTTP Handlers: OrderHandler (receives requests, constructs commands/queries)
  • Router: SetupRouter (defines /api/v1/orders routes)

Infrastructure Layer​

  • In-Memory Repository: InMemoryOrderRepository (simple implementation based on memory)

Order Status Flow​

Pending → Confirmed → Shipped → Delivered
    ↓         ↓          ↓
Cancelled  Cancelled  Cancelled

API Endpoints​

Health Check​

  • GET /health

Order Management​

  • POST /api/v1/orders - Create order
  • POST /api/v1/orders/{id}/confirm - Confirm order
  • POST /api/v1/orders/{id}/cancel - Cancel order
  • POST /api/v1/orders/{id}/ship - Ship order
  • POST /api/v1/orders/{id}/deliver - Deliver order
  • GET /api/v1/orders/{id} - Get order
  • GET /api/v1/orders - List orders

Quick Start​

  1. Navigate to the example directory
  2. Install dependencies
  3. Run the demo or full version

Extending the Example​

Switch to Persistent Storage​

Implement a persistent version of OrderRepository and register it in the dependency injection container.

Add Domain Events​

Define events in the domain layer, trigger them in aggregate roots, and handle them in projections.

Add Queries​

Define query objects and view models in the use case layer, implement them in the application service, and expose them via HTTP.

Key Takeaways​

This example demonstrates:

  • Clean architecture with clear separation of concerns
  • Domain-driven design with aggregates, entities, and value objects
  • Event sourcing with domain events
  • CQRS pattern with separate command and query paths
  • Dependency inversion with repository interfaces

The example provides both a simplified demo and a complete implementation, making it easy to understand and learn the framework.