Concepts

The Concepts section explains how Kumiko thinks. It is not a tutorial and not a reference. There are no step-by-step instructions, and there is no exhaustive parameter list — for those, see Get started and Reference respectively.

These pages exist for readers who have already decided to evaluate Kumiko and now want to understand the architecture before reading source. Each page is short, focused on one idea, and uses code only to illustrate — never as instruction.

Reading order

The pages below are ordered from foundation upward: each one assumes the ones above it. If you read top to bottom, you will end up with a working mental model in roughly thirty minutes.

Page	What it explains
How Kumiko thinks	The five non-negotiable design choices and the trade-offs they buy.
Features and composition	What defineFeature actually is, and why features replace modules.
Schemas as data	Why entities are values, not classes — and what falls out of that.
Events and projections	Append-only state, read models, and the Marten pattern Kumiko follows.
Commands and queries	The CQRS-light split: write handlers vs. query handlers.
Multi-tenancy	Tenant as aggregate, the single-handle invariant, and anonymous access.
Auth and permissions	Roles, the three-layer permission model, and the system identity.
Lifecycle and hooks	Boot → validate → migrate → run, and where you can intervene.
Bundled features vs. custom	When to take a ready-made feature, when to build your own.
Inline authoring	Why feature definitions stay inline so designers and AI can edit them.

How to use this section

If you are evaluating Kumiko, read How Kumiko thinks first — it is the shortest page and it explains why the rest of the framework looks the way it does.

If you are about to write your first feature, read Features and composition plus Schemas as data.

If you are debugging a write that did not go through, read Events and projections plus Commands and queries.

The other pages are best read on demand, when a specific question pulls you in.