Quick Start

What is Cronus?

Cronus is an open-source framework that helps you solve business problems with less time on infrastructure concerns. Applications built with Cronus are centred around three core concepts:

• Domain-Driven Design

• Event Sourcing

While many applications can be built using Cronus, it has proven very effective for microservices architectures. Cronus provides an innovative and powerful way of sensibly evolving to event-driven microservices within a microservice architecture.

Cronus has its roots way back in 2012 when a couple of passionate software engineers started building the infrastructure for a software project using DDD/CQRS/ES. The results were quite impressive and the team started growing. Everybody was sharing the same vision and passion for going beyond the boundaries of their skills. The amazing part of this story is that this hasn't changed. Cronus is a reflection of our philosophy for building great software solutions.

Cronus is built to let you express Domain-Driven Design tactical patterns with minimal friction. Aggregates, entities, value objects, commands, events, and signals all have first-class primitives and serialize/route through a predictable, conventions-first pipeline. If you are new to the DDD vocabulary, start with concepts/ddd.md; if you are new to event sourcing, read concepts/es.md.

The pages below cover the tactical building blocks you assemble into a Cronus-powered service.

Each page is self-contained and cross-references the others where a single concept spans multiple files.

This quick start builds a tiny task-management service in two processes:

• TaskManager.Api — an ASP.NET Core Web API that accepts requests from clients and publishes commands to Cronus.

• TaskManager.Service — a worker host that consumes commands, persists events, builds projections, and runs the rest of the Cronus pipeline.

Splitting API and worker is the recommended production topology. The API process stays fast and stateless; the worker process owns all long-running background work.

With a TaskCreated event in Cassandra we can now build a projection — a queryable read model derived from events. This page walks through adding a TaskProjection and exposing it through the API.

1. Install the projections package

Projections are persisted by the Cronus.Projections.Cassandra package. It should already be added to TaskManager.Service from the setup step; double-check:

dotnet list TaskManager.Service package | grep Projections

Make sure the Cronus:Projections:Cassandra:ConnectionString is set in both API and worker appsettings.json:

"Projections": {
  "Cassandra": {
    "ConnectionString": "Contact Points=127.0.0.1;Port=9042;Default Keyspace=taskmanager_projections"
  }
}

2. Define the projection

We want to query all tasks belonging to a given user. The projection ID will therefore be UserId, and the projection subscribes to TaskCreated.

Inject IProjectionReader into a controller and call GetAsync<TProjection>(id). The reader returns a ReadResult<TaskProjection>; always branch on its NotFound / HasError / IsSuccess flags.

1. Start the worker and the API (dotnet run --project ...).

2. POST /Task/CreateTask with userId=alice.

3. Wait a moment for the worker to handle the command and update the projection.

If the projection returns NotFound, check the worker logs for CronusWorkflowHandle entries involving TaskProjection. A missing entry means the event was not routed — usually a Subscribe<TEvent> is missing or the tenant does not match.

is a browser UI that inspects running hosts: tenants, projections, versions, rebuilds, and event traffic. It talks to the Cronus RPC endpoint that the worker exposes.

Enable the RPC endpoint in the worker's appsettings.json:

Then open the dashboard, add a connection to http://localhost:7477, and navigate to the Projections tab. A green "live" badge means the projection is synchronised with the event store.

• — deeper on the write model.

• — snapshots, versioning, non-event-sourced projections.

• — every Cronus option.

Cronus is a framework for building services that are honest about the way their business works. Three ideas are present in every Cronus service and are worth reading about before the rest of the documentation:

• — is what the services are about. Cronus assumes you have already decided what your core domain is, worked out the ubiquitous language with domain experts, and have settled on the boundaries of each bounded context. Without that, the rest of the framework is a set of answers to questions you have not asked yet.

• — is how Cronus remembers what happened. Aggregates emit events when they change; events are appended to an immutable log; any current-state representation (the aggregate itself, a projection, an audit report) is derived from that log by replaying events. The log is the source of truth and everything else is disposable.

With the skeleton from the setup page running, we can model a tiny slice of the task manager and send a command that ends up as an event in Cassandra.

The slice is:

1. Two aggregate IDs — TaskId and UserId.

2. A command — CreateTask.

3. An event — TaskCreated.

4. An aggregate root and its state — TaskAggregate / TaskState.

5. An application service — TaskAppService.

6. An API controller that publishes the command.

Put commands/events/IDs in a shared project (for example TaskManager.Contracts) that both the API and the worker reference. Aggregates, states and app services live in the worker project only.

AggregateRootId's ctor takes (tenant, arName, id) — in that order.

The aggregate is the only object allowed to call Apply. The state folds each event into itself via a When(TEvent) handler.

ApplicationService<TaskAggregate> gives you the repository field. ICommandHandler<CreateTask>.HandleAsync is the async entry point — load the aggregate, decide whether to create it, save it.

Inject IPublisher<ICommand> and await publisher.PublishAsync(...). The method returns true when the transport accepted the command.

With both the worker and the API running (see ), POST /Task/CreateTask:

The API returns 202 Accepted with the task URN (for example urn:tenant:task:c9b3…). Internally:

1. The controller publishes CreateTask onto RabbitMQ.

2. The worker's subscriber picks it up and runs TaskAppService.HandleAsync.

3. The service constructs a new TaskAggregate, which applies a TaskCreated event.

Take the task URN from the response, Base64-encode it, and query the Cassandra taskmanagerevents table:

You should see exactly one row — the TaskCreated event, serialised, tagged with its [DataContract(Name = …)] GUID. Restart the worker and run a LoadAsync<TaskAggregate>(taskId): Cronus rebuilds the aggregate by replaying that single event back into the state.

Next stop — turning those events into a read model.

What Event Sourcing is in Cronus

An event-sourced service does not persist the current state of its business objects. It persists the sequence of events that describe every change that ever happened to them, and derives the state on demand by replaying those events. Cronus treats the event store as the single source of truth for the write side of the service — everything else (aggregates in memory, projections, indices, analytical reports) is a derived artefact that can be thrown away and recomputed.

Contrast this with an EF- or ORM-based service. There you persist the current row of a Concert table, and a change is an UPDATE. Any insight about how the concert got to its current shape — when performers were added, when the venue changed, which commands were accepted and rejected — is lost unless you manually write an audit trail. An event-sourced service gets the audit trail for free because the events are the persistence format.

The pattern

A Cronus aggregate inherits from AggregateRoot<TState> and changes its state by calling Apply(IEvent):

public class Concert : AggregateRoot<ConcertState>
{
    Concert() { }

    public Concert(string name, Venue venue, DateTimeOffset startTime, TimeSpan duration)
    {
        Apply(new ConcertAnnounced(...));
    }

    public void RegisterPerformer(Performer performer)
    {
        if (state.HasStarted) throw new InvalidOperationException("...");
        Apply(new PerformerRegistered(...));
    }
}

The state lives in a separate class with When(TEvent) handlers — the only place the state is allowed to change:

A command is turned into zero or more events by the aggregate; those events become an AggregateCommit in the event store. Rehydrating the aggregate later is symmetric: Cronus loads the stream of past events for that aggregate id, feeds them through When, and the state you started from is the state you left off at. For the full walkthrough see .

An event-sourced workload has a very specific shape: every write is an append, and the vast majority of reads are "give me all events for this aggregate id in revision order". Cassandra's storage model is a direct match — a wide row per aggregate id, ordered clustering by revision, append-only inserts, no updates. Reads are a single partition scan; writes do not compete for a shared row lock. Distribution and replication come for free because that is what Cassandra is for.

Cronus's canonical event-store backend is and it has been in production use since 2013. See for the details of how the contract is implemented on top of Cassandra.

The property you buy with event sourcing — that the event log is the source of truth and everything else is derived — is most visible at the projection layer. A projection is a read model that handlers update as events flow through the system. If you change the projection's shape, the old rows in its store no longer match the new code. With a relational model, that would mean writing a schema migration. With event sourcing, it means bumping the projection version and replaying the events through the new handler; see .

The same property makes things like "backfill a new subscriber with every event it cares about since the start of time" and "recompute this analytical report after fixing a bug" routine. Both are a call to with the right event-type filter.

Event sourcing is not a free meal. The write side is more complex than a CRUD service, the read side requires an explicit projection pipeline, and the investment only pays off once you lean on the event log for rebuilding state, backfilling subscribers and auditing history. The shape of business that benefits most is also the shape DDD prefers — established, non-trivial, long-lived, with a rich set of distinct state transitions that people actually care about.

See also and — the three concepts reinforce each other.

What CQRS is in Cronus

CQRS is a structural decision: the write side of a service and the read side of a service are different programs. They have different types, different stores, different scaling characteristics, and — often — different hosts. They share the business domain and the event log; they do not share their runtime.

In Cronus the split is explicit:

• Writes happen against an Aggregate. A command arrives, an application service loads the aggregate from the Event Store, calls a method, and saves the resulting events. The write side is tuned for correctness and for append-only throughput.

• Reads happen against a Projection. Projections subscribe to events, update their own store, and are queried through IProjectionReader. The read side is tuned for query shape — each projection exists to serve one or a few UI or API reads cheaply.

Neither side knows about the other at the type level. An application service never references a projection type; a projection never issues a command. Between them sits the and the layer.

The division shows up in the message taxonomy. Every command in Cronus is an ICommand — a strongly-typed instance with a [DataContract] attribute, routed through IPublisher<ICommand>, delivered through the application-services consumer, handled by a method on an application service that loads an aggregate, mutates it and calls SaveAsync. See the .

Queries, by contrast, do not travel on the bus at all. A query is a GetAsync(IBlobId) call against IProjectionReader, returning a ReadResult<T> — an in-process function call. The UI layer or the API controller injects the reader and asks; no routing, no broker, no retry policy, no "eventually delivered". The read side is synchronous from the caller's point of view and the latency is bounded by how fast the projection store can answer.

That distinction is load-bearing. Commands have to be durable, at-least-once, and ordered per aggregate — they are business intent. Queries have to be cheap and right-now — they are user experience. Treating them as the same kind of thing would compromise both.

Because the two sides are runtime-separate, they scale independently. A read-heavy service might run three projection hosts and one application-services host; a write-heavy migration might run a single projection host and ten application-services hosts. The flags are exactly the knobs: turn ApplicationServicesEnabled off on a host and it becomes a pure projection reader; turn ProjectionsEnabled off and it becomes a pure command processor.

Evolution is similarly decoupled. A new projection can be added without touching the aggregate — you add the projection type, deploy, let it catch up from the event store. A new command can be added without touching existing projections — the new event it produces only affects projections that subscribe to it. This is the operational payoff of CQRS, and it is the reason Cronus makes the split structural rather than stylistic.

CQRS does not require event sourcing and event sourcing does not require CQRS, but in a Cronus service they always appear together. The event log is what lets the read side be rebuildable — a new projection version replays events through its updated handler; see . Without the event log, a CQRS service would need a separate write-to-read synchronisation mechanism, and without the CQRS split, the event log would be trying to serve both the latest-state query and the append-only write path at once. Cronus picks the combination that makes the most of both.

A useful way to think about it:

• The write side owns the rules. Can this performer be added to this concert? The aggregate knows. Can this order be cancelled after shipping? The aggregate knows. Rules are enforced by AggregateRoot methods that either produce an event or throw.

• The read side owns the shape. What does the list of upcoming concerts look like to a mobile client? A projection. What does the ops dashboard show? A projection. The read side is free to denormalise, aggregate across multiple aggregates, and expose exactly the shape the consumer wants.

Rules are written once and do not change shape with the UI. Shapes change often and do not change the rules. That is why keeping them in separate pipelines pays.

See also and — the three concepts reinforce each other; they are the load-bearing assumptions behind every Cronus service.

Identity in Cronus is built on URNs. Every aggregate root, every entity, every projection, and every message that carries an id uses a URN-shaped value object. This page walks through the concrete types you will use, what they encode, and how to derive your own.

The URN foundation

The base class is Urn (from Elders.Cronus.DomainModeling):

[DataContract(Name = "d3ff08b5-38e2-4aaf-b3a8-ccc423ed096d")]
public class Urn : IEquatable<Urn>, IBlobId
{
    public const char PARTS_DELIMITER = ':';
    public const char HIERARCHICAL_DELIMITER = '/';
    public const string UriSchemeUrn = "urn";
    // ...
}

A URN has three interesting parts for our purposes:

• the scheme, always urn,

• the NID (namespace identifier) — in Cronus, the tenant,

• the NSS (namespace-specific string) — everything that identifies the resource inside the tenant.

Cronus also accepts r-, q-, and f-components per , and by default is case-insensitive (Urn.UseCaseSensitiveUrns = false). NIDs must be 2–32 characters, alphanumeric plus -, and may not start or end with - nor contain the string urn.

AggregateRootId is the concrete URN used for aggregate roots. Its NSS is arname:id, so a full aggregate id looks like:

The load-bearing constructor takes those three pieces in order:

Argument order is tenant, arName, id — a frequent source of copy-paste bugs. Three companion statics make parsing easy:

Parse throws ArgumentException on an invalid URN; TryParse returns false.

In practice you never pass around a raw AggregateRootId. You derive a named subclass per aggregate, decorate it with a stable [DataContract(Name = "<guid>")], and forward the three constructor arguments:

The private parameterless constructor is required for deserialisation. The aggregate-root name ("experience") is the only free-form part — keep it lower-case, short, and stable. Changing it later is a store-fork event.

For entities hanging off an aggregate root, Cronus provides EntityId<TAggregateRootId>:

Deriving an entity id looks like this:

The NSS becomes arname:arid/entityname:entityid, so a full entity URN reads:

The hierarchical / separates the aggregate from the entity, the : separates name from id on each side. This is what EntityId.EntityRegex() validates against.

Several names you may see in older code, blog posts, or scratch branches are not part of the current framework:

• AggregateRootId<T> — a generic base class was sketched but left commented-out inside AggregateRootId.cs; there is no such generic today. Derive from the non-generic AggregateRootId instead.

• AggregateUrn — not defined anywhere in Elders.Cronus.DomainModeling. The previous separate type was collapsed into AggregateRootId.

If you are porting older code, delete the references and lean on AggregateRootId directly.

In Domain-Driven Design a bounded context is the explicit boundary inside which a model is consistent and unambiguous. Two teams working on the same company may use the word "Order" to mean different things — DDD accepts that and asks you to name the context each meaning lives in. For the conceptual foundation, see concepts/ddd.md.

Cronus turns that concept into a single, load-bearing configuration value: Cronus:BoundedContext.

One name, many side effects

The Cronus:BoundedContext setting is one alphanumeric string. It prefixes:

• every RabbitMQ exchange and queue the host declares,

• every Cassandra keyspace the event store and projection store write to,

• the default Namespace stored against contracts whose type does not set one explicitly.

Change that string on a running system and you fork your whole store: new queues, new keyspaces, and the old streams become invisible.

The setting is bound to the BoundedContext options class:

Two rules are enforced by the class itself:

• The value is required — a host will not start without it.

• The value must match ^\b([\w\d_]+$): alphanumeric characters and underscores only. No dots, dashes, or spaces.

• BoundedContextProvider lower-cases and trims the input, which matches RabbitMQ's case-sensitivity and keeps names canonical.

Inject IOptionsMonitor<BoundedContext> to read the current value at runtime.

Every message type in Cronus carries a [DataContract] attribute. The Name parameter is the contract id (a GUID). The Namespace parameter is the bounded context the type belongs to.

If the type sets Namespace explicitly, that wins; otherwise the caller's default is used. For a service's own contracts the default is "implicit", meaning "route under this service's own bounded context". For contracts shared with other services, set Namespace explicitly so routing stays stable regardless of which host serializes the message.

A common pattern is to keep a static constants class in your .Contracts project:

and reference it from every contract:

That keeps the bounded-context string in exactly one place per contract assembly.

An aggregate is a cluster of domain objects treated as a single consistency boundary. Every change enters through the root; every invariant is enforced inside the root. With Cronus, an aggregate is event-sourced — its state is the fold of the events it has produced.

Three classes work together:

• AggregateRoot<TState> — the entry point for behaviour. It calls Apply(IEvent) to record a change.

• AggregateRootState<TRoot, TRootId> — the snapshot of current data. It reacts to events via public void When(TEvent e).

• AggregateRootId — the aggregate's URN-based identity.

Inherit AggregateRoot<TState>. Keep a private parameterless constructor so Cronus can rehydrate the aggregate during replay, and expose behaviour as plain methods that call Apply to record events.

Inherit AggregateRootState<TRoot, TRootId>. State exposes the current data, maintains the Id, and folds events into itself via public void When(TEvent) handlers. Cronus discovers the handlers by reflection once per process lifetime.

An AggregateRootId is a URN with three segments: tenant, aggregateRootName, and id. The base class's primary constructor is:

Define your own typed ID to avoid stringly-typed code elsewhere:

An aggregate is persisted through IAggregateRepository:

Application services are the only place that should call the repository — see:

An entity is a domain object with identity. Two entities are equal when their IDs match, regardless of their other properties. In Cronus, an entity lives inside an aggregate and shares the aggregate's consistency boundary — the aggregate root is the only thing that mutates entities directly.

Use entities when a part of the aggregate needs its own identity-based lifecycle, but that lifecycle is still owned by the root. Common examples are versions inside a document, line items in an order, or rooms inside a building.

Defining an entity

Inherit Entity<TAggregateRoot, TEntityState> and pass the root plus the entity ID into the base constructor. Events are emitted via the protected Apply(IEvent) method, just like in the aggregate root — but the event is wrapped in an EntityEvent so the right entity's state handler receives it.

public class Wallet : Entity<UserAggregate, WalletState>
{
    public Wallet(UserAggregate root, WalletId entityId, string name, decimal openingBalance) : base(root, entityId)
    {
        Apply(new WalletOpened(entityId, name, openingBalance, DateTimeOffset.UtcNow));
    }

    public void AddMoney(decimal amount)
    {
        if (amount <= 0) throw new ArgumentOutOfRangeException(nameof(amount));
        Apply(new MoneyAdded(state.EntityId, amount, DateTimeOffset.UtcNow));
    }
}

Entity state

Inherit EntityState<TEntityId>. Like the aggregate state, the entity state folds its events into itself via public void When(TEvent e) handlers.

Inherit the generic EntityId<TAggregateRootId>. The base ctor takes the ID base plus the parent aggregate's ID, and you must override EntityName:

The URN of a wallet then looks like: urn:tenant:user:<user-id>/wallet:<wallet-id> — you can see the entity name appears after the hierarchical delimiter /.

The aggregate's state reacts to the "entity created" event, constructs the entity, and adds it to its collection. From that point on, the root can route calls to the entity's methods.

See the aggregate page for the companion pieces (root, state, ID):

The Cronus framework supports multitenancy, enabling a single application instance to serve multiple tenants while ensuring data isolation and security for each. This design allows for efficient resource utilization and simplified maintenance across diverse client bases.

Key Characteristics of Multitenancy in Cronus

• Tenant Isolation: Each tenant's data and configurations are isolated, preventing unauthorized access and ensuring privacy.

• Dynamic Tenant Management: Cronus allows for the addition or removal of tenants at runtime, facilitating scalability and adaptability to changing business needs.

• Shared Infrastructure: While tenants share the same application infrastructure, their data and processes remain segregated, optimizing resource usage without compromising security.

1. Tenant Identification: Assign a unique identifier to each tenant to distinguish their data and operations within the system.

2. Data Segregation: Utilize strategies such as separate databases, schemas, or tables with tenant-specific identifiers to ensure data isolation.

3. Configuration Management: Maintain tenant-specific configurations to cater to individual requirements and preferences.

4. Access Control:

• Consistent Tenant Context: Ensure that the tenant context is consistently applied throughout the application to maintain data integrity and security.

• Scalability Planning: Design the system to handle varying numbers of tenants, considering factors like data volume, performance, and resource allocation.

• Monitoring and Auditing: Implement monitoring and auditing tools to track tenant-specific activities, aiding in compliance and troubleshooting.

By adhering to these practices, developers can leverage Cronus's multitenancy capabilities to build scalable, secure, and efficient applications that serve multiple clients effectively.

Cronus treats the tenant as a first-class dimension of every message. One running service can host many tenants side-by-side; their event streams, projections, message routing, and per-tenant services are all isolated by a single string.

A tenant in Cronus is a short alphanumeric string (for example acme, contoso, northwind) that scopes everything the host does while processing a message:

• the keyspace / table prefix used by the event store,

• the keyspace / table prefix used by the projection store,

• the RabbitMQ exchange and queue names,

• any service you register with a per-tenant lifetime.

The tenant is not a property you carry around manually. Cronus takes the inbound message, resolves the tenant from it once, pins that tenant on the current async scope, and every component downstream that asks "which tenant am I in?" gets the same answer.

The set of tenants a host serves is controlled by the Cronus:Tenants configuration key. See for the full schema.

Each entry is lower-cased, trimmed, and validated by TenantsOptions against the regex ^\b([\w\d_]+$), so tenant names may only contain alphanumeric characters and underscores. The binding is performed by TenantsOptionsProvider under the setting key cronus:tenants.

Inject IOptionsMonitor<TenantsOptions> anywhere you need to enumerate the configured tenants at runtime.

While handling a message, Cronus creates an IServiceScope and attaches a CronusContext to it. The context holds the tenant and the scope's service provider:

The context is exposed via ICronusContextAccessor, which stores it in an AsyncLocal<CronusContextHolder> so it flows across await boundaries without you passing it around. The IsNotInitialized short-circuit exists so callers outside a message-handling scope can detect that there is no current tenant rather than accidentally reading null.

Cronus resolves the tenant from the inbound message via a two-layer chain.

• A non-generic dispatcher, TenantResolver : ITenantResolver, receives the raw object and looks up a typed resolver for its runtime type. It also implements the single-tenant fallback: if no resolver returns a value but Cronus:Tenants has exactly one entry, that entry is used.

• Typed resolvers implement ITenantResolver<T>. DefaultTenantResolver ships implementations for AggregateRootId,

Registration is automated by MultitenancyDiscovery: every non-abstract type implementing ITenantResolver<T> found in the loaded assemblies is registered as a singleton for each ITenantResolver<T> interface it closes. To add your own resolver (for example one that pulls the tenant from a custom transport header), just implement ITenantResolver<YourSource> and let discovery pick it up.

Two helpers make tenant-scoped singletons painless:

• SingletonPerTenant<T> resolves, caches, and returns a T per tenant, setting IHaveTenant.Tenant on the instance if the type implements that marker.

• SingletonPerTenantContainer<T> is the shared dictionary behind SingletonPerTenant<T> and disposes cached instances when the host shuts down.

Register them with AddTenantSingleton<TService, TImplementation> from :

AddTenantSupport wires SingletonPerTenant<> as transient and SingletonPerTenantContainer<> as singleton, so every resolution of TService transparently dispatches to the correct tenant-specific instance.

Every AggregateRootId encodes the tenant in its URN. The constructor takes the tenant first:

See for the full URN layout. DefaultTenantResolver.Resolve(AggregateRootId id) simply returns id.Tenant; this is why messages that expose an AggregateRootId property do not need to carry a separate Tenant string.

A value object is an immutable, identity-less piece of the domain model. Two value objects are equal when their properties are equal — there is no "same-ness" tracked separately from the data itself. Prices, coordinates, phone numbers, date ranges, colour codes: these are all value objects. See Martin Fowler's short piece for the canonical definition.

The two idiomatic options on modern .NET are records and hand-written immutable classes.

Option 1 — record (recommended)

record types give you structural equality for free:

[DataContract(Name = "1b6187f0-88c7-46d5-a22d-b39301765412")]
public record Money
{
    Money() { }

    public Money(decimal amount, string currency)
    {
        if (amount < 0) throw new ArgumentOutOfRangeException(nameof(amount));
        if (string.IsNullOrWhiteSpace(currency)) throw new ArgumentException("Currency is required", nameof(currency));

        Amount = amount;
        Currency = currency;
    }

    [DataMember(Order = 1)] public decimal Amount { get; init; }
    [DataMember(Order = 2)] public string Currency { get; init; }

    public Money Add(Money other)
    {
        if (Currency != other.Currency) throw new InvalidOperationException("Cannot add different currencies.");
        return new Money(Amount + other.Amount, Currency);
    }
}

Two Money(10, "EUR") instances are equal by definition. GetHashCode, Equals and the == / != operators are generated for you.

If you need more control (base classes, private backing fields, bespoke comparisons) write a regular class:

If a property is a collection of value objects, make sure the collection itself supports element-by-element equality. Standard List<T> does not — two List<T> with the same contents are not equal under default equality. Either use HashSet<T> with a value-equality comparer, or compute equality explicitly.

Value objects travel inside events, commands and projection state, so they must serialize cleanly:

A message is the unit of communication that flows through a Cronus bounded context. Every message implements IMessage and carries a Timestamp. Cronus recognises four kinds of messages and each has its own role in the domain model.

Each kind is documented on its own page:

To send a message from outside an aggregate (for example from an API controller, a port, or a saga) inject the typed IPublisher<T> and await one of its PublishAsync overloads:

Business requirements

To drive the examples in the following pages, we'll build a task-management service that meets these real-world requirements:

• A new task-management system for multiple tenants.

• Data must be consistent — no partial updates, no silent loss of state.

• Tasks can be reassigned inside the same user group.

• Every user has an accurate progress report.

• Group progress reports are restricted to group members.

• When a user finishes a task, the group is notified.

• A screen shows the historical changes in user activity.

• When a user closes their account, an optional exit survey is recorded.

• A monthly report summarises why lost users closed their accounts.

We won't implement every single bullet in the quick start. The goal is to get a working skeleton in place and see a command become an event become a projection.

1. — create two processes (API + worker), add the Cronus packages, start Cassandra & RabbitMQ in Docker, and wire AddCronus(Configuration).

2. — model TaskAggregate, publish a CreateTask command, persist a TaskCreated event.

By the end you will have a two-process Cronus service you can grow into a real domain. Each page ends with a pointer to the deeper documentation on the building block it introduced.

What is Domain-Driven Design?

It is our job, as software engineers, to effectively transfer real-world business problems and solutions into the digital world. This is not an easy task. You have to understand how the business operates and what are its key advantages over the competitors. Exploring models in collaboration with domain experts and software experts is essential. To be successful you need to uncover and concentrate on how the business generates profit. We call this area the Core Domain.

There are different supporting pieces as part of the overall puzzle which enhance the Core Domain. We call those Supporting Domains. You need to pay special attention to the details because sometimes a so-called "very important part of the business" could be something generic and commonly used in other applications - a.k.a Generic Domain. For such cases, it is recommended to use an off-the-shelf product or leverage an open-source project and concentrate on the Core and Supporting domains. Otherwise, the software engineers will build something which does not bring value nor a competitive advantage to the client.

Why do we need Domain-Driven Design?

Domain-Driven Design is a concept that helps to reduce the overall complexity of a domain. Software solutions built using the Domain-Driven Design approach, tend to reflect the reality closer and enable the business to grow and expand faster in a reliable and predictable way.

When to use Domain-Driven Design?

There are different opinions about the situations a DDD is appropriate and when you should use it.

There are several factors that make Domain-Driven Design shine. If you have everything in place you should expect good, if not great, results:

It is recommended to use other techniques, different from Domain Driven Design if:

• you are building a software solution for a totally new business. The argument behind this is that Domain-Driven Design relies on the experience and the know-how of the domain experts. It is very likely that you will invest a great amount of time designing models which are not useful. This for sure will lead you to a failure.

• you are building a concept/MVP solution for a new feature. It is better to do it the "quick-and-dirty" way so you could discover if the business concept will be successful or not. This will give you a deeper understanding of the problems you are trying to solve.

• Find a domain expert!

• Strategic design

• Tactical design

• Fail fast

A domain event is a fact: something that already happened inside the bounded context. It is the unit of change in an event-sourced system — the aggregate's state is computed by replaying its events, and projections are built by handling them.

Defining an event

Implement IEvent. Keep the parameterless constructor private so serializers can hydrate the instance, and expose every property with a private setter so the event is immutable from the outside.

[DataContract(Name = "728fc4e7-628b-4962-bd68-97c98aa05694")]
public class TaskCreated : IEvent
{
    TaskCreated() { }

    public TaskCreated(TaskId id, UserId userId, string name, DateTimeOffset deadline, DateTimeOffset timestamp)
    {
        Id = id;
        UserId = userId;
        Name = name;
        Deadline = deadline;
        Timestamp = timestamp;
    }

    [DataMember(Order = 1)] public TaskId Id { get; private set; }
    [DataMember(Order = 2)] public UserId UserId { get; private set; }
    [DataMember(Order = 3)] public string Name { get; private set; }
    [DataMember(Order = 4)] public DateTimeOffset Deadline { get; private set; }
    [DataMember(Order = 5)] public DateTimeOffset Timestamp { get; private set; }

    public override string ToString() => $"Task '{Name}' ({Id}) created for user {UserId}.";
}

Emitting an event

Events are never published directly — they are always emitted through an aggregate root (or an entity inside one) by calling the protected Apply method. The aggregate's state handler (public void When(TEvent e)) is invoked synchronously and the event is added to the uncommitted stream. Persistence happens when the application service calls repository.SaveAsync(aggregate).

public class TaskAggregate : AggregateRoot<TaskState>
{
    TaskAggregate() { }

    public TaskAggregate(TaskId id, UserId userId, string name, DateTimeOffset deadline)
    {
        Apply(new TaskCreated(id, userId, name, deadline, DateTimeOffset.UtcNow));
    }
}

Subscribing to an event

Any handler that needs to react to an event (projection, saga, port, trigger) declares IEventHandler<TEvent>:

See the dedicated handler pages for the specifics of each subscriber kind.

A command expresses the intent to change the state of a single aggregate. It is an immutable message, authored by the caller, that the domain model can accept or reject based on the current state and its invariants. One command maps to one aggregate and one application service.

Defining a command

Implement the ICommand marker. Keep a private parameterless constructor (serializers need it) and assign all properties through the public constructor so instances are effectively immutable.

[DataContract(Name = "857d960c-4b91-49cc-98fd-fa543906c52d")]
public class CreateTask : ICommand
{
    CreateTask() { }

    public CreateTask(TaskId id, UserId userId, string name, DateTimeOffset timestamp)
    {
        if (id is null) throw new ArgumentNullException(nameof(id));
        if (userId is null) throw new ArgumentNullException(nameof(userId));
        if (string.IsNullOrWhiteSpace(name)) throw new ArgumentException("Name is required", nameof(name));

        Id = id;
        UserId = userId;
        Name = name;
        Timestamp = timestamp;
    }

    [DataMember(Order = 1)] public TaskId Id { get; private set; }
    [DataMember(Order = 2)] public UserId UserId { get; private set; }
    [DataMember(Order = 3)] public string Name { get; private set; }
    [DataMember(Order = 4)] public DateTimeOffset Timestamp { get; private set; }

    public override string ToString() => $"Create task '{Name}' ({Id}) for user {UserId}.";
}

Publishing a command

Inject IPublisher<ICommand> and await the PublishAsync method. The call returns true when the transport accepted the command. A false result means the command was not dispatched and the caller must decide how to recover.

[ApiController]
[Route("[controller]/[action]")]
public class TaskController : ControllerBase
{
    private readonly IPublisher<ICommand> publisher;

    public TaskController(IPublisher<ICommand> publisher)
    {
        this.publisher = publisher;
    }

    [HttpPost]
    public async Task<IActionResult> CreateTask(CreateTaskRequest request, CancellationToken ct)
    {
        var taskId = new TaskId(request.Tenant, "task", Guid.NewGuid().ToString());
        var userId = new UserId(request.Tenant, "user", request.UserId);

        var command = new CreateTask(taskId, userId, request.Name, DateTimeOffset.UtcNow);

        if (await publisher.PublishAsync(command).ConfigureAwait(false) == false)
            return Problem($"Unable to publish {command}.");

        return Accepted(taskId.Value);
    }
}

Delaying or scheduling a command

IPublisher<TMessage> exposes overloads for deferred delivery:

Deferred delivery requires the scheduled-message transport to be configured. See the transport-specific documentation (e.g. RabbitMQ) for setup.

Commands are consumed by an application service — the write-side entry point for a specific aggregate.

A handler is a class that reacts to an incoming message and produces some outcome. In Cronus, handlers come in six shapes, each with a different job.

Every handler implements the marker interface IMessageHandler. Beyond that, the kind of handler determines which types of messages it listens to and what it is allowed to do in response.

The six kinds

The choice is about intent, not capability.

• Use an Application Service when a command must mutate one aggregate root.

• Use a Projection when you need a queryable read model built from the event stream.

• Use a Saga when the outcome of one event must lead to new commands that coordinate several aggregates.

• Use a Port

Each kind of handler is served by a dedicated subscriber that can be enabled or disabled per host process via :

• Cronus:ApplicationServicesEnabled

• Cronus:ProjectionsEnabled

• Cronus:SagasEnabled

All default to true. Turn one off when you want to split a monolith into specialised processes — for example, a projections host that never runs ports or sagas.

A public event is an event you explicitly choose to share with the outside world — other bounded contexts, integration consumers, downstream services. It is the Cronus expression of a published language: a deliberate, versioned contract that outlives the internal representation of your domain events.

A public event implements IPublicEvent, which adds a Tenant property on top of IMessage:

public interface IPublicEvent : IMessage
{
    string Tenant { get; }
}

Defining a public event

[DataContract(Name = "c6d9d1ae-5e54-4e1e-9121-9ab0c4f3f7a5")]
public class AccountSuspended_public : IPublicEvent
{
    AccountSuspended_public() { }

    public AccountSuspended_public(string tenant, string accountUrn, DateTimeOffset timestamp)
    {
        Tenant = tenant;
        AccountUrn = accountUrn;
        Timestamp = timestamp;
    }

    [DataMember(Order = 1)] public string Tenant { get; private set; }
    [DataMember(Order = 2)] public string AccountUrn { get; private set; }
    [DataMember(Order = 3)] public DateTimeOffset Timestamp { get; private set; }

    public override string ToString() => $"Account {AccountUrn} suspended in tenant {Tenant}.";
}

Emitting a public event

Public events are emitted from the aggregate root via an overload of Apply:

public void Suspend()
{
    if (state.IsSuspended) return;

    Apply(new AccountSuspended(state.Id, DateTimeOffset.UtcNow));
    Apply(new AccountSuspended_public(state.Id.Tenant, state.Id.Value, DateTimeOffset.UtcNow));
}

Cronus tracks uncommitted public events separately from domain events (see IUnderstandPublishedLanguage.UncommittedPublicEvents). They are published after the aggregate commit has been persisted, so the outside world only ever sees events that actually happened.

Use IPublicEventHandler<T> when another bounded context needs to react to the published language:

A signal is a fire-and-forget trigger that tells something in the system to run. Unlike a command it has no aggregate target, no invariants, and no success/failure contract — its only purpose is to fan out work.

Cronus itself uses signals for heartbeats, projection rebuilds, and index maintenance. In your domain you might use them to pulse periodic reports, announce cron-like events, or ping a saga to re-evaluate its state.

public interface ISignal : IMessage { }

Defining a signal

[DataContract(Name = "c04b3c09-4ad4-4a62-b2f6-d5d86d4f0e55")]
public class RefreshDailyReportSignal : ISignal
{
    RefreshDailyReportSignal() { }

    public RefreshDailyReportSignal(string tenant, DateTimeOffset timestamp)
    {
        Tenant = tenant;
        Timestamp = timestamp;
    }

    [DataMember(Order = 1)] public string Tenant { get; private set; }
    [DataMember(Order = 2)] public DateTimeOffset Timestamp { get; private set; }

    public override string ToString() => $"Refresh daily report for {Tenant}.";
}

Handling a signal

Implement ISignalHandle<TSignal>:

public interface ISignalHandle<in T> where T : ISignal
{
    Task HandleAsync(T signal);
}

public class DailyReportTrigger : ITrigger,
    ISignalHandle<RefreshDailyReportSignal>
{
    private readonly IPublisher<ICommand> commandPublisher;

    public DailyReportTrigger(IPublisher<ICommand> commandPublisher)
    {
        this.commandPublisher = commandPublisher;
    }

    public async Task HandleAsync(RefreshDailyReportSignal signal)
    {
        var cmd = new RebuildDailyReport(signal.Tenant, signal.Timestamp);
        await commandPublisher.PublishAsync(cmd).ConfigureAwait(false);
    }
}

Publishing a signal

Inject IPublisher<ISignal> and call PublishAsync:

await signalPublisher.PublishAsync(new RefreshDailyReportSignal("acme", DateTimeOffset.UtcNow));

You can also schedule a signal with one of the PublishAsync overloads that accepts a DateTime or a TimeSpan.

Two real signal types ship inside the framework and are good references when you write your own.

CronusHeartbeat wakes up every Cronus:Heartbeat:IntervalInSeconds seconds, builds a and publishes it through IPublisher<ISignal>. The signal carries the bounded context and the full tenant list, so downstream services can use it as a liveness probe — see for the consumer side.

The publisher on the heartbeat side typically attaches a TTL header so a delayed consumer can drop a stale beat:

is a system trigger that handles ReplayPublicEventsRequested — a signal asking the host to republish a slice of the public-event stream to a newly-added subscriber. It is a small but representative example of an ISystemTrigger that reacts to a signal by kicking off a :

The pattern — receive a signal, build a job, hand it to the runner — is the canonical way to express "kick off long-running work in response to an ambient nudge".

An application service is the write-side entry point of an aggregate. It is the handler where commands are received and translated into operations on a single aggregate root. This is the "write" side in CQRS.

An application service orchestrates a command: it loads (or creates) the aggregate, calls the right method on it, and saves the resulting events. It is the only place that bridges the infrastructure (the command bus, the repository) and the domain model. Nothing outside of an application service should ever touch the aggregate directly.

Defining an application service

Inherit from ApplicationService<AR> where AR is the aggregate root type. Implement ICommandHandler<T> for every command you want to handle. The base class gives you a protected repository field of type IAggregateRepository and a UpdateAsync helper that loads, mutates, and saves in one call.

ICommandHandler<T> requires one async method:

Use the explicit LoadAsync + SaveAsync pattern when the command can create the aggregate. ReadResult<AR> exposes IsSuccess, NotFound and HasError:

Use UpdateAsync(id, action) when you are 100% sure the aggregate already exists. It throws if the load fails and saves automatically on success:

A published language is the shared vocabulary between two bounded contexts — the set of messages they agree on so one can consume what the other emits without coupling internal models. In Cronus the published language is defined by the messages you mark with [DataContract].

The DataContract convention

Every serialisable message, aggregate id, entity id, and value object in Cronus carries [DataContract(Name = "<guid>")]. The GUID is the stable serialization id for the type. It is not a version number and not a human-friendly name — it is the thing the wire format and the event store use to address a CLR type.

If you rename the class OrderPlaced to OrderSubmitted, the GUID in the attribute stays the same. Serialized events already on disk continue to resolve to the new class name, because look-up goes through the GUID, not through typeof(T).FullName.

MessageInfo implements this indirection:

A type without [DataContract(Name = ...)] will throw the moment Cronus tries to serialise it — there is no fallback.

DataContract.Namespace doubles as the bounded context for the type:

If a type sets Namespace explicitly, that value wins; otherwise the default "implicit" is used. The value is always lower-cased, because RabbitMQ exchanges and queues are case-sensitive and Cronus keeps the routing keys canonical.

See for how that value flows into RabbitMQ routing and Cassandra keyspaces.

The convention is uniform across the Elders ecosystem. A few live attributes:

• Framework-level: Urn and AggregateRootId both opt in.

• An event in a product code-base (no explicit namespace, so it routes under the service's own bounded context):

• A contract shared across services — the namespace is set so the routing stays stable regardless of which host serialises it:

Note the companion convention: a static constants class (BC) holds the bounded-context strings so each contract references the same literal.

Event sourcing persists events forever. If a rename, a move, or a refactor broke the mapping between a serialized payload and a CLR type, replay would stop working. The GUID in [DataContract(Name = ...)] is the insurance against that: it pins the serialization id to the type across every rename and every namespace move.

[DataMember(Order = N)] on every persisted property is the field-level equivalent: removing or renaming a field without keeping its Order number stable breaks replay.

When the shape of an event has to change in a way that is not backwards-compatible, do not mutate the existing type. Create a new type with a new GUID, then add a migration to transform old payloads into the new shape during replay.

A saga is a message handler that watches the event stream and, as a reaction, publishes new commands. Its job is to coordinate a business process that spans more than one aggregate, or to schedule work for the future.

In Cronus, a saga is any class that implements ISaga. Nearly every real saga derives from the abstract Saga base class in the same file, which wires up the two publishers a saga needs:

public abstract class Saga : ISaga
{
    protected readonly IPublisher<ICommand> commandPublisher;
    protected readonly IPublisher<IScheduledMessage> timeoutRequestPublisher;

    public Saga(IPublisher<ICommand> commandPublisher, IPublisher<IScheduledMessage> timeoutRequestPublisher)
    {
        this.commandPublisher = commandPublisher ?? throw new ArgumentNullException(nameof(commandPublisher));
        this.timeoutRequestPublisher = timeoutRequestPublisher ?? throw new ArgumentNullException(nameof(timeoutRequestPublisher));
    }

    public Task RequestTimeoutAsync<T>(T timeoutMessage) where T : IScheduledMessage
    {
        return timeoutRequestPublisher.PublishAsync(timeoutMessage, timeoutMessage.PublishAt);
    }
}

A saga reacts to events through the standard IEventHandler<T> interface. On top of that, it can receive scheduled messages through ISagaTimeoutHandler<T>, where T : IScheduledMessage.

Saga vs Application Service

Both are message handlers, but they sit on opposite sides of the command/event boundary.

An Application Service mutates one aggregate. A Saga never loads an aggregate directly — it publishes commands so that the appropriate Application Services do that work. If you catch yourself wanting to load aggregate state inside a saga, you almost certainly belong in an Application Service or in a new projection.

A saga often needs to do something later — "if the customer has not confirmed in 24 hours, cancel the reservation". It expresses this by publishing an :

Call RequestTimeoutAsync(message) on the base class. Cronus will deliver the message back to the saga at PublishAt, and the saga handles it through ISagaTimeoutHandler<T>.

A production saga rarely has a single handler. It usually reacts to a broad slice of the lifecycle it owns. For a realistic shape look at in the Locus backend — it handles 13 events covering publish-for-approval, approval confirmation, rejection and every edit that invalidates a pending version — and in every case its only job is to publish a command to the right aggregate:

The saga does not touch aggregate state. Each handler inspects the event, decides on the next command and publishes it through commandPublisher. That is the whole pattern.

The subscriber that feeds sagas is toggled by Cronus:SagasEnabled (default: true). Turn it off on processes that must not advance saga state.

• A Saga can send new commands to drive the process forward.

• a saga can subscribe to events from any aggregate in the bounded context

• a saga can publish new commands through commandPublisher

• a saga

A gateway is a port that remembers things. It reacts to events and talks to an external system, just like a port, but in addition it maintains a small amount of persistent state that the external system — not the business — needs.

In Cronus, a gateway is any class that implements IGateway:

public interface IGateway : IMessageHandler { }

The marker interface is minimal. A gateway earns its behaviour through IEventHandler<T> implementations, just like a port or a saga.

Gateway vs Port vs Projection

The XML doc on IGateway sums up the niche it fills:

Compared to IPort, which can dispatch a command, an IGateway can do the same but it also has a persistent state. A scenario could be sending commands to external BC like push notifications, emails etc. There is no need to event source this state and it's perfectly fine if this state is wiped. Example: iOS push notifications badge. This state should be used only for infrastructure needs and never for business cases. Compared to projections, which track events and project their data and are not allowed to send any commands at all, an IGateway store and track a metadata required by external systems. Also, IGateway are restricted and not touched when events are replayed.

Three rules follow from that:

1. A gateway is the right choice when the external system needs state (an APNS badge count, a last-seen device id, a third-party handle). Business state belongs on aggregates.

2. A gateway is not replayed. Unlike projections, gateway state survives a projection rebuild. That makes it safe to store values that are meaningful only in combination with live external resources.

3. A gateway, unlike a projection, may publish commands. That is why it is shaped more like a port than a projection.

Calling an external service by hand from an application service is a trap: you either hand-roll retry, timeout and serialisation logic every time, or you forget it. A gateway is the canonical place to centralise those concerns for a given external system, so the application services above it stay clean.

In practice a gateway wraps the SDK of the external system (HTTP client, gRPC stub, legacy RPC proxy) and applies the retry policy you want for that system's failure modes.

A realistic gateway would inject the external-system client plus whatever persistent store holds the infrastructure metadata (for example a table of APNS device tokens and current badge counts).

The subscriber that dispatches events to gateways is toggled by Cronus:GatewaysEnabled (default: true). Disable it on hosts that should not talk to the external system, for instance when you split the host into a write-only and a read-only process.

A port is the place where an event from the domain meets the outside world. It reacts to events and does I/O: sending emails, calling third-party APIs, writing to disk, pushing a message to another system, or publishing a follow-up command to a related aggregate.

In Cronus, a port is any class that implements IPort:

public interface IPort : IMessageHandler { }

public abstract class Port : IPort
{
    protected readonly IPublisher<ICommand> publisher;

    public Port(IPublisher<ICommand> publisher)
    {
        this.publisher = publisher;
    }
}

The Port base class gives you a command publisher for convenience; you are not required to use it. What makes a class a port is the IPort marker plus one or more IEventHandler<T> implementations.

Why a port and not an application service?

Keep Application Services focused on a single aggregate and free of I/O. That leaves the domain model fast, testable and replayable. All the messy things — latency, failure, retries — belong in a port.

A port is a natural retry boundary. If the third-party API is down, the port fails, the message is not acknowledged, and the subscriber delivers it again later. If the same side effect lived in an application service, a transient failure would also block the aggregate's write path.

Port vs Saga

Both react to events; both can publish commands. The difference is intent:

• A port reaches out. Its reason to exist is the side effect — call the outside world, or fan out a single follow-up command.

• A saga orchestrates. Its reason to exist is a multi-step business process that spans several aggregates.

Use a port when the reaction is a one-shot "when X happens, do Y". Use a saga when Y is followed by Z and possibly a compensating W.

And a port that reacts to an event by issuing a command to a different aggregate:

The subscriber that dispatches events to ports is toggled by Cronus:PortsEnabled (default: true). Turn it off on processes that must not perform outbound side effects, for example a read-only replica or a dedicated projections host.

By utilizing Ports appropriately, developers can design systems that are both modular and maintainable, adhering to the principles of Domain-Driven Design and Event Sourcing.

A projection is a read model. It is a derived representation of the events in the event store, shaped for the way a particular reader wants to consume data — an API endpoint, a dashboard, a search index. A projection never mutates the source of truth; it only applies events to its own state.

Cronus supports two flavours:

• Event-sourced projections — inherit ProjectionDefinition<TState, TId> and subscribe to the events they care about. Their state is rebuilt by replaying events, optionally from a stored snapshot.

• Non-event-sourced projections — implement IProjection directly and persist state to an external store (for example Elasticsearch or a relational database).

Inherit ProjectionDefinition<TState, TId> where TState is a serializable plain class and TId is any type that implements IBlobId. Declare IEventHandler<TEvent> once per event you want to handle. In the constructor, call Subscribe<TEvent>(event => projectionId) for every event — that's how Cronus knows which projection instance a given event belongs to.

The state class is serialised into a snapshot, so it needs a parameterless constructor, a [DataContract] attribute, and [DataMember(Order = n)] on every persisted property — the same rules as for events.

Cronus does not guarantee that an event is delivered exactly once, and out-of-order delivery can happen during catch-up or rebuild. Design your projection accordingly:

Sometimes the read model lives in an external store that tracks its own consistency — a SQL database via EF Core, for example. Implement IProjection directly and skip the snapshot machinery:

You own the write path; Cronus only fans the event into your handler.

Inject IProjectionReader and call GetAsync<TProjection>(id). The returned ReadResult<TProjection> tells you whether the projection was found and whether there was an error.

GetAsOfAsync rebuilds the projection as it was at a given point in time — useful for time-travel queries and diagnostics.

When a projection's shape changes (new event subscription, different state schema, new aggregation) Cronus treats it as a new version: the old version keeps serving reads while the new one rebuilds in the background, then traffic switches over atomically. That flow is covered in the projections versioning documentation.