Skip to content

Config as code vs. the database

Content types, themes and modules are code; pages, menus, audiences and admin-created types are rows — and the boundary decides what a deploy can change.

The line runs through the content model itself, not around it: a content type can come from kywi.config.ts or from the admin's Type Designer, and both kinds are live in the same registry. What separates them is who can change them and when — a config type moves on a deploy, an admin type moves on a save.

Where the two halves meet

Once, at boot. Building the API handler loads the admin-defined fields and admin-created types out of the database and merges them with the config's into two maps — content types, and the generated tables behind them. Those maps are mutated in place and never reassigned, deliberately: route handlers capture the reference at registration, so a schema reload is visible to them immediately, with no server restart. A type added in the Type Designer is servable before the next deploy; a type added to the config is not there until one.

Provenance travels with the shape

interface ContentTypeConfig { source?: 'config' | 'admin'; /* … */ }
interface FieldDefinition   { source?: 'config' | 'admin'; /* … */ }
Set on admin-created types and admin-added fields; config declarations leave it unset. It is what tells the admin which parts of a type it may offer to edit.

The flag is per field, not only per type, so a config-owned type can carry admin-added fields and the designer will let you edit exactly those. See Config types, Type Designer types, and extension attributes for how the two are edited side by side.

Config-only, because these are functions

A database column cannot hold a closure, so anything expressed as one lives in the config and only there: the access predicates on a type (read, write, publish, delete), the nine content-type hooks (validate, beforeCreate and afterCreate through afterPublish and afterUnpublish), an ax.jsonLd type mapping's transform escape hatch, a signal adapter's collect or transform, and a plugin's init and scopeExtensions. There is no admin surface for any of them, and there cannot be one. Hooks are covered in Hooks: content-type hooks and the event bus, access predicates in Access control in kywi.config.ts.

Database-only, because they are content

Everything an editor or a site admin creates at runtime: pages and their version history, menus, media, feeds, audiences, experiments, changesets, comments, per-document permission overrides, per-site settings. And admin-created content types, each of which gets its own generated kywi_ct_<name> table. None of it is expressible in kywi.config.ts, and none of it should be seeded by hand in SQL — Seeding structure as code is the supported route.

kywi_sites is the one table your config owns

Since 0.23.0 the runtime reconciles kywi_sites against config.sites at init, before anything reads the table — creating a missing row and updating name, domain, defaultLocale and theme in place, matched on the config id as the row's slug. Those four columns are config's; editing them in the database is editing something a boot will overwrite.

Typed, validated, and read by nobody

Two cache keys are worth knowing about before you tune them. cache.contentTtl is real — it becomes the TTL of the cached content queries. cache.feedTtl, cache.navTtl and cache.defaultTtl are typed, validated by the config schema, and reported back by both GET /cache and the config export, but no cache path reads them; setting one changes what the admin displays and nothing else. mode is in the same position at runtime: it selected which files the scaffold wrote and is now only reported. Neither is a bug you can work around in config — treat the values as descriptive until they are wired.