# jasperfx/marten architecture

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

- Interactive diagram: https://gitdiagram.com/jasperfx/marten
- Repository: https://github.com/jasperfx/marten

## Overview

Marten is a .NET document database and event store backed by PostgreSQL. The main user workflow is to open a session, store or query documents, and commit or receive results; event-stream operations and projections provide a parallel event-sourcing workflow. The graph also shows query-handler and storage internals evidenced by sampled source. README capabilities such as async projections, subscriptions, and tenancy are included at subsystem level; their implementation wiring was not sampled, so those links are intentionally limited.

Main entry points: [`src/Marten/Linq/Parsing/LinqQueryParser.Handlers.cs`](https://github.com/jasperfx/marten/blob/master/src/Marten/Linq/Parsing/LinqQueryParser.Handlers.cs) (LINQ parsing), [`src/Marten`](https://github.com/jasperfx/marten/tree/master/src/Marten) (Sessions and store), [`src/Marten/Internal/Sessions/DocumentSessionBase.ProjectionStorage.cs`](https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/Sessions/DocumentSessionBase.ProjectionStorage.cs) (Document operations), [`src/Marten/Internal/ClosedShape/QueryOnlyClosedShapeStorage.cs`](https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/ClosedShape/QueryOnlyClosedShapeStorage.cs) (Closed-shape storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_documents["Document database"]
  node_sessions["Sessions and store"]
  node_docops["Document operations"]
  node_docmeta["Document metadata"]
  node_patching["Native patching"]
  node_tenancy["Multi-tenancy"]
end

subgraph group_events["Event sourcing"]
  node_eventstore["Event store"]
  node_streamstate["Stream state"]
  node_projections["Event projections"]
  node_asyncdaemon["Async daemon"]
  node_subscriptions["Subscriptions"]
end

subgraph group_query["Query execution"]
  node_linq["LINQ parsing"]
  node_advancedsql["Advanced SQL"]
  node_includes["Include handling"]
  node_compiled["Compiled queries"]
end

subgraph group_runtime["Storage runtime"]
  node_queryonly["Read-only storage"]
  node_closedshape["Closed-shape storage"]
  node_projectionstorage["Projection storage"]
  node_eventquery["Single-event query"]
end

node_developer(("Application code"))
node_postgres[("PostgreSQL")]

node_developer -->|"opens session"| node_sessions
node_sessions -->|"queues operations"| node_docops
node_docops -->|"persists documents"| node_postgres
node_sessions -->|"builds queries"| node_linq
node_linq -->|"wraps handler"| node_includes
node_linq -->|"builds handler"| node_advancedsql
node_includes -->|"delegates results"| node_linq
node_advancedsql -->|"executes SQL"| node_postgres
node_docmeta -->|"reads metadata"| node_postgres
node_queryonly -->|"loads documents"| node_postgres
node_closedshape -->|"specializes storage"| node_queryonly
node_closedshape -->|"builds selector"| node_sessions
node_projectionstorage -->|"queues writes"| node_docops
node_developer -->|"queries events"| node_eventstore
node_eventstore -->|"reads event"| node_postgres
node_developer -->|"requests stream state"| node_streamstate
node_streamstate -->|"queries stream"| node_postgres
node_compiled -->|"binds query parameters"| node_linq
node_projections -->|"processed by"| node_asyncdaemon
node_asyncdaemon -->|"reads and writes"| node_postgres
node_subscriptions -.->|"processed by"| node_asyncdaemon
node_patching -->|"updates documents"| node_postgres
node_tenancy -->|"scopes storage"| node_postgres

click node_sessions "https://github.com/jasperfx/marten/tree/master/src/Marten"
click node_docops "https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/Sessions/DocumentSessionBase.ProjectionStorage.cs"
click node_docmeta "https://github.com/jasperfx/marten/blob/master/src/Marten/Storage/Metadata/EntityMetadataQueryHandler.cs"
click node_patching "https://github.com/jasperfx/marten/tree/master/src/Marten"
click node_tenancy "https://github.com/jasperfx/marten/tree/master/src/Marten"
click node_eventstore "https://github.com/jasperfx/marten/blob/master/src/Marten/Events/Querying/SingleEventQueryHandler.cs"
click node_streamstate "https://github.com/jasperfx/marten/blob/master/src/Marten/EventStorage/Querying/ClosedShapeStreamStateQueryHandler.cs"
click node_projections "https://github.com/jasperfx/marten/tree/master/src/Marten"
click node_asyncdaemon "https://github.com/jasperfx/marten/tree/master/src/Marten"
click node_subscriptions "https://github.com/jasperfx/marten/tree/master/src/Marten"
click node_linq "https://github.com/jasperfx/marten/blob/master/src/Marten/Linq/Parsing/LinqQueryParser.Handlers.cs"
click node_advancedsql "https://github.com/jasperfx/marten/blob/master/src/Marten/Linq/QueryHandlers/AdvancedSqlQueryHandler.cs"
click node_includes "https://github.com/jasperfx/marten/blob/master/src/Marten/Linq/Includes/IncludeQueryHandler.cs"
click node_compiled "https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/CompiledQueries/CompiledQueryHandlerDescriptor.cs"
click node_queryonly "https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/Storage/QueryOnlyDocumentStorage.cs"
click node_closedshape "https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/ClosedShape/QueryOnlyClosedShapeStorage.cs"
click node_projectionstorage "https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/Sessions/DocumentSessionBase.ProjectionStorage.cs"
click node_eventquery "https://github.com/jasperfx/marten/blob/master/src/Marten/Events/Querying/SingleEventQueryHandler.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_sessions,node_docops,node_docmeta,node_patching,node_tenancy toneBlue
class node_eventstore,node_streamstate,node_projections,node_asyncdaemon,node_subscriptions,node_postgres toneAmber
class node_linq,node_advancedsql,node_includes,node_compiled toneMint
class node_queryonly,node_closedshape,node_projectionstorage,node_eventquery toneRose
class node_developer toneIndigo
```

## Components

### Document database

- [Sessions and store](https://github.com/jasperfx/marten/tree/master/src/Marten): `src/Marten`
- [Document operations](https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/Sessions/DocumentSessionBase.ProjectionStorage.cs): `src/Marten/Internal/Sessions/DocumentSessionBase.ProjectionStorage.cs`
- [Document metadata](https://github.com/jasperfx/marten/blob/master/src/Marten/Storage/Metadata/EntityMetadataQueryHandler.cs): `src/Marten/Storage/Metadata/EntityMetadataQueryHandler.cs`
- [Native patching](https://github.com/jasperfx/marten/tree/master/src/Marten): `src/Marten`
- [Multi-tenancy](https://github.com/jasperfx/marten/tree/master/src/Marten): `src/Marten`

### Event sourcing

- [Event store](https://github.com/jasperfx/marten/blob/master/src/Marten/Events/Querying/SingleEventQueryHandler.cs): `src/Marten/Events/Querying/SingleEventQueryHandler.cs`
- [Stream state](https://github.com/jasperfx/marten/blob/master/src/Marten/EventStorage/Querying/ClosedShapeStreamStateQueryHandler.cs): `src/Marten/EventStorage/Querying/ClosedShapeStreamStateQueryHandler.cs`
- [Event projections](https://github.com/jasperfx/marten/tree/master/src/Marten): `src/Marten`
- [Async daemon](https://github.com/jasperfx/marten/tree/master/src/Marten): `src/Marten`
- [Subscriptions](https://github.com/jasperfx/marten/tree/master/src/Marten): `src/Marten`

### Query execution

- [LINQ parsing](https://github.com/jasperfx/marten/blob/master/src/Marten/Linq/Parsing/LinqQueryParser.Handlers.cs): `src/Marten/Linq/Parsing/LinqQueryParser.Handlers.cs`
- [Advanced SQL](https://github.com/jasperfx/marten/blob/master/src/Marten/Linq/QueryHandlers/AdvancedSqlQueryHandler.cs): `src/Marten/Linq/QueryHandlers/AdvancedSqlQueryHandler.cs`
- [Include handling](https://github.com/jasperfx/marten/blob/master/src/Marten/Linq/Includes/IncludeQueryHandler.cs): `src/Marten/Linq/Includes/IncludeQueryHandler.cs`
- [Compiled queries](https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/CompiledQueries/CompiledQueryHandlerDescriptor.cs): `src/Marten/Internal/CompiledQueries/CompiledQueryHandlerDescriptor.cs`

### Storage runtime

- [Read-only storage](https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/Storage/QueryOnlyDocumentStorage.cs): `src/Marten/Internal/Storage/QueryOnlyDocumentStorage.cs`
- [Closed-shape storage](https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/ClosedShape/QueryOnlyClosedShapeStorage.cs): `src/Marten/Internal/ClosedShape/QueryOnlyClosedShapeStorage.cs`
- [Projection storage](https://github.com/jasperfx/marten/blob/master/src/Marten/Internal/Sessions/DocumentSessionBase.ProjectionStorage.cs): `src/Marten/Internal/Sessions/DocumentSessionBase.ProjectionStorage.cs`
- [Single-event query](https://github.com/jasperfx/marten/blob/master/src/Marten/Events/Querying/SingleEventQueryHandler.cs): `src/Marten/Events/Querying/SingleEventQueryHandler.cs`

### Other components

- **Application code**
- **PostgreSQL**

## Connections

- Application code → Sessions and store: opens session
- Sessions and store → Document operations: queues operations
- Document operations → PostgreSQL: persists documents
- Sessions and store → LINQ parsing: builds queries
- LINQ parsing → Include handling: wraps handler
- LINQ parsing → Advanced SQL: builds handler
- Include handling → LINQ parsing: delegates results
- Advanced SQL → PostgreSQL: executes SQL
- Document metadata → PostgreSQL: reads metadata
- Read-only storage → PostgreSQL: loads documents
- Closed-shape storage → Read-only storage: specializes storage
- Closed-shape storage → Sessions and store: builds selector
- Projection storage → Document operations: queues writes
- Application code → Event store: queries events
- Event store → PostgreSQL: reads event
- Application code → Stream state: requests stream state
- Stream state → PostgreSQL: queries stream
- Compiled queries → LINQ parsing: binds query parameters
- Event projections → Async daemon: processed by
- Async daemon → PostgreSQL: reads and writes
- Subscriptions → Async daemon: processed by
- Native patching → PostgreSQL: updates documents
- Multi-tenancy → PostgreSQL: scopes storage