# jet/equinox architecture

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

- Interactive diagram: https://gitdiagram.com/jet/equinox
- Repository: https://github.com/jet/equinox

## Overview

##### Overall project type and purpose
- Equinox is not a framework but a collection of composable libraries that implement the core event sourcing “decider” pattern along with plug‑in adapters for various backing stores (in‑memory, CosmosDB, DynamoDB, EventStoreDB, SQL‐backed stores, MessageDB). It also includes serialization support via FsCodec and a number of sample and tool projects.
- Its main goal is to enable the creation of scalable, cache‑friendly, production‐ready event sourcing solutions that can support snapshots, optimistic concurrency control, and efficient queries against different persistent stores.

##### File structure and identify the main components
- Top‑level components:
– Root-level solution and build files (Equinox.sln, build.proj, build.ps1) for compiling multi-targeted NuGet packages.
– Source directory (“src”) which holds the core libraries. Look for separate subfolders for:
– Equinox.Core: Implements shared utility types (e.g. batching, TaskCell, retry logic, caching).
– Store adapters: Subdirectories like Equinox.MemoryStore, Equinox.CosmosStore (and its Prometheus variant), Equinox.DynamoStore (with Prometheus), Equinox.EventStore, Equinox.EventStoreDb, and Equinox.SqlStreamStore (with MsSql, MySql, Postgres) plus Equinox.MessageDb.
– Equinox: Likely the main business logic contracts, including the decider’s API.
- Additional support:
– Tools (in “tools” folder) that provide command‑line capabilities (Equinox.Tool, Equinox.Tools.TestHarness).
– Samples under “samples”: Several sample applications (for example, TodoBackend, Store, Tutorial, and a Web sample) illustrate how to integrate the library into full‑stack systems.
– Tests under “tests” ensure that load tests and integration tests run against all supported store implementations.

##### Modeling the key components
a. Core Equinox libraries as one large “module” for event sourcing. Within it, identify sub‑components such as:
– The core decider/stream API (managing state folding, snapshotting, and concurrency control).
– The caching and batching modules in Equinox.Core.
– Equinox.MemoryStore – a volatile in‑process store used for testing.
– Equinox.CosmosStore (and its Prometheus metrics add‑on) – handling the “Tip” document and unfolding snapshots.
– Equinox.DynamoStore – following a pattern similar to CosmosStore but adapted to DynamoDB’s API and characteristics.
– Equinox.EventStore and Equinox.EventStoreDb – for interfacing with EventStoreDB (using the modern gRPC protocols).
– Equinox.SqlStreamStore (with connector variants for MsSql, MySql, Postgres) – a SQL‑backed approach.
– Equinox.MessageDb – if using MessageDB in Postgres.
c. Serialization support (FsCodec space) as a shared library that each store adapter depends on.
d. External tooling and sample applications:
– The sample projects (TodoBackend, Store, Tutorial, Web) that demonstrate usage of deciders and event sourcing.
– The Equinox.Tool and related utilities used for load testing, initialization of databases (Cosmos, Dynamo, SQL) and operational tasks.
e. Optionally, show the relationship to complementary systems such as Propulsion (mentioned in the readme) that provides projection and reactor-side functionality.

##### Relationships and interactions
- That the serialization libraries (FsCodec) are “used by” both the core Equinox package and by all store adapters.
- Optionally, include separate paths or “lanes” for control flows such as:
– Snapshot/unfold management (e.g., within CosmosStore, the Tip concept that holds unfolds).
– Metrics reporting (connecting Prometheus-enabled components to a metrics sink).

##### Architectural patterns and design principles to capture
- Separation of concerns—you have a core, store‑agnostic event sourcing library (Equinox) that is then “composed” with store‑specific adapters.
- Application of Domain‑Driven Design (DDD), the decider pattern, and support for idempotency and optimistic concurrency.
- Use of a “Plug‑in” architecture; for any new store, the same Equinox abstraction can be reused.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Sample Applications
    subgraph "Sample Applications"
        Todo["TodoBackend Sample"]:::sample
        StoreS["Store Sample"]:::sample
        Tutorial["Tutorial Sample"]:::sample
        Web["Web Sample"]:::sample
    end

    %% Core Libraries with Serialization support
    subgraph "Core Libraries"
        EquinoxCore["Equinox Core (Decider, Caching)"]:::core
        FsCodecLib["FsCodec Serialization"]:::serial
    end

    %% Store Adapters
    subgraph "Store Adapters"
        MemoryStore["MemoryStore Adapter"]:::adapter
        CosmosStore["CosmosStore Adapter"]:::adapter
        CosmosStoreProm["CosmosStore Prometheus"]:::adapter
        DynamoStore["DynamoStore Adapter"]:::adapter
        DynamoStoreProm["DynamoStore Prometheus"]:::adapter
        EventStore["EventStore Adapter"]:::adapter
        EventStoreDb["EventStoreDb Adapter"]:::adapter
        subgraph "SQL Based Stores"
            SqlStream["SQL Stream Store Adapter"]:::adapter
            MsSql["SQL Adapter MsSql"]:::adapter
            MySql["SQL Adapter MySql"]:::adapter
            Postgres["SQL Adapter Postgres"]:::adapter
        end
        MessageDb["MessageDb Adapter"]:::adapter
    end

    %% Operational Tools
    subgraph "Operational Tools"
        EquinoxTool["Equinox.Tool"]:::tool
        TestHarness["Test Harness"]:::tool
    end

    %% Additional Components
    ArchitecturalDiagrams["Architectural Diagrams"]:::diag
    PromMetrics["Prometheus Metrics"]:::metrics

    %% Connections Between Components
    Todo -->|"calls_decider"| EquinoxCore
    StoreS -->|"calls_decider"| EquinoxCore
    Tutorial -->|"calls_decider"| EquinoxCore
    Web -->|"calls_decider"| EquinoxCore

    EquinoxTool -->|"operates"| EquinoxCore
    TestHarness -->|"operates"| EquinoxCore

    EquinoxCore -->|"uses"| FsCodecLib

    %% Equinox Core interactions with Store Adapters
    EquinoxCore -->|"write_load_cache"| MemoryStore
    EquinoxCore -->|"write_load_cache"| CosmosStore
    EquinoxCore -->|"write_load_cache"| CosmosStoreProm
    EquinoxCore -->|"write_load_cache"| DynamoStore
    EquinoxCore -->|"write_load_cache"| DynamoStoreProm
    EquinoxCore -->|"write_load_cache"| EventStore
    EquinoxCore -->|"write_load_cache"| EventStoreDb
    EquinoxCore -->|"write_load_cache"| SqlStream
    EquinoxCore -->|"write_load_cache"| MessageDb

    %% SQL Based Stores internal connections
    SqlStream -->|"connects"| MsSql
    SqlStream -->|"connects"| MySql
    SqlStream -->|"connects"| Postgres

    %% Prometheus metrics reporting
    CosmosStoreProm -->|"reports"| PromMetrics
    DynamoStoreProm -->|"reports"| PromMetrics

    %% Architectural diagrams reference the core design
    ArchitecturalDiagrams ---|"references"| EquinoxCore

    %% Click Events for Component Mapping
    click EquinoxCore "https://github.com/jet/equinox/blob/master/src/Equinox.Core"
    click EquinoxCore "https://github.com/jet/equinox/blob/master/src/Equinox/Decider.fs"
    click MemoryStore "https://github.com/jet/equinox/blob/master/src/Equinox.MemoryStore"
    click CosmosStore "https://github.com/jet/equinox/blob/master/src/Equinox.CosmosStore"
    click CosmosStoreProm "https://github.com/jet/equinox/blob/master/src/Equinox.CosmosStore.Prometheus"
    click DynamoStore "https://github.com/jet/equinox/blob/master/src/Equinox.DynamoStore"
    click DynamoStoreProm "https://github.com/jet/equinox/blob/master/src/Equinox.DynamoStore.Prometheus"
    click EventStore "https://github.com/jet/equinox/blob/master/src/Equinox.EventStore"
    click EventStoreDb "https://github.com/jet/equinox/blob/master/src/Equinox.EventStoreDb"
    click SqlStream "https://github.com/jet/equinox/blob/master/src/Equinox.SqlStreamStore"
    click MsSql "https://github.com/jet/equinox/blob/master/src/Equinox.SqlStreamStore.MsSql"
    click MySql "https://github.com/jet/equinox/blob/master/src/Equinox.SqlStreamStore.MySql"
    click Postgres "https://github.com/jet/equinox/blob/master/src/Equinox.SqlStreamStore.Postgres"
    click MessageDb "https://github.com/jet/equinox/blob/master/src/Equinox.MessageDb"
    click EquinoxTool "https://github.com/jet/equinox/blob/master/tools/Equinox.Tool"
    click TestHarness "https://github.com/jet/equinox/blob/master/tools/Equinox.Tools.TestHarness"
    click Todo "https://github.com/jet/equinox/tree/master/samples/TodoBackend"
    click StoreS "https://github.com/jet/equinox/tree/master/samples/Store"
    click Tutorial "https://github.com/jet/equinox/tree/master/samples/Tutorial"
    click Web "https://github.com/jet/equinox/tree/master/samples/Web"
    click ArchitecturalDiagrams "https://github.com/jet/equinox/tree/master/diagrams"

    %% Styles
    classDef core fill:#B3CDE0,stroke:#333,stroke-width:2px;
    classDef adapter fill:#CDEAC0,stroke:#333,stroke-width:2px;
    classDef sample fill:#FFEDBF,stroke:#333,stroke-width:2px;
    classDef tool fill:#D0E0E3,stroke:#333,stroke-width:2px;
    classDef serial fill:#FDD7E4,stroke:#333,stroke-width:2px;
    classDef metrics fill:#E3D4B9,stroke:#333,stroke-width:2px;
    classDef diag fill:#D1C4E9,stroke:#333,stroke-width:2px;
```
