https://github.com/envato/event_sourcery_todo_app
Example event_sourcery app
https://github.com/envato/event_sourcery_todo_app
cqrs cqrs-es domain-driven-design event-sourcery event-sourcing
Last synced: 6 months ago
JSON representation
Example event_sourcery app
- Host: GitHub
- URL: https://github.com/envato/event_sourcery_todo_app
- Owner: envato
- License: mit
- Created: 2017-06-13T01:27:10.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2025-04-01T02:50:50.000Z (6 months ago)
- Last Synced: 2025-04-01T03:33:05.229Z (6 months ago)
- Topics: cqrs, cqrs-es, domain-driven-design, event-sourcery, event-sourcing
- Language: Ruby
- Size: 166 KB
- Stars: 16
- Watchers: 62
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Event Sourcery Todo Example App
[](https://heroku.com/deploy)
An example event sourced/CQRS web application built using [EventSourcery](https://github.com/envato/event_sourcery) and its [Postgres event store implementation](https://github.com/envato/event_sourcery-postgres).
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:
```sh
$ rbenv install
```
Then make sure you have postgresql running in the background:
```sh
$ brew services restart postgresql
```
Then run the setup script.
```sh
$ ./scripts/setup
```
Run the tests.
```sh
$ bundle exec rake
```
## Using the Application
Start the web app and event stream processors via Foreman.
```sh
$ foreman start
```
Then you can manage your Todos using the `request` CLI script.
```sh
# 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](https://msdn.microsoft.com/en-us/library/jj591569.aspx).
- `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](https://en.wikipedia.org/wiki/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
```