# asos/simpleeventstore architecture

> Architecture diagram of the GitHub repository asos/simpleeventstore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asos/simpleeventstore
- Repository: https://github.com/asos/simpleeventstore

## Overview

Simple Event Store is a lightweight event-sourcing library. A caller creates EventData and uses EventStore to append it to, or read it from, a stream; EventStore delegates persistence to an IStorageEngine. The repository provides in-memory and Azure Cosmos DB engines, with Cosmos-specific configuration, event serialization, and operation logging. The README documents forward reads, optimistic concurrency, and engine setup. Cosmos engine behavior is excerpted; other links are included only where the README or source index supports them.

Main entry points: [`src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs`](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs) (Cosmos Engine), [`src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs`](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs) (Cosmos Builder), [`src/SimpleEventStore/SimpleEventStore/IStorageEngine.cs`](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/IStorageEngine.cs) (Storage Contract), [`src/SimpleEventStore/SimpleEventStore/EventStore.cs`](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/EventStore.cs) (EventStore API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Event Store Core"]
  node_eventstore["EventStore API<br/>[EventStore.cs]"]
  node_eventdata["Event Data<br/>[EventData.cs]"]
  node_storageevent["Stored Event<br/>[StorageEvent.cs]"]
  node_enginecontract["Storage Contract<br/>[IStorageEngine.cs]"]
  node_concurrency["Concurrency Error"]
end

subgraph group_engines["Persistence Engines"]
  node_memoryengine[("In-Memory Engine")]
end

subgraph group_cosmos["Cosmos Integration"]
  node_cosmosbuilder["Cosmos Builder"]
  node_cosmosengine["Cosmos Engine"]
  node_cosmosdb[("Azure Cosmos DB")]
  node_cosmosevent["Cosmos Event Document"]
  node_typemap["Type Mapping"]
  node_typemapcontract["Type Map Contract"]
  node_defaulttypemap["Default Type Map"]
  node_jsonserializer["JSON Serializer"]
  node_options["Database Options<br/>[DatabaseOptions.cs]"]
  node_collection["Collection Options"]
  node_logging["Operation Logging<br/>[LoggingOptions.cs]"]
  node_responseinfo["Response Details"]
end

node_caller(("Application"))

node_caller -->|"uses"| node_eventstore
node_caller -->|"creates"| node_eventdata
node_eventstore -->|"delegates persistence"| node_enginecontract
node_eventstore -->|"accepts"| node_eventdata
node_eventstore -->|"creates"| node_storageevent
node_enginecontract -->|"transfers"| node_storageevent
node_memoryengine -->|"implements"| node_enginecontract
node_memoryengine -->|"throws on conflict"| node_concurrency
node_cosmosbuilder -->|"builds"| node_cosmosengine
node_cosmosbuilder -->|"returns"| node_enginecontract
node_cosmosengine -->|"implements"| node_enginecontract
node_cosmosengine -->|"reads and writes"| node_cosmosdb
node_cosmosengine -->|"converts events"| node_cosmosevent
node_cosmosevent -->|"resolves types"| node_typemapcontract
node_cosmosevent -->|"reconstructs"| node_eventdata
node_cosmosbuilder -->|"configures"| node_typemapcontract
node_cosmosbuilder -->|"defaults to"| node_defaulttypemap
node_cosmosbuilder -->|"configures"| node_options
node_cosmosbuilder -->|"configures"| node_collection
node_cosmosengine -->|"uses"| node_options
node_cosmosengine -->|"uses"| node_collection
node_cosmosengine -->|"reports operations"| node_logging
node_cosmosengine -->|"builds details"| node_responseinfo
node_cosmosevent -->|"serializes payloads"| node_jsonserializer

click node_eventstore "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/EventStore.cs"
click node_eventdata "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/EventData.cs"
click node_storageevent "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/StorageEvent.cs"
click node_enginecontract "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/IStorageEngine.cs"
click node_concurrency "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/ConcurrencyException.cs"
click node_memoryengine "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/InMemory/InMemoryStorageEngine.cs"
click node_cosmosbuilder "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs"
click node_cosmosengine "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs"
click node_cosmosevent "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/CosmosDbStorageEvent.cs"
click node_typemap "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/ConfigurableSerializationTypeMap.cs"
click node_typemapcontract "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/ISerializationTypeMap.cs"
click node_defaulttypemap "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/DefaultSerializationTypeMap.cs"
click node_jsonserializer "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/JsonNetCosmosSerializer.cs"
click node_options "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/DatabaseOptions.cs"
click node_collection "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/CollectionOptions.cs"
click node_logging "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/LoggingOptions.cs"
click node_responseinfo "https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/ResponseInformation.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_eventstore,node_eventdata,node_storageevent,node_enginecontract,node_concurrency toneBlue
class node_memoryengine toneAmber
class node_cosmosbuilder,node_cosmosengine,node_cosmosdb,node_cosmosevent,node_typemap,node_typemapcontract,node_defaulttypemap,node_jsonserializer,node_options,node_collection,node_logging,node_responseinfo toneMint
class node_caller toneIndigo
```

## Components

### Event Store Core

- [EventStore API](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/EventStore.cs): `src/SimpleEventStore/SimpleEventStore/EventStore.cs`
- [Event Data](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/EventData.cs): `src/SimpleEventStore/SimpleEventStore/EventData.cs`
- [Stored Event](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/StorageEvent.cs): `src/SimpleEventStore/SimpleEventStore/StorageEvent.cs`
- [Storage Contract](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/IStorageEngine.cs): `src/SimpleEventStore/SimpleEventStore/IStorageEngine.cs`
- [Concurrency Error](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/ConcurrencyException.cs): `src/SimpleEventStore/SimpleEventStore/ConcurrencyException.cs`

### Persistence Engines

- [In-Memory Engine](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore/InMemory/InMemoryStorageEngine.cs): `src/SimpleEventStore/SimpleEventStore/InMemory/InMemoryStorageEngine.cs`

### Cosmos Integration

- [Cosmos Builder](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs`
- [Cosmos Engine](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs`
- **Azure Cosmos DB**
- [Cosmos Event Document](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/CosmosDbStorageEvent.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/CosmosDbStorageEvent.cs`
- [Type Mapping](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/ConfigurableSerializationTypeMap.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/ConfigurableSerializationTypeMap.cs`
- [Type Map Contract](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/ISerializationTypeMap.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/ISerializationTypeMap.cs`
- [Default Type Map](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/DefaultSerializationTypeMap.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/DefaultSerializationTypeMap.cs`
- [JSON Serializer](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/JsonNetCosmosSerializer.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/JsonNetCosmosSerializer.cs`
- [Database Options](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/DatabaseOptions.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/DatabaseOptions.cs`
- [Collection Options](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/CollectionOptions.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/CollectionOptions.cs`
- [Operation Logging](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/LoggingOptions.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/LoggingOptions.cs`
- [Response Details](https://github.com/asos/simpleeventstore/blob/main/src/SimpleEventStore/SimpleEventStore.CosmosDb/ResponseInformation.cs): `src/SimpleEventStore/SimpleEventStore.CosmosDb/ResponseInformation.cs`

### Other components

- **Application**

## Connections

- Application → EventStore API: uses
- Application → Event Data: creates
- EventStore API → Storage Contract: delegates persistence (evidence: `src/SimpleEventStore/SimpleEventStore/EventStore.cs`)
- EventStore API → Event Data: accepts (evidence: `src/SimpleEventStore/SimpleEventStore/EventStore.cs`)
- EventStore API → Stored Event: creates (evidence: `src/SimpleEventStore/SimpleEventStore/EventStore.cs`)
- Storage Contract → Stored Event: transfers (evidence: `src/SimpleEventStore/SimpleEventStore/IStorageEngine.cs`)
- In-Memory Engine → Storage Contract: implements (evidence: `src/SimpleEventStore/SimpleEventStore/InMemory/InMemoryStorageEngine.cs`)
- In-Memory Engine → Concurrency Error: throws on conflict (evidence: `src/SimpleEventStore/SimpleEventStore/InMemory/InMemoryStorageEngine.cs`)
- Cosmos Builder → Cosmos Engine: builds (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs`)
- Cosmos Builder → Storage Contract: returns (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs`)
- Cosmos Engine → Storage Contract: implements (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs`)
- Cosmos Engine → Azure Cosmos DB: reads and writes (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs`)
- Cosmos Engine → Cosmos Event Document: converts events (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs`)
- Cosmos Event Document → Type Map Contract: resolves types (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/CosmosDbStorageEvent.cs`)
- Cosmos Event Document → Event Data: reconstructs (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/CosmosDbStorageEvent.cs`)
- Cosmos Builder → Type Map Contract: configures (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs`)
- Cosmos Builder → Default Type Map: defaults to (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs`)
- Cosmos Builder → Database Options: configures (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs`)
- Cosmos Builder → Collection Options: configures (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngineBuilder.cs`)
- Cosmos Engine → Database Options: uses (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs`)
- Cosmos Engine → Collection Options: uses (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs`)
- Cosmos Engine → Operation Logging: reports operations (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs`)
- Cosmos Engine → Response Details: builds details (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/AzureCosmosDbStorageEngine.cs`)
- Cosmos Event Document → JSON Serializer: serializes payloads (evidence: `src/SimpleEventStore/SimpleEventStore.CosmosDb/CosmosDbStorageEvent.cs`)
