Learning paths

There is no single Kumiko project. These routes connect the existing tutorials, concepts, guides, and runnable recipes around a goal, so you can learn in the order that matches the app you are building. They do not duplicate the code from those pages.

Choose a route

If you are new to Kumiko, start with My first Kumiko app. If you already have a running app, jump to the route that matches your next design decision. Read each item in order, run the checkpoint, and stop when the goal is met.

Every route uses the same format:

• Goal — the result you should be able to achieve.
• Prerequisites — what to know or have running first.
• Sequence — the recommended reading order.
• Recipe — a runnable example to inspect or execute.
• Test command — the smallest useful verification for the route.
• Checkpoint — what you should be able to explain or demonstrate.
• Next depth — where to go when the route raises a harder question.

My first Kumiko app

Goal

Scaffold an app, see the generated Tasks UI, understand the feature that produced it, and prepare the app for a container deployment.

Prerequisites

A terminal, Docker with Compose v2, curl, OpenSSL, and the local ports listed in Requirements. You do not need a clone of the framework repository.

Sequence

1. Requirements, to check tools and ports.
2. Quickstart, to scaffold, boot, sign in, and create the first task.
3. Walkthrough, to trace the generated entity, handlers, screens, navigation, and seed data.
4. Basic entity, to see the smallest event-sourced CRUD feature without the starter app’s extra UI wiring.
5. UI widgets, when the generated screens are not enough and you need an app-specific screen.
6. Deploy: Docker, to build and run the production image with migrations applied before boot.

Recipe

Run the UI walkthrough sample when you want to compare the generated Tasks screen with a complete sample that also covers authentication, tenant switching, language, theme, and optimistic locking.

Test command

In the scaffolded app, use the composition check before debugging the browser path, then build the deployable artifacts:

bun run boot
bun run build

Checkpoint

You can create a task in the browser, point to the entity and handlers that made the screen work, and explain why bun run boot is not a replacement for a real database-backed browser check.

Next depth

Continue with A real domain function, or read Features and composition and Schemas as data before changing the starter feature.

A real domain function

Goal

Turn a business idea into a feature: define its data, expose the right handlers, add generated UI, and model relationships or sensitive fields without creating a second data path.

Prerequisites

A running app from the first route, or an existing app with a mounted feature. You should be comfortable editing TypeScript and deciding which roles may use a business operation.

Sequence

1. Features and composition, to understand the feature boundary and dependency closure.
2. Schemas as data, to define stored fields, reference data, and derived values from one source of truth.
3. Auth and permissions, to separate handler, field, and row access.
4. Add an entity, to add CRUD, screens, navigation, and labels to an existing feature.
5. Commands and queries, to understand the write and read pipelines before adding business rules.
6. Write a custom write handler, when generated CRUD no longer expresses the domain operation.
7. Relations, for independent parent-child entities.
8. Embedded fields and lists, for owned, fixed-shape nested data.
9. Field-level access, for sensitive columns that need different read and write roles.

Recipe

Use Basic entity as the baseline, then compare it with custom handlers, relations, embedded fields, and field-level access.

Test command

Run the app’s boot check after changing the feature. From the framework repository, run the integration suite for the canonical recipes:

# In your app
bun run boot

# In kumiko-framework
bun kumiko test integration

Checkpoint

You can justify whether a nested value is an embedded field or its own entity, identify the handler that owns a business rule, and verify that a restricted field is filtered by the framework rather than by branches in the handler.

Next depth

Choose A secure multi-tenant app when the data needs stronger isolation, or Event sourcing step by step when the domain has events beyond CRUD.

A secure multi-tenant app

Goal

Build a tenant-isolated app with explicit public surfaces, scoped automation, stronger account security, and an erasure/key-management plan that is safe to operate in production.

Prerequisites

A working app and a clear tenant model. For production work, have a deployment secret store and a tested rollback path before handling encryption keys or changing MFA enforcement.

Sequence

1. Multi-tenancy, to learn the tenant-scoped database invariant and the explicit cross-tenant escape hatches.
2. Auth and permissions, to map users, memberships, handler access, field access, and ownership.
3. Tenant isolation, to see the ordinary handler boundary in a focused recipe.
4. Anonymous access, to expose a public read surface without losing tenant resolution or field filtering.
5. Anonymous access multitenant, to inspect host-based tenant resolution without a session user.
6. Field-level permissions, to protect individual fields inside an otherwise usable row.
7. Personal Access Tokens, for scripts, CI, and customer integrations that need scoped, revocable access.
8. Add TOTP-based 2FA, and roll out tenant-wide enforcement only after the affected users have enrolled.
9. Production security baseline, to turn the controls into a staged launch checklist with evidence and stop-gates.
10. Crypto-shredding and blind indexes, to design erasure for event-sourced personal data.
11. Load encryption keys from a key manager and rotate encryption keys as separate operational procedures.
12. Deploy: Docker, with production secrets injected outside Git and schema application before the new image starts.

Recipe

Start with Security baseline, then run Auth MFA and Crypto-shredding (mini HR). The Public share token recipe is a useful follow-up for revocable anonymous links.

Test command

From kumiko-framework, run the integration suite after changing tenant, authentication, or encryption wiring:

bun kumiko test integration

For a production-like key or MFA rollout, treat a successful test run as a precondition, not as a substitute for a staging drill and a rollback check.

Checkpoint

You can explain where the tenant ID comes from for authenticated and anonymous requests, name the rate limit and resolver requirements for public writes, and state what happens to ciphertext, blind indexes, sessions, and unenrolled users when security settings change.

Next depth

Read Lifecycle and hooks and the Platform section for process shutdown, schema application, deployment topology, and operator boundaries.

Event sourcing step by step

Goal

Start with ordinary CRUD, then add domain events, projections, versioning, and cross-aggregate read models only when the domain needs them.

Prerequisites

A running app and the basic entity model from the first two routes. You do not need to adopt custom event streams just to use Kumiko’s standard CRUD path.

Sequence

1. Event Sourcing Handbook, to see the four levels and choose the complexity your domain actually needs.
2. Level 1 — CRUD, no jargon, the default path for a new entity.
3. Level 2 — Events & projections, for domain verbs and read models.
4. Level 3 — Evolution, for upcasters, snapshots, and time travel.
5. Level 4 — Scale & operations, for rebuilds and production operations.
6. React to another feature’s events, for an asynchronous reaction across feature boundaries.
7. Build a read model across multiple aggregates, for cross-stream views and at-least-once consumers.

Recipe

The Event sourcing showcase contains versioned events, an inline projection, a multi-stream projection, point-in-time loading, and stream archiving. Pair it with the Cross-feature events recipe when the consumer belongs to another feature.

Test command

Run the two focused recipes from kumiko-framework:

bun test --dots --config=bunfig.integration.toml --timeout=15000 \
  samples/recipes/event-sourcing/src/__tests__/feature.integration.test.ts
bun test --dots --config=bunfig.integration.toml --timeout=15000 \
  samples/recipes/cross-feature-events/src/__tests__/feature.integration.test.ts

Use bun kumiko test integration when you want the complete integration suite. The CLI’s integration scope runs the whole suite; it does not accept an additional path filter.

Checkpoint

You can distinguish an inline single-stream projection from an asynchronous multi-stream projection, explain why an apply function must be idempotent, and name the rebuild boundary for side-effect-only consumers.

Next depth

Read Commands and queries alongside Events and projections when you need to debug a write, or continue to A secure multi-tenant app before putting personal data into an immutable event history.

Enterprise AI

Goal

Add an AI provider and an in-app agent or pipeline while keeping exposure, approval, tenant policy, provenance, prompts, and cost controls explicit.

This is the current Kumiko product path: start with the Enterprise AI overview, then choose one workflow. You can use the maintained Enterprise implementation or build the same application-specific layer yourself from public Kumiko features, handlers, jobs, screens, and provider adapters.

Prerequisites

Kumiko Enterprise access, a running tenant-aware app, and a provider strategy. Use the mock provider for deterministic tests; use a real provider only with a secret-store-managed key and an agreed data classification for prompts and outputs.

Sequence

1. ai-foundation, the provider host and per-tenant provider resolution layer.
2. ai-provider-mock for tests, then ai-provider-anthropic or another production provider.
3. Make your app agent-ready, to describe handlers, declare risk, and close documentation gaps before exposure.
4. AI agent basic, a complete approval-mode agent that can search and close tickets but cannot purge them.
5. ai-pipeline, to make step policy editable per tenant while keeping pipeline structure in code.
6. Provenance and cost control, to track prompt revisions, providers, models, token usage, and output limits.
7. prompt-store, when prompt changes need revisions, audit history, and rollback.
8. designer, when a visual pattern editor should parse, patch, and publish feature definitions.

Recipe

Use AI agent basic for the approval and permission model. Use the Document pipeline recipe for the extract → classify → generate step vocabulary and its mock provider wiring.

Test command

From the enterprise workspace, run the deterministic integration recipes with the repository’s integration configuration. The repository’s test setup supplies the shared environment; the mock provider avoids a real vendor API call:

bun --env-file=../.env test --config=bunfig.integration.toml samples/recipes/ai-agent-basic
bun --env-file=../.env test --config=bunfig.integration.toml samples/recipes/ai-pipeline

Checkpoint

You can explain why an undescribed handler is invisible, why an approval proposal is not a write, where tenant policy is resolved, and which prompt, provider, model, and token facts are retained without persisting the prompt or model response in step provenance.

Next depth

Continue with ai-conversation, ai-patch, and publish when the agent or Designer needs persistent conversations, targeted source changes, or a controlled release path.