# commanded/eventstore architecture

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

- Interactive diagram: https://gitdiagram.com/commanded/eventstore
- Repository: https://github.com/commanded/eventstore

## Overview

##### Main Components
- EventStore Application: At the center is the EventStore module (see lib/event_store.ex and lib/event_store/application.ex) that sets up and starts the supervision tree.
- Storage Layer: Highlight modules that manage appending events, reading streams, handling snapshots, and executing SQL statements (lib/event_store/storage, lib/event_store/sql, and related EEx templates).
- Serialization Layer: Include components for event data serialization such as the JSON (and JSONB) serializers.
- Subscriptions & Notifications: Identify the subscription logic (lib/event_store/subscriptions/*) and notifications (lib/event_store/notifications/*) that enable components to subscribe to events and handle acknowledgements.
- Cluster and Configuration: Represent cluster configuration files (in the cluster directory) and the configuration management in “config/” files. Show how the system’s behavior is influenced by different environments (bench, dev, test).
- Mix Tasks & Migrations: Indicate the management tasks (lib/mix/tasks/* and lib/event_store/tasks/*) for bootstrapping, migrating, and administering the event store.
- Benchmarking: Although it might not be a core architectural component, include a reference note to the “bench” directory which is used for performance measurement and tuning.

##### Relationships and Interactions
- Subscription system as an interaction connecting “EventStore” to “Subscribers” (which could be external processes or GenServers) via the notifications subsystem.
- Where configuration (various config files and cluster settings) influences the behavior of the system.

##### Architectural Patterns and Design Principles
- Supervision & Fault Tolerance: Indicate the supervisor tree (lib/event_store/supervisor.ex and related modules) managing child processes.
- Modularity: Emphasize the clear separation between components (storage, serialization, subscriptions) so that each can be evolved or replaced independently.
- Clustering: Mark the support for running in a distributed environment via the cluster configuration files.
- Extensibility: Note how Mix tasks and configuration parsers establish hooks for administration, migrations, and modifications.

##### Relevant Technologies and Frameworks
- Elixir (OTP/Supervision Trees, GenServers)
- PostgreSQL for durable storage, including SQL scripts (priv/event_store/migrations and lib/event_store/sql/statements)
- EEx templates used for SQL generation
- Benchmarks rely on Erlang’s external term format serialization (as mentioned in the README)

## Diagram (Mermaid)

```mermaid
graph TD
    Client["Client Process"]:::external
    EventStore["EventStore Application"]:::eventstore
    PostgreSQL["PostgreSQL Database"]:::database

    subgraph "Storage Layer"
        Storage["Storage Layer"]:::storage
        Appender["Appender"]:::storage
        Reader["Reader"]:::storage
        Snapshot["Snapshot Manager"]:::storage
    end

    subgraph "SQL Modules"
        SQL["SQL Modules"]:::storage
        EEx["EEx Templates"]:::storage
    end

    subgraph "Serialization Layer"
        Serialization["Serialization Layer"]:::serialization
        JSONSer["JSON Serializer"]:::serialization
        JSONBSer["JSONB Serializer"]:::serialization
        TermSer["Term Serializer"]:::serialization
    end

    subgraph "Subscriptions & Notifications"
        Subs["Subscriptions & Notifications"]:::subscriptions
        SubManager["Subscription Manager"]:::subscriptions
        SubFSM["Subscription FSM"]:::subscriptions
        Notif["Notifications (Publisher/Listener)"]:::subscriptions
    end

    subgraph "Cluster & Configuration"
        Config["Cluster & Configuration"]:::config
    end

    subgraph "Mix Tasks & Migrations"
        Tasks["Mix Tasks & Migrations"]:::tasks
    end

    subgraph "Benchmarking"
        Bench["Benchmarking"]:::benchmark
    end

    Client -->|"appendEvent"| EventStore
    EventStore -->|"initStorage"| Storage
    Storage -->|"useAppender"| Appender
    Storage -->|"useReader"| Reader
    Storage -->|"manageSnapshots"| Snapshot

    EventStore -->|"executesSQL"| SQL
    SQL -->|"usesEEx"| EEx

    EventStore -->|"serializes"| Serialization
    Serialization -->|"JSON"| JSONSer
    Serialization -->|"JSONB"| JSONBSer
    Serialization -->|"Term"| TermSer

    EventStore -->|"notifies"| Subs
    Subs -->|"manages"| SubManager
    Subs -->|"workflow"| SubFSM
    Subs -->|"publishes"| Notif

    EventStore -->|"stores"| PostgreSQL

    Config -->|"configures"| EventStore
    Tasks -->|"adminTasks"| EventStore
    Bench -->|"benchmarks"| EventStore

    click EventStore "https://github.com/commanded/eventstore/blob/master/lib/event_store.ex"
    click EventStore "https://github.com/commanded/eventstore/blob/master/lib/event_store/application.ex"

    click Storage "https://github.com/commanded/eventstore/blob/master/lib/event_store/storage.ex"
    click Storage "https://github.com/commanded/eventstore/tree/master/lib/event_store/storage/"

    click SQL "https://github.com/commanded/eventstore/tree/master/lib/event_store/sql/"
    click SQL "https://github.com/commanded/eventstore/tree/master/lib/event_store/sql/statements/"

    click Serialization "https://github.com/commanded/eventstore/blob/master/lib/event_store/json_serializer.ex"
    click Serialization "https://github.com/commanded/eventstore/blob/master/lib/event_store/jsonb_serializer.ex"
    click Serialization "https://github.com/commanded/eventstore/blob/master/lib/event_store/term_serializer.ex"

    click Subs "https://github.com/commanded/eventstore/tree/master/lib/event_store/subscriptions/"
    click Subs "https://github.com/commanded/eventstore/tree/master/lib/event_store/notifications/"

    click Config "https://github.com/commanded/eventstore/tree/master/cluster/"
    click Config "https://github.com/commanded/eventstore/tree/master/config/"

    click Tasks "https://github.com/commanded/eventstore/tree/master/lib/mix/tasks/"
    click Tasks "https://github.com/commanded/eventstore/tree/master/priv/event_store/migrations/"

    click Bench "https://github.com/commanded/eventstore/tree/master/bench/"

    classDef eventstore fill:#AEDFF7,stroke:#1B7FCF,stroke-width:2px;
    classDef storage fill:#C5F7C1,stroke:#2DA44E,stroke-width:2px;
    classDef serialization fill:#F7E2AE,stroke:#D49C2E,stroke-width:2px;
    classDef subscriptions fill:#F7D6AE,stroke:#D47F2E,stroke-width:2px;
    classDef config fill:#E2E2E2,stroke:#8C8C8C,stroke-width:2px;
    classDef tasks fill:#E7C7F7,stroke:#B367D7,stroke-width:2px;
    classDef benchmark fill:#E0F7FA,stroke:#00ACC1,stroke-width:2px;
    classDef database fill:#FFD9C0,stroke:#D2691E,stroke-width:2px;
    classDef external fill:#FFF2AE,stroke:#D4A017,stroke-width:2px;
```
