👁 Image
Cratis.Chronicle.XUnit.Integration 15.34.11

<div align="center"> <a href="https://cratis.io"> <img src="full-logo.png" alt="Cratis Chronicle" width="480"> </a>

<h3 align="center">Cratis Chronicle</h3>

<p align="center"> An Event Sourcing database for .NET — built with ease of use, productivity, compliance, and maintainability in mind. <br /> <a href="https://cratis.io"><strong>Explore the docs »</strong></a> <br /> <br /> <a href="https://github.com/cratis/samples">View Samples</a>  ·  <a href="https://github.com/cratis/chronicle/issues/new?labels=bug">Report a Bug</a>  ·  <a href="https://github.com/cratis/chronicle/issues/new?labels=enhancement">Request a Feature</a>  ·  <a href="https://discord.gg/kt4AMpV8WV">Join the Discord</a> </p>

<p align="center"> <a href="https://discord.gg/kt4AMpV8WV"> <img src="https://img.shields.io/discord/1182595891576717413?label=Discord&logo=discord&color=7289da" alt="Discord"> </a> <a href="http://nuget.org/packages/cratis.chronicle"> <img src="https://img.shields.io/nuget/v/Cratis.Chronicle?logo=nuget" alt="NuGet"> </a> <a href="https://hub.docker.com/r/cratis/chronicle"> <img src="https://img.shields.io/docker/v/cratis/chronicle?label=Chronicle&logo=docker&sort=semver" alt="Docker"> </a> <a href="https://github.com/Cratis/Chronicle/actions/workflows/dotnet-build.yml"> <img src="https://github.com/cratis/Chronicle/actions/workflows/dotnet-build.yml/badge.svg" alt="C# Build"> </a> <a href="https://github.com/Cratis/Chronicle/actions/workflows/publish.yml"> <img src="https://github.com/cratis/Chronicle/actions/workflows/publish.yml/badge.svg" alt="Publish"> </a> <a href="https://github.com/Cratis/Documentation/actions/workflows/pages.yml"> <img src="https://github.com/Cratis/Documentation/actions/workflows/pages.yml/badge.svg" alt="Documentation site"> </a> </p> </div>

📖 Table of Contents

• 📖 Table of Contents
• 🧭 About
• ✨ Key Features
  • 🏗️ Event Sourcing Foundation
  • 🎯 Real-time Processing
  • 🛡️ Enterprise Ready
  • 🚀 Developer Experience
• 🚀 Getting Started
  • Prerequisites
  • Installation
  • Quick Example
    • ASP.NET Core setup (Program.cs)
    • Define events
    • Append events
    • React to events (Reactor)
    • Build read models (Reducer)
    • Declarative projections
• 🏛️ Architecture
• 📚 Documentation
• 🤝 Contributing
• 💬 Support
• 📊 Repository Stats
• 📄 License
• 🙏 Acknowledgements

🧭 About

Cratis Chronicle is an Event Sourcing database that captures every state change in your system as an immutable sequence of events — rather than storing only the current state. This unlocks powerful capabilities like full audit trails, time-travel debugging, and event-driven architectures without the usual complexity.

Chronicle ships with:

• 🖥️ Chronicle Kernel — the server that manages event storage, processing, and querying
• 📦 .NET Client SDK — a rich C# library for interacting with Chronicle from any .NET application
• 🌐 Web Workbench — a built-in management dashboard for monitoring, browsing events, and administration
• 🗄️ MongoDB Backend — optimized storage layer with an extensible model for other data stores

For core values and principles, read our core values and principles.

✨ Key Features

🏗️ Event Sourcing Foundation

🎯 Real-time Processing

🛡️ Enterprise Ready

🚀 Developer Experience

🚀 Getting Started

Prerequisites

• .NET 8+
• Docker (to run Chronicle)

Installation

Note: The latest-development Chronicle image bundles both Chronicle and MongoDB in a single container — no separate database setup needed.

Option 1 — Docker CLI:

docker run -d --name chronicle \
 -p 35000:35000 \
 -p 8080:8080 \
 cratis/chronicle:latest-development

Option 2 — Docker Compose:

services:
 chronicle:
 image: cratis/chronicle:latest-development
 ports:
 - "35000:35000" # gRPC / API
 - "8080:8080" # Web Workbench

docker compose up -d

Add the NuGet package to your .NET project:

# ASP.NET Core
dotnet add package Cratis.Chronicle.AspNetCore

# Console / Worker Service
dotnet add package Cratis.Chronicle

Quick Example

ASP.NET Core setup (Program.cs)

var builder = WebApplication.CreateBuilder(args)
 .AddCratisChronicle(options => options.EventStore = "MyApp");

var app = builder.Build();
app.UseCratisChronicle();
app.Run();

Define events

[EventType]
public record UserOnboarded(string Name, string Email);

[EventType]
public record BookAddedToInventory(string Title, string Author, string ISBN);

Append events

// Inject IEventLog or grab it from the event store
await eventLog.Append(Guid.NewGuid(), new UserOnboarded("Jane Doe", "jane@example.com"));
await eventLog.Append(Guid.NewGuid(), new BookAddedToInventory("Domain-Driven Design", "Eric Evans", "978-0321125217"));

React to events (Reactor)

public class UserNotifier : IReactor
{
 public async Task Onboarded(UserOnboarded @event, EventContext context)
 {
 // send welcome email, provision resources, etc.
 Console.WriteLine($"Welcome, {@event.Name}!");
 }
}

Build read models (Reducer)

public class BooksReducer : IReducerFor<Book>
{
 public Task<Book> Added(BookAddedToInventory @event, Book? current, EventContext context) =>
 Task.FromResult(new Book(
 Guid.Parse(context.EventSourceId),
 @event.Title,
 @event.Author,
 @event.ISBN));
}

Declarative projections

public class BorrowedBooksProjection : IProjectionFor<BorrowedBook>
{
 public void Define(IProjectionBuilderFor<BorrowedBook> builder) => builder
 .From<BookBorrowed>(from => from
 .Set(m => m.UserId).To(e => e.UserId)
 .Set(m => m.Borrowed).ToEventContextProperty(c => c.Occurred))
 .Join<BookAddedToInventory>(b => b
 .On(m => m.Id)
 .Set(m => m.Title).To(e => e.Title))
 .RemovedWith<BookReturned>();
}

Full working samples are available in the Samples repository.

🏛️ Architecture

┌──────────────────────────────────────────────────────────┐
│ Your .NET Application │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Events · Reactors · Reducers · Projections │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ Chronicle Client SDK │
└─────────────────────────────┬────────────────────────────┘
 │ gRPC
┌─────────────────────────────┴────────────────────────────┐
│ Chronicle Kernel │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────┐ │
│ │ Event Store │ │ Projection │ │ Web │ │
│ │ (MongoDB) │ │ Engine │ │ Workbench │ │
│ └────────────────┘ └────────────────┘ └────────────┘ │
└──────────────────────────────────────────────────────────┘

Chronicle follows a client-server model:

📚 Documentation

Full documentation is available at https://cratis.io.

🤝 Contributing

Contributions are what make the open-source community an amazing place to learn, inspire, and create. Any contribution you make is greatly appreciated!

1. Fork the repository
2. Create a feature branch: git checkout -b feature/AmazingFeature
3. Commit your changes: git commit -m 'Add some AmazingFeature'
4. Push to the branch: git push origin feature/AmazingFeature
5. Open a Pull Request

Looking for a good first issue? Check out the contribute page.

For detailed build and development instructions, see the .

You can also browse the code directly in your browser: 👁 Open in VSCode

💬 Support

📊 Repository Stats

📄 License

Distributed under the MIT License. See for full details.

🙏 Acknowledgements

• MongoDB — the default storage backend powering Chronicle
• Microsoft Orleans — distributed actor framework used in the Chronicle Kernel
• Louis3797/awesome-readme-template — README inspiration
• All our contributors and the open-source community ❤️