# How the platform fits together

URL: https://kywi-docs-production.up.railway.app/start/concepts/how-the-platform-fits-together
Type: docPage

Where the engine ends and your project begins: host app, layers, themes, plugins, hooks, adapters, webhooks, caching, migrations and AX surfaces.

Kywi is a package your project mounts, not a framework your project lives inside of. That distinction runs through every term below: what the engine owns outright, what a project supplies on top of it, and what the platform keeps and publishes without either side having to ask.

## The seam between the engine and your project

### host app vs core engine

Core cannot import your `kywi.config.ts` — a published package has no path back into the project that installed it — so the inversion runs the other way: your project hands it in once. What a host app owes core is five thin wiring files plus three stylesheet imports Next keeps out of the package; the whole rest of the render path is core's, and upgrades with it. See [The host-app contract](/developing/the-host-app-contract/).

### deployment mode

Deployment mode is a required field answered once, at scaffold time, and it decides exactly one thing: which files `create-kywi-app` writes. Nothing in core branches on it at runtime — coupled additionally gets the public render path, while headless and decoupled emit a near-identical file set differing only in a comment and a README section. See [The three deployment modes](/integrating/the-three-deployment-modes/) and, for the choice itself, [Coupled / headless / decoupled](/start/coupled--headless--decoupled/).

## One codebase, several looks

### layer

Three layers, and core is one of them: core owns a working default for everything renderable, so a project supplying nothing below it still renders. Under core sits the site layer, `sites/<slug>/`, for overrides shared across that site's themes, and inside it the theme layer for presentation. Configuration does not move down — it stays in `kywi.config.ts`. See [What the scaffold generates — and what it deliberately doesn't](/developing/what-the-scaffold-generates--and-what-it-deliberately-doesnt/) and [The host-app contract](/developing/the-host-app-contract/).

### override by placement

Resolution runs theme → site → core, first hit wins. A lower layer overrides by supplying a same-named artifact, never by editing the one above — which is what lets an upgrade replace core wholesale. And the chain is not a filesystem scan: a generated registry, `kywi.layers.ts`, enumerates it at build time and is rewritten on upgrade, not hand-edited. See [What the scaffold generates — and what it deliberately doesn't](/developing/what-the-scaffold-generates--and-what-it-deliberately-doesnt/) and [The host-app contract](/developing/the-host-app-contract/).

## What a project styles and configures on top

### theme

A theme is a small, fixed shape — a name, the regions it defines, and optional tokens, personalization settings and a custom-value policy — declared in code and named by a site's own config, not something an admin can switch. What a theme visually draws lives in its layer, keyed by the same name; what it declares about itself lives in this object. See [Themes and design tokens](/developing/themes-and-design-tokens/).

### design token

A design token is a named value in one of a theme's five categories — colors, spacing, typography, border radius, shadow — emitted as a `--kywi-*` CSS custom property on every request, keyed to whichever site the Host header resolved to. A token suffixed `@breakpoint` becomes a media-query override of the same variable rather than a second variable. See [Themes and design tokens](/developing/themes-and-design-tokens/).

## Five ways to extend a running project

### plugin

A plugin is a config entry, declared inline or referenced by package name, that can contribute hooks, content types, modules, scope extensions and admin nav items. One whose content type or module name collides with the app's own is silently dropped in the app's favour; one that fails to load is skipped rather than taking boot down. See [Plugins: what one can contribute, and when](/developing/plugins-what-one-can-contribute-and-when/).

### hook

A content type declares nine lifecycle hooks, and only `validate` can stop a write; the rest transform data or observe after the fact. Underneath sits a much wider event bus that comments, trash, versions and more dispatch onto and plugins subscribe to by name — but nothing on that bus can reject anything: it fires only after the write is decided. See [Hooks: content-type hooks and the event bus](/developing/hooks-content-type-hooks-and-the-event-bus/).

### adapter (pull / push)

An adapter is a small typed object — an id, a side, field names, one function — that feeds the audience rule builder from outside the platform. A pull adapter runs: something calls it, and what comes back becomes signals a rule can match on. A push adapter type-checks and registers identically, but nothing anywhere calls it. See [Signal adapters: feeding the audience builder from code](/developing/signal-adapters-feeding-the-audience-builder-from-code/) and [Audience adapters: third-party CDP integration](/integrating/audience-adapters-third-party-cdp-integration/).

### webhook event

A webhook event is one of eleven named lifecycle moments — content published, a comment approved — an endpoint can subscribe to; Kywi signs the exact bytes it sends with an HMAC over your endpoint's secret. Saving a page's layout is not on the list: it dispatches a different event that only invalidates caches, so an endpoint waiting on the closest-sounding webhook never fires. See [Webhooks](/integrating/webhooks/).

### scope

In the SDK, a scope is one typed slice of the REST API — `content`, `media`, `nav`, and fourteen more, seventeen in all. Large parts of the API have no scope at all: audiences, experiments, changesets, bulk operations and cache administration are calls you make with a plain `fetch` and your own types. See [The SDK: what it wraps and what it doesn't](/integrating/the-sdk-what-it-wraps-and-what-it-doesnt/).

## What the platform keeps and publishes on its own

### cache key namespace

The server cache is keyed by a fixed set of namespaces, each prefixed by the site it belongs to — content, feeds, nav, menus, the resolved site config, one per AX surface. One content mutation clears several at once, which is what makes a publish visible immediately rather than after a TTL. The admin's clear-cache action, though, is deployment-wide rather than site-scoped. See [Caching semantics for an integrator](/integrating/caching-semantics-for-an-integrator/) and [Cache administration](/operating/cache-administration/).

### migration journal

The migration journal is the record of every schema change `kywi migrate` has applied, grown by `drizzle-kit generate` each time the command runs. Push-mode migration writes straight to the database without touching that record, which is why it is refused on a project that already has a journal and banned from a deploy hook. See [Running migrations against a live database](/operating/running-migrations-against-a-live-database/) and [Why drizzle-kit push is banned before deploy](/operating/why-drizzle-kit-push-is-banned-before-deploy/).

### Agent Experience (AX)

Agent Experience is the collective name for six machine-facing surfaces a Kywi site publishes without an API key or a session, all configured from one block. Every surface defaults on except the per-page Markdown twin, which defaults off, and the cacheable ones clear on the same content-mutation event the rest of the cache does. See [AX surfaces as a machine-readable feed](/integrating/ax-surfaces-as-a-machine-readable-feed/) and [The `ax` block: what your project publishes to machines](/developing/the-ax-block-what-your-project-publishes-to-machines/).

### extension subtype / attribute set

Extension attributes are the third way to add fields to content, and the only one that adds no column and needs no migration, ever. A subtype and its attribute set define what an extension can hold. The cost is reach: a value stored this way is reachable only by content id, so it cannot back a feed or an audience rule. See [Config types, Type Designer types, and extension attributes](/developing/config-types-type-designer-types-and-extension-attributes/).
