# ismasan/sourced architecture

> Architecture diagram of the GitHub repository ismasan/sourced, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ismasan/sourced
- Repository: https://github.com/ismasan/sourced

## Overview

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:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Trigger
    UC["User Command"]:::infra

    %% Registration & Routing Layer
    subgraph "Registration & Routing"
        reg["Registration (Sourced.register)"]:::routing
        conf["Configuration"]:::routing
        rout["Router/Dispatcher"]:::routing
        reg --> conf
        conf --> rout
    end
    UC -->|"command_invocation"| rout

    %% Domain Logic: Actor Layer
    subgraph "Domain Logic: Cart Actor"
        ch["Command Handler"]:::domain
        ee["Event Evolve"]:::domain
        rb["Reaction Block"]:::domain
        ch -->|"processes"| ee
        ee -->|"notifies"| rb
    end
    rout -->|"routes_command"| ch
    rb -->|"triggers"| ch

    %% Read Model: Projector
    subgraph "Read Models"
        proj["Projector"]:::domain
    end
    ee -->|"propagates_event"| proj

    %% Supervisors & Workers Layer
    subgraph "Supervisors & Workers"
        sup["Supervisor"]:::infra
        work["Worker Pool"]:::infra
        sup -->|"initiates"| work
    end
    work -->|"queues_command"| ch

    %% Backend Storage Layer
    subgraph "Backend Storage"
        ar["ActiveRecord Backend"]:::infra
        sq["Sequel Backend"]:::infra
        err["Error Strategy"]:::error
    end
    ee -->|"persists_event"| ar
    ee -->|"persists_event"| sq
    ar -->|"error_notify"| err
    sq -->|"error_notify"| err
    err -->|"retry"| work

    %% Click Events
    click reg "https://github.com/ismasan/sourced/blob/main/lib/sourced.rb"
    click conf "https://github.com/ismasan/sourced/blob/main/lib/sourced/configuration.rb"
    click rout "https://github.com/ismasan/sourced/blob/main/lib/sourced/router.rb"
    click ch "https://github.com/ismasan/sourced/blob/main/lib/sourced/actor.rb"
    click ch "https://github.com/ismasan/sourced/blob/main/examples/cart.rb"
    click ee "https://github.com/ismasan/sourced/blob/main/lib/sourced/evolve.rb"
    click rb "https://github.com/ismasan/sourced/blob/main/lib/sourced/react.rb"
    click proj "https://github.com/ismasan/sourced/blob/main/lib/sourced/projector.rb"
    click ar "https://github.com/ismasan/sourced/blob/main/lib/sourced/backends/active_record_backend.rb"
    click sq "https://github.com/ismasan/sourced/blob/main/lib/sourced/backends/sequel_backend.rb"
    click sup "https://github.com/ismasan/sourced/blob/main/lib/sourced/supervisor.rb"
    click work "https://github.com/ismasan/sourced/blob/main/lib/sourced/worker.rb"
    click work "https://github.com/ismasan/sourced/blob/main/examples/workers.rb"

    %% Styles
    classDef domain fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef infra fill:#98fb98,stroke:#008000,stroke-width:2px;
    classDef error fill:#ffc0cb,stroke:#ff0000,stroke-width:2px;
    classDef routing fill:#e0ffff,stroke:#008080,stroke-width:2px;
```
