# get-eventually/eventually-rs architecture

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

- Interactive diagram: https://gitdiagram.com/get-eventually/eventually-rs
- Repository: https://github.com/get-eventually/eventually-rs

## Overview

##### Main components
- Core Library (eventually): Contains modules for aggregates, commands, events, queries, serialization, tracing, and versioning. It defines the abstractions for modeling domain entities (aggregates) and the interface for interacting with an event store.
- Backend Implementations:
- InMemory Event Store: Found in eventually/src/event/store.rs, provided as a simple, in-memory implementation.
- PostgreSQL Event Store & Aggregate Repository: Provided by the eventually-postgres crate. It includes migrations and tests to support a production-ready event store.
- Macros (eventually-macros): Provides helper macros to reduce boilerplate and ease integration of the event sourced approach.
- Examples (particularly bank-accounting): Serves as a practical demonstration showing how the abstractions and backends integrate to form a complete event-sourced application.
- Supporting Tools & Configurations:
- CI/CD configurations (GitHub workflows, codecov, etc.).
- Environment settings, linting configuration, and documentation generation tools.

##### Relationships and interactions
- The Core Library (eventually) directly defines the abstractions and the primary API for event sourcing.
- The Macros (eventually-macros) enhance or automate parts of the core’s implementation, linking directly into the event sourcing abstractions.
- The eventually-postgres crate implements the concrete persistence layer for events and aggregates, integrating with the core library by conforming to its store abstraction.
- Example applications (i.e., bank-accounting) tie the pieces together by:
- Using the eventually crate’s abstractions.
- Choosing one of the backends (either in-memory or PostgreSQL) as their event store.
- Possibly leveraging the macros to simplify their data model definitions.
- There is also a flow of events throughout the architecture: domain commands trigger changes which produce domain events that are then persisted via one of the event stores (in-memory or Postgres).

##### Architectural patterns and design principles
- Event Sourcing Pattern: The library encapsulates the event sourcing pattern, storing immutable events rather than direct state changes.
- Separation of Concerns: Different crates isolate core functionality, macro expansions, and data persistence.
- Extensibility: Offering multiple backends (in-memory and Postgres) suggests that the design is modular and pluggable.
- Domain-Driven Design (DDD): The use of aggregates, commands, events, and queries reflects DDD principles, and the bank-accounting example further illustrates these concepts.

##### Relevant technologies, frameworks, or libraries
- Rust and Cargo as the core language and build system.
- PostgreSQL for one of the event store implementations.
- GitHub Actions for continuous integration and tests.
- Docker Compose in the bank-accounting example, which might be used for local service orchestration in a demo or development environment.

– Core Library (eventually)
– Event Store Implementations
- InMemory Store (inside eventually)
- PostgreSQL Store (eventually-postgres)
– Macros (eventually-macros)
– Example Application (bank-accounting) demonstrating integration
– API calls from the bank-accounting example into the core library.
– Interactions between the core library and the event store (both the in-memory and PostgreSQL implementations).
– How the macros integrate with or wrap parts of the core functionality.
- Labels that clearly indicate each component’s purpose (e.g., “Event Store Abstraction”, “Domain Modeling via Macros”, “Event Persistence Layer (PostgreSQL)”, “Application Example”).
– Library code versus deployment tools/configurations.
– Abstraction layers (domain logic versus persistence or helper macros).
- A clear separation of concerns that visually distinguishes the pluggable backend implementations from the core event sourcing API.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Core Abstraction"
        A["Core Library\n(eventually)"]:::core
        D["Macros\n(eventually-macros)"]:::macros
    end

    subgraph "Event Store Implementations"
        B["InMemory Event Store"]:::store
        C["PostgreSQL Event Store & Aggregate Repository"]:::store
    end

    E["Example Application\n(bank-accounting)"]:::example

    E -->|"uses"| A
    E -->|"utilizes_macros"| D
    D -->|"enhances"| A
    A -->|"persists_in"| B
    A -->|"persists_in"| C

    click A "https://github.com/get-eventually/eventually-rs/tree/main/eventually/"
    click B "https://github.com/get-eventually/eventually-rs/blob/main/eventually/src/event/store.rs"
    click C "https://github.com/get-eventually/eventually-rs/tree/main/eventually-postgres/"
    click D "https://github.com/get-eventually/eventually-rs/blob/main/eventually-macros/src/lib.rs"
    click E "https://github.com/get-eventually/eventually-rs/tree/main/examples/bank-accounting/"

    classDef core fill:#f9e6ff,stroke:#6a0dad,stroke-width:2px;
    classDef store fill:#d0e5ff,stroke:#0055ff,stroke-width:2px;
    classDef macros fill:#e6ffe6,stroke:#2d862d,stroke-width:2px;
    classDef example fill:#fff4db,stroke:#ff8c00,stroke-width:2px;
```
