Event Sourcery Todo Example App

An example event sourced/CQRS web application built using EventSourcery and its Postgres event store implementation.

This application is intended to illustrate concepts in EventSourcery, how they relate to each other, and how to use them in practice.

Get started

Ensure you have Postgres and Ruby 2.2 or higher installed.

First you need to install the correct ruby version to work with:

$ rbenv install

Then make sure you have postgresql running in the background:

$ brew services restart postgresql

Then run the setup script.

$ ./scripts/setup

Run the tests.

$ bundle exec rake

Using the Application

Start the web app and event stream processors via Foreman.

$ foreman start

Then you can manage your Todos using the request CLI script.

# Add a todo
$ ./scripts/request add -i aac35923-39b4-4c39-ad5d-f79d67bb2fb2 -t "Get to the chopper" -d "It's in the trees" -s dillon@cia.gov -D 2017-01-01

# Amend
$ ./scripts/request amend -i aac35923-39b4-4c39-ad5d-f79d67bb2fb2 -t "Get to the chopper, NOW"

# Complete
$ ./scripts/request complete -i aac35923-39b4-4c39-ad5d-f79d67bb2fb2 -D 2017-01-01

# Abandon
$ ./scripts/request abandon -i aac35923-39b4-4c39-ad5d-f79d67bb2fb2 -D 2017-01-01

# List
$ ./scripts/request list -l outstanding
$ ./scripts/request list -l scheduled
$ ./scripts/request list -l completed

Application Structure

├── app
│   ├── aggregates
│   │   └── todo.rb
│   ├── commands
│   │   └── todo
│   │       ├── abandon.rb
│   │       ├── add.rb
│   │       ├── amend.rb
│   │       └── complete.rb
│   ├── errors.rb
│   ├── events
│   │   ├── stakeholder_notified_of_todo_completion.rb
│   │   ├── todo_abandoned.rb
│   │   ├── todo_added.rb
│   │   ├── todo_amended.rb
│   │   └── todo_completed.rb
│   ├── projections
│   │   ├── completed_todos
│   │   │   ├── projector.rb
│   │   │   └── query.rb
│   │   ├── outstanding_todos
│   │   │   ├── projector.rb
│   │   │   └── query.rb
│   │   └── scheduled_todos
│   │       ├── projector.rb
│   │       └── query.rb
│   ├── reactors
│   │   └── todo_completed_notifier.rb
│   ├── utils.rb
│   └── web
│       └── server.rb
├── config
│   └── environment.rb

Events

These are our domain events. They are stored in our event store as a list of immutable facts over time. Together they form the source of truth for our application's state.

• TodoAdded
• TodoCompleted
• TodoAbandoned
• TodoAmended
• StakeholderNotifiedOfTodoCompletion

A Todo can have the following attributes:

• title
• description
• due_date
• stakeholder_email

Commands

The set of command handlers and commands that can be issued against the system. These form an interface between the web API and the domain model in the aggregate.

Aggregates

The domain is modeled via aggregates. In this application we only have one aggregate root: Todo. It loads its state from the event store (via the repository), executes commands, and raises new events which are saved back to the store (again via the repository).

Projections

You can think of projections as read-only models. They are created and updated by projectors and in this case show different current state views over the events that are the source of truth for our application state.

• OutstandingTodos
• CompletedTodos
• ScheduledTodos (has due date)

Reactors

Reactors listen for events and take some action. Often these actions will involve emitting other events into the store. Sometimes it may involve triggering side effects in external systems.

Reactors can be used to build process managers or sagas.

• TodoCompletedNotifier
  • "sends" an email notifying stakeholders of todo completion.
  • Emits StakeholderNotifiedOfTodoCompletion event to record this fact.

Data flow of an "Add Todo" Request

Below we see the flow of data of an "add todo" request. Note that arrows indicate data flow.

Note that stage 1 and 2 are not synchronous. This means EventSourcery applications need to embrace eventual consistency.

Also note that we are only showing one projection below. The other projectors and reactors will also update their projections based on the TodoAdded event.

         1. Add Todo      │       2. Update Outstanding   │     3. Issue Outstanding
                                    Todos Projection                Todos Query
               │          │                               │
               ▼                                                          ▲
       ┌───────────────┐  │                               │               │
       │Command Handler│                                                  │
       └───────────────┘  │                               │          F. Handle
               │                                                       Query
     B. Call add todo on  │                               │               │
          aggregate                                                       │
               │          │                               │               │
               ▼                       ┌─────────────┐                    │
        ┌─────────────┐   │            │ Outstanding │    │        ┌─────────────┐
        │             │       ┌───────▶│    Todos    │             │             │
     ┌─▶│  Aggregate  │   │   │        │  Projector  │    │        │Query Handler│
     │  │             │       │        └─────────────┘             │             │
     │  └─────────────┘   │  D. Read          │           │        └─────────────┘
     │         │              event      E. Update                        ▲
 A. Load  C. Save new     │   │          Projection       │               │
state from   event            │               │                        G. Read
  events       │          │   │               │           │       Outstanding Todos
     │         ▼              │               ▼                      Projection
     │  ┌─────────────┐   │   │        ┌─────────────┐    │               │
     │  │             │       │        │ Outstanding │                    │
     └──│ Event Store │───┼───┘        │    Todos    │    │               │
        │             │                │  Database   │────────────────────┘
        └─────────────┘   │            │    Table    │    │
                                       └─────────────┘
                          │                               │

Routes

The application exposes a web UI with the following API.

GET /todos/outstanding
GET /todos/completed
GET /todos/scheduled
POST /todo/:id (add)
PUT /todo/:id (amend)
POST /todo/:id/complete
POST /todo/:id/abandon