Learning paths

Cratis covers an event store, an application framework, a UI library, and the tools around them, so the documentation is wide. A path gives you an order to read it in. Each one says who it is for, what you can do when you finish, and which pages to read or build along the way.

Paths share pages, and you can switch at any point. If none of them fits, Adopting Cratis helps you pick a starting product first.

New to event sourcing Understand facts, projections, and consistency before you commit to a design.

Build a full-stack app Scaffold an app and follow a command through an event and a read model to a live React screen.

Keep decisions correct Make a rule that depends on state hold when two requests run at once, from the first protected command to the advanced scenarios.

Use Chronicle from another language Start from the TypeScript, Kotlin/Java, or Elixir client instead of .NET.

Evaluate Cratis Decide whether the stack, or one product from it, fits your system.

Operate Chronicle Run, inspect, diagnose, replay, and upgrade a Chronicle deployment.

Frontend developer Work with generated proxies and Components on an existing Arc backend.

Contributor Change Cratis itself: code, documentation, or design proposals.

New to event sourcing

For developers who have built CRUD applications and want to know what changes when events become the source of truth. When you finish, you can model a small domain as facts, explain how read models are derived from them, and say where event sourcing is the wrong tool.

1. Read Why event sourcing for the argument, then CRUD, EF Core, and Chronicle to map tables and SaveChanges onto events.
2. Read Event modeling. It gives you the notation the rest of the docs use for commands, events, and read models.
3. Build the Chronicle tutorial. It adds one concept at a time to a small library domain.
4. Read Consistency and When to use event sourcing.
5. Bring your first real model to Community and help. A modeling question with the business decision and the facts you already have usually gets a useful answer.

Build a full-stack app

For .NET developers starting a new information system with Chronicle, Arc, and Components together. When you finish, you have a running application with one slice you wrote yourself, and you know where the command, event, projection, query, and screen for a feature live.

1. Follow Build a full-stack feature. It scaffolds an application from the Cratis template and adds one slice end to end.
2. Read Vertical slices to see why the feature lives in one folder.
3. Work through the Arc tutorial for validation, related slices, live queries, and authorization. It runs over a plain database, which keeps the focus on commands, queries, and generated proxies.
4. Read Add event sourcing to an Arc slice to see what changes when a slice’s writes move to Chronicle, and what does not.
5. Continue with the vertical slices scenario for the state view, automation, and translation patterns, and Testing with Cratis for specs.
6. Follow Generated values, from Screenplay to running app to have the server own your ids and secrets, from the model through Stage and Arc to pinned specs.

Building on Kotlin or Java instead? The Cratis Kotlin and Cratis Java templates scaffold the same full-stack shape on Spring Boot, and the Arc tutorial shows its main slice examples in Kotlin as well as C#. Some backend snippets are C# only.

Write-side consistency

For developers who write commands whose outcome depends on stored state: a stock level, a limit, a capacity, a document someone else may edit. When you finish, you can say why a plain read does not hold a rule, pick the mechanism that does, write a protected command, and test that it holds when two requests race. Arc read protection needs Arc 22.106.0 or later, which uses Chronicle 19.71.0 or later.

1. Read Keeping decisions correct. It is the five-minute introduction: why a read model can be stale at write time, what read protection does, and which mechanism holds which rule. If you know DCB, KurrentDB, Marten or Axon, read Read this first next.
2. Follow Getting started with read protection to write your first protected command and see the error the losing request gets. Using Chronicle without Arc? Start from Decision reads instead.
3. Work through the scenarios from simple to advanced. Each has the rule, the code and the guard it produces.
   • One entity: stock on one book.
   • Unique and once: constraints, no read needed.
   • Two entities: a loan limit and a course capacity.
   • One stream: a monthly limit, with a per-stream read model.
   • Process stream, gapless numbers, rich aggregate and editing conflict.
   • Test the race to prove a rule holds. For the Chronicle client, see the Chronicle scenarios.
4. Adopt it in an existing application with Adopting read protection: Off, then Measure, then On.
5. Walk the whole stack in Decisions that hold, from model to frontend: one rule from a Screenplay model to an Arc command under read protection, a spec that makes the race happen, and a frontend that handles a lost race. For the idea behind it, read The Dynamic Consistency Boundary.
6. Keep the reference close: Reads, Validators, Refusals, Pitfalls and the FAQ. For the mechanics, read How guards are derived and Read protection in Chronicle.

Use Chronicle from another language

For developers whose services are not written in .NET. When you finish, your service appends events to Chronicle and a projection or reactor responds to them.

1. Read Chronicle in your language to see which clients are published and where each is documented.
2. Start a local kernel and follow the shared loop on Chronicle getting started. Its examples have a tab for each client that implements them.
3. Follow your client’s setup guide: TypeScript, Kotlin and Java, or Elixir.
4. Build the Chronicle tutorial and pick your client’s tab where one exists.

The Python client is pre-release and not published yet; Event sourcing in Python tracks it.

Evaluate Cratis

For architects and team leads deciding whether to adopt Cratis. When you finish, you can name the product you would start with, the first slice you would move, and the version and production questions you still need answered.

1. Read Why developers choose Cratis, including when it is not a good fit.
2. Read Adopting Cratis to pick an entry point for a new or existing system.
3. If you are comparing event stores, read Compare event sourcing for .NET or Compare event sourcing on the JVM. Marten vs Chronicle is a head-to-head for .NET teams on PostgreSQL.
4. Check the FAQ, Version compatibility, and Production readiness.
5. Run one sample that matches the shape you would build.
6. Ask adoption questions in Community and help, or Work with us for a dedicated review.

Operate Chronicle

For people who deploy and run Chronicle. When you finish, you can host Chronicle with storage and TLS you chose deliberately, find a failed partition, and plan an upgrade.

1. Read Chronicle hosting and Production hosting.
2. Review Chronicle configuration, including storage.
3. Learn the CLI and the Workbench, then keep Chronicle troubleshooting close.
4. Use Production readiness as the cross-stack checklist.
5. Before each upgrade, use Plan an upgrade and What’s new. Follow Security for vulnerability reporting.

Frontend developer

For React developers joining a team that already has an Arc backend. When you finish, you can call commands and queries through generated proxies and build forms, dialogs, and live tables with Components.

1. Read Understanding the proxy boundary to see where the generated TypeScript comes from and why you never edit it.
2. Read Arc frontend.
3. Build the Components tutorial, then use Choosing a component for new screens.
4. Browse Storybook for live examples. Coming from PrimeReact? Read Coming from PrimeReact.
5. Run a sample with a React frontend to see the screen and backend together.

Contributor

For people changing Cratis itself. When you finish, you know where a change belongs and what a pull request needs before review.

1. Read Contributing and Governance.
2. Find the repository that owns the behavior. Product pages are written in each product repository’s Documentation/ folder; only site-level pages such as this one live in the Documentation repository.
3. Use Feedback and suggestions or Discord for early ideas before opening a large proposal.
4. Run the owning repository’s build, specs, and documentation checks before opening a pull request.