Skip to content
Kumiko

How Kumiko thinks

Kumiko makes a small number of design choices that pull the rest of its shape after them. None of them are arbitrary, and none of them are adjustable — taking any of them out unwinds the others.

If you read just one Concepts page, this is it. The other nine spell out the consequences in detail.

1. Everything is a feature

Section titled “1. Everything is a feature”

There is no privileged core. Auth, audit, multi-tenancy, file storage, notifications, jobs — every capability ships as a feature definition, constructed through the same defineFeature API your own code uses. The framework underneath provides infrastructure (the dispatcher, the lifecycle pipeline, the tenant database context) but no business semantics.

The trade-off bought: features are pluggable, replaceable, removable. The cost paid: cross-feature work goes through a small fixed set of channels, not direct imports.

2. Schemas are values, not classes

Section titled “2. Schemas are values, not classes”

A Kumiko entity is a configuration object — fully serialisable, fully walkable, with no methods on it. The framework derives everything else from that one definition: the database table, the validation schema, the list view model, the edit form, the search index, the i18n keys. Adding a field is one edit; everything that depends on the field updates with it.

The trade-off bought: an AST surface that designers, AI builders, and code-mod scripts can read and write. The cost paid: features are slightly more verbose than they would be with builder-style abstractions.

3. Source is the canonical representation

Section titled “3. Source is the canonical representation”

What you read in the source file is what the framework loads, what tools edit, and what reviewers approve. Features are written inline, not behind factory functions that construct their shape at runtime. Anything that moves the definition behind a layer of indirection breaks the property that the source can be inspected without running it.

The trade-off bought: every property that depends on reading source — boot validation, designer rendering, AI editing, the audit of a code change — works without a build step. The cost paid: bundled features get a configuration-shape API; app features do not.

4. State is append-only, projections are derived

Section titled “4. State is append-only, projections are derived”

Every state change writes an event before it updates anything else. The event log is the source of truth; entity tables and custom projections are caches you can rebuild. A change that needs to span a transaction and a projection commits both together; a change that fans out across many entities runs from the event log asynchronously.

The trade-off bought: audit, replay, and time travel come for free; a projection schema change becomes a rebuild instead of a migration. The cost paid: writes carry an envelope of previous data, sensitive fields need explicit flagging, and some bookkeeping is unavoidable.

5. Configuration is validated at boot

Section titled “5. Configuration is validated at boot”

Misconfiguration is a startup error, not a runtime surprise. Before any handler runs, the framework walks the feature graph and confirms it is internally consistent — required dependencies present, cross-feature references resolved, no circular dependencies, no name collisions, no mutually-exclusive flags set together. Production never sees a configuration mistake; CI does.

The trade-off bought: deploys are uneventful, and broken configurations cannot ship. The cost paid: boot is more than a process startup — it is a verification step that takes seconds.

What follows

Section titled “What follows”

Each of the other nine Concepts is a consequence of one or more of these five choices.

The choices are stable. The interesting questions in Kumiko are about how to live well within them — what to express as an entity versus a projection, when to extend a bundled feature versus replace it, where to attach a hook. Those are practical questions, with practical answers. The five choices above are the ground.