Cratis.Arc.Chronicle.CodeAnalysis 22.168.0

title: "Cratis Arc: CQRS framework for ASP.NET Core" description: Cratis Arc is a CQRS framework for ASP.NET Core that exposes commands and queries over HTTP and generates TypeScript clients, without requiring event sourcing.

<a id="cratis-arc"></a>

Cratis Arc: CQRS framework for ASP.NET Core

Cratis Arc is an open-source (MIT) CQRS application framework for ASP.NET Core. CQRS separates requests to change something (commands) from requests to read it (queries). Arc exposes those contracts over HTTP, handles validation and authorization, and generates TypeScript clients for the frontend. It works with current-state storage or optional Cratis Chronicle event sourcing.

Build a feature as a vertical slice: keep its command, read model, query, frontend, and specs together. The backend defines the contracts; generated TypeScript proxies carry them into the frontend without a hand-written API client for those contracts. Observable queries let a screen subscribe to results as they change, with a configured observation source.

Choose the packages your feature needs. Arc includes identity and tenancy, React integration, MongoDB and Entity Framework Core adapters, OpenAPI, analyzers, and testing helpers. Chronicle event sourcing and Cratis Components are optional integrations. Free AI skills provide guidance for building with the stack.

Start here

• Browse the Arc documentation
• Read why Arc exists
• Map familiar concepts when coming from MediatR and MVC
• Try runnable samples — including Idea Loom and Library
• Choose a documented application path
• Understand Arc's independent boundary
• Start an Arc host
• Inspect packages and repository layout

What Arc owns

Use this table to find the capability you need, then check its package and documentation for your host, provider, browser, and versions. The rows do not establish compatibility for every combination.

Choose a path

Arc documentation is organized around the job you need to complete:

• Execute commands — model-bound or controller-based changes, pipelines, validation, authorization, filters, and response handling.
• Separate command decisions from inline side effects — preferred for already-decided work in model-bound commands, with optional best-effort compensation. Direct service calls remain supported; operations require neither Chronicle nor frontend recovery code.
• Expose queries and observable results — request/response reads, paging, sorting, streaming updates, diagnostics, and generated clients.
• Build the frontend — TypeScript runtimes, React hooks and forms, dialogs, identity, messaging, and optional MVVM packages.
• Configure identity and access — authentication, identity details, authorization, roles, and frontend visibility boundaries.
• Resolve tenants — request resolvers, scoped tenant context, and provider-specific database or namespace mapping.
• Use current-state persistence — application services, MongoDB, or Entity Framework Core without requiring an event log.
• Add Chronicle event sourcing — events, projections, reducers, aggregates, reactors, concurrency, and Chronicle-specific testing.
• Inspect and verify the application boundary — introspection, OpenAPI, analyzers, generated metadata, and command scenarios.

For a first feature, start the host below, then follow the command and query guides. If you already have an application, choose the path for the part you want Arc to handle.

Arc does not require event sourcing

Arc.Core does not depend on Chronicle. A command can call an application service or write current state to a database; a query can read that state without an event log.

Choose the optional Chronicle integration when you want to record events and derive state from them. Arc still handles commands, queries, validation, authorization, and generated frontend contracts.

Chronicle is Cratis's storage-agnostic event-sourcing database and runtime — MIT licensed and free to use; see the Chronicle documentation for its own scope and setup.

Relationship to Components

Components is a React component library aligned with Arc application patterns. See the Components documentation for its packages and setup.

Applications may use Arc without Components and remain responsible for their own frontend, accessibility, browser, and design-system verification.

Start an Arc host

Arc's .NET packages embed this product-family README. The example below uses the Cratis.Arc package, Arc's ASP.NET Core integration; when viewing this README from a specialized package page, use that package's manifest and reference documentation for its own installation scope.

Use the .NET SDK declared by Arc's current global.json. Create an ASP.NET Core project and install the package:

dotnet new web -n MyApp
cd MyApp
dotnet add package Cratis.Arc

Replace Program.cs and run the host:

var builder = WebApplication.CreateBuilder(args);
builder.AddCratisArc();

var app = builder.Build();
app.UseCratisArc();
await app.RunAsync();

Starting the host confirms the basic Arc setup. For workers, consoles, or services without ASP.NET Core, the lightweight host is ArcApplication.CreateBuilder(args) from the separate Cratis.Arc.Core package; do not combine it with Cratis.Arc, whose ASP.NET Core services it does not register. See getting started with the lightweight host. Continue with the Arc documentation, and use GitHub Issues when the observed behavior does not match the documentation.

Packages and repository layout

Package existence does not imply compatibility with every frontend, runtime, persistence provider, or product version. Check the package manifests and documentation for the versions you use.

Documentation map

• Arc documentation
• Product-owned documentation source
• Arc releases
• Arc issues

Contributing

Arc is a framework-library repository. Changes to public APIs, analyzers, generated output, and package shapes can affect consumers and require the owning repository's compatibility and release review.

Repository development currently requires the SDK and toolchain versions declared by global.json and package.json. Follow the Cratis contribution guide and this repository's project context (AGENTS.md and the project rules it links) before changing public surfaces.

Before submitting documentation-only work, verify its links, anchors, and examples explicitly; current automated documentation checks are path-scoped. Source changes must pass the owning repository's applicable build, specification, TypeScript, and documentation gates.

• .NET SDK 10.0.400+. Arc's analyzers and source generators are built against Roslyn 5.9.0, which ships with .NET SDK 10.0.400 and newer. On an older SDK band the compiler refuses to load them (CS9057), silently disabling proxy generation and the ARC*/ARCCHR* analyzers. Consuming the Cratis.Arc packages carries the same floor. Raising this floor is a minor version bump.
• Node 23+
• Yarn

Trim and NativeAOT diagnostics

Arc is not trim or NativeAOT compatible yet (#2204). Pull requests that change Source/DotNET run a ratchet that builds Cratis.Arc.Core, Cratis.Arc, Cratis.Arc.MongoDB, Cratis.Arc.EntityFrameworkCore and Cratis.Arc.Chronicle in one build with the trim and AOT analyzers on and compares the diagnostics per code, file and target framework with Source/DotNET/aot-baseline.json. It fails when a diagnostic or a trim/AOT suppression is added, and also when one is removed without shrinking the baseline. Run it locally with Python 3 and the .NET SDKs:

python3 scripts/aot-ratchet.py           # compare with the baseline
python3 scripts/aot-ratchet.py --update  # rewrite the baseline after fixing diagnostics, then commit it

Fix a new diagnostic by replacing the unsafe path rather than suppressing it. The analyzer ships with the .NET SDK, so run --update with the SDK global.json selects, as CI does; the baseline records the SDK version it was made with. When a new SDK changes what the analyzer reports, regenerate the baseline with --update in its own pull request. The normal build is unaffected; the analyzers only run when the script passes CratisAotAnalysis=true. A project is covered by importing Source/DotNET/AotAnalysis.props, which the script discovers, and the run fails unless every covered project reported for each of its target frameworks. The MongoDB, EF Core and Chronicle integrations are held at their current counts until they are annotated with [RequiresUnreferencedCode] and [RequiresDynamicCode].

Community and repository

The Cratis ecosystem

Arc is part of Cratis — a platform 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 (this repository) — 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

Arc is MIT licensed and free to use. Other Cratis products have their own licensing and access terms.

Release notes and announcements: the Cratis blog.