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.
Ensure you have Postgres and Ruby 2.2 or higher installed.
First you need to install the correct ruby version to work with:
$ rbenv installThen make sure you have postgresql running in the background:
$ brew services restart postgresqlThen run the setup script.
$ ./scripts/setupRun the tests.
$ bundle exec rakeStart the web app and event stream processors via Foreman.
$ foreman startThen 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 [email protected] -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├── 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
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.
TodoAddedTodoCompletedTodoAbandonedTodoAmendedStakeholderNotifiedOfTodoCompletion
A Todo can have the following attributes:
- title
- description
- due_date
- stakeholder_email
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.
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).
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.
OutstandingTodosCompletedTodosScheduledTodos(has due date)
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
StakeholderNotifiedOfTodoCompletionevent to record this fact.
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 │ │
└─────────────┘
│ │
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
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent