{"id":18510751,"url":"https://github.com/envato/event_sourcery_todo_app","last_synced_at":"2025-04-09T04:33:22.434Z","repository":{"id":21902354,"uuid":"94155949","full_name":"envato/event_sourcery_todo_app","owner":"envato","description":"Example event_sourcery app","archived":false,"fork":false,"pushed_at":"2025-04-01T02:50:50.000Z","size":170,"stargazers_count":16,"open_issues_count":1,"forks_count":8,"subscribers_count":62,"default_branch":"main","last_synced_at":"2025-04-01T03:33:05.229Z","etag":null,"topics":["cqrs","cqrs-es","domain-driven-design","event-sourcery","event-sourcing"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/envato.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-13T01:27:10.000Z","updated_at":"2025-04-01T02:50:53.000Z","dependencies_parsed_at":"2024-01-01T03:22:40.870Z","dependency_job_id":"bc1bb1db-3d40-480b-86b4-537e5b212fcc","html_url":"https://github.com/envato/event_sourcery_todo_app","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envato%2Fevent_sourcery_todo_app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envato%2Fevent_sourcery_todo_app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envato%2Fevent_sourcery_todo_app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/envato%2Fevent_sourcery_todo_app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/envato","download_url":"https://codeload.github.com/envato/event_sourcery_todo_app/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247980833,"owners_count":21027803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cqrs","cqrs-es","domain-driven-design","event-sourcery","event-sourcing"],"created_at":"2024-11-06T15:24:53.328Z","updated_at":"2025-04-09T04:33:21.826Z","avatar_url":"https://github.com/envato.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Event Sourcery Todo Example App\n\n[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)\n\nAn 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).\n\nThis application is intended to illustrate concepts in EventSourcery, how they relate to each other, and how to use them in practice.\n\n## Get started\n\nEnsure you have Postgres and Ruby 2.2 or higher installed.\n\nFirst you need to install the correct ruby version to work with:\n\n```sh\n$ rbenv install\n```\n\nThen make sure you have postgresql running in the background:\n\n```sh\n$ brew services restart postgresql\n```\n\nThen run the setup script.\n\n```sh\n$ ./scripts/setup\n```\n\nRun the tests.\n\n```sh\n$ bundle exec rake\n```\n\n## Using the Application\n\nStart the web app and event stream processors via Foreman.\n\n```sh\n$ foreman start\n```\n\nThen you can manage your Todos using the `request` CLI script.\n\n```sh\n# Add a todo\n$ ./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\n\n# Amend\n$ ./scripts/request amend -i aac35923-39b4-4c39-ad5d-f79d67bb2fb2 -t \"Get to the chopper, NOW\"\n\n# Complete\n$ ./scripts/request complete -i aac35923-39b4-4c39-ad5d-f79d67bb2fb2 -D 2017-01-01\n\n# Abandon\n$ ./scripts/request abandon -i aac35923-39b4-4c39-ad5d-f79d67bb2fb2 -D 2017-01-01\n\n# List\n$ ./scripts/request list -l outstanding\n$ ./scripts/request list -l scheduled\n$ ./scripts/request list -l completed\n```\n\n## Application Structure\n\n```\n├── app\n│   ├── aggregates\n│   │   └── todo.rb\n│   ├── commands\n│   │   └── todo\n│   │       ├── abandon.rb\n│   │       ├── add.rb\n│   │       ├── amend.rb\n│   │       └── complete.rb\n│   ├── errors.rb\n│   ├── events\n│   │   ├── stakeholder_notified_of_todo_completion.rb\n│   │   ├── todo_abandoned.rb\n│   │   ├── todo_added.rb\n│   │   ├── todo_amended.rb\n│   │   └── todo_completed.rb\n│   ├── projections\n│   │   ├── completed_todos\n│   │   │   ├── projector.rb\n│   │   │   └── query.rb\n│   │   ├── outstanding_todos\n│   │   │   ├── projector.rb\n│   │   │   └── query.rb\n│   │   └── scheduled_todos\n│   │       ├── projector.rb\n│   │       └── query.rb\n│   ├── reactors\n│   │   └── todo_completed_notifier.rb\n│   ├── utils.rb\n│   └── web\n│       └── server.rb\n├── config\n│   └── environment.rb\n```\n\n### Events\n\nThese 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.\n\n- `TodoAdded`\n- `TodoCompleted`\n- `TodoAbandoned`\n- `TodoAmended`\n- `StakeholderNotifiedOfTodoCompletion`\n\nA `Todo` can have the following attributes:\n\n- title\n- description\n- due_date\n- stakeholder_email\n\n### Commands\n\nThe 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.\n\n### Aggregates\n\nThe 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`).\n\n### Projections\n\nYou 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.\n\n- `OutstandingTodos`\n- `CompletedTodos`\n- `ScheduledTodos` (has due date)\n\n### Reactors\n\nReactors 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.\n\nReactors can be used to build [process managers or sagas](https://msdn.microsoft.com/en-us/library/jj591569.aspx).\n\n- `TodoCompletedNotifier`\n  - \"sends\" an email notifying stakeholders of todo completion.\n  - Emits `StakeholderNotifiedOfTodoCompletion` event to record this fact.\n\n## Data flow of an \"Add Todo\" Request\n\nBelow we see the flow of data of an \"add todo\" request. Note that arrows indicate data flow.\n\nNote that stage 1 and 2 are not synchronous. This means EventSourcery applications need to embrace [eventual consistency](https://en.wikipedia.org/wiki/Eventual_consistency).\n\nAlso note that we are only showing one projection below. The other projectors and reactors will also update their projections based on the TodoAdded event.\n\n```\n\n         1. Add Todo      │       2. Update Outstanding   │     3. Issue Outstanding\n                                    Todos Projection                Todos Query\n               │          │                               │\n               ▼                                                          ▲\n       ┌───────────────┐  │                               │               │\n       │Command Handler│                                                  │\n       └───────────────┘  │                               │          F. Handle\n               │                                                       Query\n     B. Call add todo on  │                               │               │\n          aggregate                                                       │\n               │          │                               │               │\n               ▼                       ┌─────────────┐                    │\n        ┌─────────────┐   │            │ Outstanding │    │        ┌─────────────┐\n        │             │       ┌───────▶│    Todos    │             │             │\n     ┌─▶│  Aggregate  │   │   │        │  Projector  │    │        │Query Handler│\n     │  │             │       │        └─────────────┘             │             │\n     │  └─────────────┘   │  D. Read          │           │        └─────────────┘\n     │         │              event      E. Update                        ▲\n A. Load  C. Save new     │   │          Projection       │               │\nstate from   event            │               │                        G. Read\n  events       │          │   │               │           │       Outstanding Todos\n     │         ▼              │               ▼                      Projection\n     │  ┌─────────────┐   │   │        ┌─────────────┐    │               │\n     │  │             │       │        │ Outstanding │                    │\n     └──│ Event Store │───┼───┘        │    Todos    │    │               │\n        │             │                │  Database   │────────────────────┘\n        └─────────────┘   │            │    Table    │    │\n                                       └─────────────┘\n                          │                               │\n\n```\n\n## Routes\n\nThe application exposes a web UI with the following API.\n\n```\nGET /todos/outstanding\nGET /todos/completed\nGET /todos/scheduled\nPOST /todo/:id (add)\nPUT /todo/:id (amend)\nPOST /todo/:id/complete\nPOST /todo/:id/abandon\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenvato%2Fevent_sourcery_todo_app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fenvato%2Fevent_sourcery_todo_app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fenvato%2Fevent_sourcery_todo_app/lists"}