How ismasan/sourced works
Based on our analysis of the file tree and the README, this project is an Event Sourcing and CQRS library for Ruby. Its purpose is to provide a cohesive, modular framework that helps developers design systems using commands, events, and reactions along with support for actors, projectors, and various backend adapters (like Sequel or ActiveRecord). The library also offers built‐in support for handling concurrency, error strategies, and integration with Rails.
Main Components
• Command/Events Infrastructure:
– Highlight that “command” blocks process incoming business intents (e.g. add_item) and “event” blocks evolve state.
• Actors:
– Represent the primary building block. Actors encapsulate both command handlers and event handlers.
– For instance, the “Cart” actor (illustrated in the README example) encapsulates the domain logic.
• Projectors:
– They are responsible for building views or maintaining read models.
– Two variations exist: “State-stored projectors” (with database access) and “Event-sourced projectors” (using past events).
– Represent projectors as distinct components that subscribe to events, update state, and trigger sync operations.
• Backends / Storage Layer:
– The library supports storing events, state snapshots, and also logs errors. Include a sub-component for error management via configured “error_strategy.”
• Supervisors and Workers:
– Include a “Supervisor” component that initializes background workers (the code in lib/sourced/supervisor.rb and examples in bin/console).
– These workers process commands and events concurrently yet with ordering guarantees on the same stream. Indicate the concurrency model using “stream IDs” and locks.
• Registration & Routing Mechanism:
– The registration of Actors and Projectors (via Sourced.register) is an essential component tying the various parts together.
– Illustrate an “Event Router” or “Command Dispatcher” that directs incoming commands to the proper actor and plugins reactions accordingly.
Relationships and Data Flows
• Commands originate (from a user or system invocation) and are routed to an Actor’s command handler.
• Once a command is validated, the actor publishes events that go to:
– The same actor’s event handler for state evolution.
– Registered reactors, such as projectors or other actors that use reaction blocks.
• Flow from supervisor/worker queues to the command/event handlers — emphasizing ordered processing per stream.
• Backend interactions where events get persisted and the error strategy mechanism that manages retries and stops on failures.
Architectural Patterns & Important Design Principles
• CQRS and Event Sourcing:
– Emphasize the separation of “write” (commands produce events) and “read” (projectors build current views).
• Actor-Based Concurrency:
– Highlight that each Actor encapsulates its own state and concurrency is controlled via stream IDs (with locks ensuring sequential processing for the same stream).
• Causation and Correlation:
– Show that each command or event carries metadata (correlation_id and causation_id) so that cause-and-effect chains can be traced.
• Error Handling: