# j-tech-japan/sekiban architecture

> Architecture diagram of the GitHub repository j-tech-japan/sekiban, 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/j-tech-japan/sekiban
- Repository: https://github.com/j-tech-japan/sekiban

## Overview

##### Main Components
- Framework Core (Domain and Event Sourcing Engine):
– Components handling aggregates, commands, events, projections, queries, and serializations.
– Modules included under src/Sekiban.Pure (e.g., Aggregates, Commands, Events, Exceptions, Projectors, Repositories, Serialization, etc.).
- Orleans-Enabled Modules:
– The Orleans implementation (src/Sekiban.Pure.Orleans and related surrogates, grains, partitions, executor parts).
– Key components like Grain interfaces and classes (e.g., AggregateEventHandlerGrain, AggregateProjectorGrain, MultiProjectorGrain) that implement event processing and projection.
- Persistence/Infrastructure Providers:
– CosmosDb support (src/Sekiban.Pure.CosmosDb) with event writers/readers, partition generators and cache accessors.
– Postgres support (src/Sekiban.Pure.Postgres) including migrations, context factories, and database event writers/readers.
– Additional providers/tools may be seen for other storage solutions.
- API and Application Hosts:
– API services and AppHost projects (as seen in Samples/AspireEventSample and internalUsages/OrleansSekiban.ApiService/AppHost) that expose endpoints and support HTTP, likely in ASP.NET Core.
- Testing and Templates:
– NUnit/xUnit projects and samples (src/Sekiban.Pure.NUnit, src/Sekiban.Pure.Orleans.xUnit, tests/ directories) to indicate the testing framework and examples for integration tests.
– Template projects and documentation utilities (found in the templates/ folder, docfx documentation resources) for scaffolding new implementations and generating documentation.
- Auxiliary Tools:
– Tools like “ConvertAndCopyCosmosItems” demonstrating how events might be transformed or copied.
– Memory-stat module in src/MemStat.Net – possibly not directly part of the core framework but included for monitoring or auxiliary diagnostic functionality.

##### Relationships and Interactions
- A layered structure where the Domain Core (Commands, Events, Aggregates) sits at the center.
- Directional flows:
– Commands enter the system via API Services/AppHost; these feed into the framework’s command executor.
– Events are generated by aggregates and are written to the Event Store using different providers.
– Projections and Query components read from the stored events; these might be updated on demand or via Orleans grains.
– Orleans grains interact with the framework core, ensuring scalability by handling aggregate commands and event delivery using the actor model.
- Supporting flows for testing and configuration:
– Testing modules can be shown interacting with almost every layer via mock/external interfaces.
– The templates and tooling support the generation of proper projects that follow the same architectural layout.

##### Architectural Patterns / Design Principles
- Use of CQRS (Command Query Responsibility Segregation) separating the write (command/aggregate handling) and read (projections/query processing) models.
- Event Sourcing: every change is captured as an event that can then be used to rebuild aggregate state.
- Orleans (actor model) is used to increase scalability and support concurrent multi-threaded operations.
- Dependency inversion and modularization: each infrastructure module (Cosmos, Postgres, etc.) is a plug-in that can be configured with the core business logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "API/Application Layer"
        API1["API Service: AspireEventSample"]:::api
        API2["API Service: OrleansSekiban.ApiService"]:::api
    end

    subgraph "Domain Layer"
        CORE["Framework Core\n(Aggregates,Commands,Events,Projections)"]:::domain
    end

    subgraph "Orleans Grain Layer"
        GRAIN["Orleans Grains\n(Handlers & Projectors)"]:::orleans
    end

    subgraph "Persistence Infrastructure"
        COSMOS["Cosmos DB Provider"]:::infra
        POSTGRES["Postgres Provider"]:::infra
    end

    subgraph "Testing & Tooling"
        TEST_NUnit["NUnit Tests"]:::testing
        TEST_Orleans_xUnit["Orleans xUnit Tests"]:::testing
        TEST_Domain_Test["Domain Tests"]:::testing
        TEST_Domain_xUnit["Domain xUnit Tests"]:::testing
        TEMPLATES["Templates & Documentation"]:::tool
        AUX["Auxiliary Tools"]:::tool
    end

    %% Connections between Layers
    API1 -->|"CommandDispatch"| CORE
    API2 -->|"CommandDispatch"| CORE

    CORE -->|"EventEmission"| COSMOS
    CORE -->|"EventEmission"| POSTGRES
    CORE -->|"TriggerProjection"| GRAIN

    COSMOS -->|"ProjectionUpdate"| GRAIN
    POSTGRES -->|"ProjectionUpdate"| GRAIN

    GRAIN -->|"QueryResponse"| API1
    GRAIN -->|"QueryResponse"| API2

    %% Testing interactions
    TEST_NUnit -->|"Validates"| CORE
    TEST_Orleans_xUnit -->|"Validates"| GRAIN
    TEST_Domain_Test -->|"Validates"| CORE
    TEST_Domain_xUnit -->|"Validates"| CORE

    TEMPLATES -->|"Scaffolds"| CORE
    AUX -->|"TransformsEvents"| COSMOS

    %% Styles
    classDef domain fill:#ccf,stroke:#333,stroke-width:2px;
    classDef api fill:#ff9,stroke:#333,stroke-width:2px;
    classDef orleans fill:#9f9,stroke:#333,stroke-width:2px;
    classDef infra fill:#f99,stroke:#333,stroke-width:2px;
    classDef testing fill:#d9b3ff,stroke:#333,stroke-width:2px;
    classDef tool fill:#fc9,stroke:#333,stroke-width:2px;

    class CORE domain;
    class API1,API2 api;
    class GRAIN orleans;
    class COSMOS,POSTGRES infra;
    class TEST_NUnit,TEST_Orleans_xUnit,TEST_Domain_Test,TEST_Domain_xUnit testing;
    class TEMPLATES,AUX tool;

    %% Click Events
    click CORE "https://github.com/j-tech-japan/sekiban/blob/main/src/Sekiban.Pure"
    click GRAIN "https://github.com/j-tech-japan/sekiban/blob/main/src/Sekiban.Pure.Orleans"
    click COSMOS "https://github.com/j-tech-japan/sekiban/blob/main/src/Sekiban.Pure.CosmosDb"
    click POSTGRES "https://github.com/j-tech-japan/sekiban/blob/main/src/Sekiban.Pure.Postgres"
    click API1 "https://github.com/j-tech-japan/sekiban/blob/main/Samples/Tutorials/AspireEventSample/AspireEventSample.ApiService"
    click API2 "https://github.com/j-tech-japan/sekiban/blob/main/internalUsages/OrleansSekiban.ApiService"
    click TEST_NUnit "https://github.com/j-tech-japan/sekiban/blob/main/src/Sekiban.Pure.NUnit"
    click TEST_Orleans_xUnit "https://github.com/j-tech-japan/sekiban/blob/main/src/Sekiban.Pure.Orleans.xUnit"
    click TEST_Domain_Test "https://github.com/j-tech-japan/sekiban/blob/main/tests/Pure.Domain.Test"
    click TEST_Domain_xUnit "https://github.com/j-tech-japan/sekiban/blob/main/tests/Pure.Domain.xUnit"
    click TEMPLATES "https://github.com/j-tech-japan/sekiban/blob/main/templates/Sekiban.Pure.Templates"
    click TEMPLATES "https://github.com/j-tech-japan/sekiban/tree/main/docs/docfx_project"
    click AUX "https://github.com/j-tech-japan/sekiban/tree/main/tools/ConvertAndCopyCosmosItems"
```
