# Shaping the admin your project ships

URL: https://kywi-docs-production.up.railway.app/developing/shaping-the-admin-your-project-ships
Type: docPage

The admin is a registry of surfaces grouped into 25 areas; config denies areas or surfaces at build time and a per-site settings row does it at runtime.

Every admin route is a declared entry in one typed registry — an id, a feature area, a URL pattern, a minimum role and a lazy component loader — not a page in your app. That is what makes the admin subtractable: you never delete a route, you deny an id.

## Areas and surfaces are two different granularities

An **area** is the feature taxonomy: 25 of them, from `dashboard` and `contentTree` through `audiences`, `experiments` and `changesets` to `settings` and `account`. A **surface** is one route inside an area — a list, a new form and a detail view are three surfaces, each its own lazily loaded chunk. Sixty-three make up the shipped admin; thirty-eight appear in the sidebar across six sections (five labelled, plus an unlabelled overview group), and the other twenty-five — the same count as the areas, coincidentally — are unlisted surfaces: detail routes, create forms, utilities like `media.upload` and `search.index`, and the account password screen.

## Config is the ceiling

The `admin` block is a denylist that defaults to on. An absent block, an area you did not mention, a surface you did not list: all enabled. Only an explicit `false` or an explicit id removes anything. Deny an area and everything in it goes; deny a surface id and one route goes while its area stays.

admin: { // enabled: false would leave an API-only host with no admin at all features: { experiments: false, // the whole area, nav rows included translations: false, }, disableSurfaces: ['media.upload'], // one route, area otherwise intact },

## kywi.config.ts

A denied surface is not a 404. Core answers a genuinely unknown admin path with one, but a known route held off by the ceiling renders the shell's own "disabled" message — so a link into it from a bookmark or an old doc explains itself instead of looking broken.

## A typo in admin.features fails kywi migrate, not the build

Unknown keys are not dropped — they are carried forward so validation can reject them, but that validation runs only through `kywi migrate`, not at build or boot — see [Startup assertions — the config errors that fail a deploy](/developing/startup-assertions--the-config-errors-that-fail-a-deploy/). So `{ features: { medai: false } }` produces *Unknown admin area "medai" in admin.features. Valid areas: …* the next time you run `kywi migrate`, while boot starts with the typo'd flag having no effect. `disableSurfaces` is checked the same way, rejecting `login` (not a registry surface) and `settings.adminFeatures` (the escape hatch below).

## Runtime flags are per site, and softer

The second lever is a single `kywi_site_settings` row keyed `admin.features`, holding a flat map of area or surface id to boolean. It is per site rather than per deployment, so one site can hide Experiments while another keeps it — see [One config, several sites](/developing/one-config-several-sites/). Like the config block it is active-by-default: no row, or no entry, means enabled.

The two compose as an AND, with config as the hard floor: a surface renders only if the config ceiling allows it, the runtime flag does not deny it, and the signed-in user clears its `minRole` — see [Roles and the capability matrix](/governing/roles-and-the-capability-matrix/) for the third term.

## Two surfaces you cannot lock yourself out of

The superAdmin **Admin Features** surface survives both levers, even a disabled `settings` area, because it is the only way to undo a runtime lockout. The account password screen survives them too and carries no role gate: a forced-reset user is refused every other route, so gating the one screen that releases them would brick the account. Only `admin.enabled: false` removes either.

## Your layers reach the admin, minus their templates

The admin route gets the same `kywi.layers.ts` registry the public route does, so the layout editor can render your custom modules — but not your templates: core strips the `templates` key from every layer first. The admin app is a client component, while `hydrateLayout` and `shell` are server-only, and either one crossing that boundary throws and takes down the whole admin, not just one surface. The strip removes the whole key rather than a list of known names, so a new template slot cannot reintroduce the failure; site and theme keys survive it.
