Cratis Chronicle

Cratis Chronicle is an open-source (MIT) event-sourcing database and runtime for applications that need a history of meaningful changes. Record application changes as events, build queryable views with declarative projections, and react to events from .NET, TypeScript, Kotlin/Java, or Elixir.
Explore the docs »

View Samples  ·  Report a Bug  ·  Request a Feature  ·  Join the Discord

• 📑 Table of Contents
• 📖 About
• ✨ Key Features
  • 🧱 Event Sourcing Foundation
  • ⚡ Real-time Processing
  • 🔒 Data Integrity & Compliance
  • 💻 Developer Experience
• 🌍 Clients
• 🚀 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
• 🧩 The Cratis ecosystem
• 🤝 Contributing
• 💬 Support
• 📊 Repository Stats
• 📄 License
• 🙏 Acknowledgements

Cratis Chronicle is an event-sourcing database and processing runtime for applications that need to retain meaningful changes, not just current state. You append facts such as OrderPlaced to an event log. That history lets you inspect how an order changed and build new views from the events your application recorded.

Chronicle's declarative projections map events onto read models, views shaped for the queries your application serves. The kernel handles processing and storage updates. Reactors run your code when events arrive, for example to send a notification. Materialized views update after the append, so choose the consistency behavior your workflow needs.

For personal data, Chronicle encrypts fields marked as personally identifiable information (PII) under a subject's key and supports erasing that key without removing the event's position in the log. These mechanisms support your compliance work; they do not make an application compliant by themselves. Read Compliance before recording personal data.

The Orleans-based .NET kernel has a first-class .NET SDK and additional TypeScript, Kotlin/Java (JVM), and Elixir clients; a Python client is coming soon. Storage providers include MongoDB (default), PostgreSQL, SQL Server, SQLite, and in-memory implementations. Client and provider capabilities differ, so use the guide for your chosen setup. Chronicle and its bundled web workbench run without Studio, Arc, or Components. Chronicle is free to use and MIT licensed; free AI skills are also available for working with the code and documentation.

Chronicle ships with:

• ⚙️ Chronicle Kernel — the server that manages event storage, processing, and querying, built on Microsoft Orleans for distributed, stateful processing
• 🧩 .NET Client SDK — a rich C# library for interacting with Chronicle from any .NET application
• 🌍 Language-agnostic gRPC contracts — protobuf contracts that any language can implement, with clients for TypeScript, Kotlin/Java, and Elixir, and a Python client coming soon
• 🗄️ Pluggable storage — MongoDB (default), PostgreSQL, SQL Server, SQLite, and in-memory providers
• 🖥️ Web Workbench — a bundled browser tool for browsing events, inspecting observer state, and trying supported projection mappings
• ⌨️ CLI — the Cratis CLI brings event, observer, projection, and read-model inspection to the terminal

Workbench and CLI inspection access does not grant permission to mutate data. See the workbench guide for the inspection and authorization boundaries.

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

Chronicle's boundary is a set of language-agnostic gRPC/protobuf contracts — any language with a gRPC implementation can talk to the kernel.

Building a client for another language? The building a client guide distills everything the existing clients learned along the way.

Start the local kernel below, then follow a client or host quickstart to connect an application and append an event. The C# snippets here show the API shape; they are not a complete application. Use the library tutorial if you want to build the model one step at a time.

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

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 127.0.0.1:35000:35000 \
  cratis/chronicle:latest-development

Option 2 — Docker Compose:

services:
  chronicle:
    image: cratis/chronicle:latest-development
    ports:
      - "127.0.0.1:35000:35000"   # gRPC, REST API and Web Workbench (single TLS port)

Both options publish the port on this machine only. The development image's workbench accepts well-known development credentials, so don't expose it on a shared network. Open the workbench at https://localhost:35000 and accept the self-signed development certificate. MongoDB stays inside the container with this setup; use the two-port quickstart if your application will query MongoDB directly.

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

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

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

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

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

// 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"));

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

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));
}

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.

┌──────────────────────────────────────────────────────────┐
│                     Your Application                     │
│         .NET · TypeScript · Kotlin/Java · Elixir         │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Events · Reactors · Reducers · Projections        │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
│                     Chronicle Client                     │
└─────────────────────────────┬────────────────────────────┘
                              │  gRPC (language-agnostic contracts)
┌─────────────────────────────┴────────────────────────────┐
│              Chronicle Kernel (Orleans-based)            │
│                                                          │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────┐  │
│  │  Event Store   │  │   Projection   │  │    Web     │  │
│  │                │  │   Engine       │  │ Workbench  │  │
│  └────────────────┘  └────────────────┘  └────────────┘  │
│                                                          │
│      MongoDB · PostgreSQL · SQL Server · SQLite          │
└──────────────────────────────────────────────────────────┘

Chronicle follows a client-server model:

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

This project is part of Cratis Platform — tools for building event-sourced and CQRS applications.

• Chronicle — event-sourcing database and runtime. Orleans-based kernel, pluggable storage (MongoDB default; PostgreSQL, SQL Server, SQLite, in-memory), language-agnostic gRPC contracts. Docs
• Chronicle clients — first-class .NET SDK, plus TypeScript, Kotlin/Java, and Elixir; Python coming soon. AI agents connect through the Chronicle MCP server.
• Arc — opinionated CQRS framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing. Docs
• Components — React components aligned with Arc patterns. Docs
• CLI + Workbench — inspect and diagnose Chronicle from the terminal or the browser. Docs
• Model-first layer — Studio, Screenplay, Stage, Scene, Prologue
• Supporting — Fundamentals, Specifications, Synopsis, Lens, Narrator, and free AI tooling; Ensemble coming soon
• Samples — runnable event sourcing and CQRS samples for the whole stack

Chronicle is MIT licensed and free to use.

Blog: blog.cratis.io

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 contributing guide.

You can also browse the code directly in your browser:

Distributed under the MIT License. See LICENSE for full details.

• 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 ❤️

Release notes and announcements: the Cratis blog.