Concepts

New to Kumiko?

This section explains the architecture and assumes you already know what Kumiko does. If you’re just arriving, start with What you get and the Quickstart — then come back here to understand why it works that way.

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	Why every change is stored as an event, and the read tables your queries hit.
Commands and queries	Why writes and reads run on separate rails: write handlers vs. query handlers.
Multi-tenancy	How one database serves many tenants in isolation, plus 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.
Aggregates vs. embedded fields	When nested data gets its own event stream, and when it stays a field.
Core features vs. samples	Bundled features are production code; samples are worked examples, never a dependency.
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.