# How a site is structured

URL: https://kywi-docs-production.up.railway.app/start/concepts/how-a-site-is-structured
Type: docPage

The vocabulary of a Kywi page — sites, trees, content types, layouts, modules, shared components and media — and where each term is treated in depth.

A Kywi deployment is one running app and one database holding any number of sites. Everything below starts from that: which site a request belongs to, where a page sits inside that site, what a page is made of, and what gets shared across pages rather than owned by one.

## Outside in: a deployment, its sites, and who may touch them

### site

A site is a config entry — an id, a domain, a theme — matched against every incoming request by its Host header, and reconciled into its own database row by that id at boot. Two sites on one deployment share the app process and the database; what differs per request is only which site the Host resolved to. See [One config, several sites](/developing/one-config-several-sites/).

### site membership

A user's role is global — a siteAdmin on one site is a siteAdmin on every site in the install. Site membership is a separate, optional list layered on top of that role, narrowing which sites a user can reach; with no memberships configured, the default, a role applies unrestricted everywhere. See [Managing users, roles, site access](/governing/managing-users-roles-site-access/).

## One tree, and a page’s URL is its place in it

One hierarchy holds every page in a site; each row in it is a node; and where a node sits in that hierarchy is literally its address.

### site tree

Every page in a site lives in one parent/child hierarchy, and three separate gestures act on it: dragging a row only reorders it among its current siblings, "Move to…" is the only gesture that reparents a page, and Copy always duplicates a page as a sibling of the one you copied. See [Shaping the site tree](/authoring/shaping-the-site-tree/).

### content node

A content node is one row in that tree — a page, a folder, a piece of media, or any other item a content type describes — holding its own fields and, where its base type supports one, its own layout document. Every gesture above acts on a node without touching what kind of thing it is. See [Shaping the site tree](/authoring/shaping-the-site-tree/).

### slug and path

A page's URL is the chain of slugs from the site root down to it, worked out once at creation. Editing a title afterwards changes the label and leaves the URL alone; only a deliberate slug change or a move rewrites the path. See [Slugs, paths, and moving a page](/authoring/slugs-paths-and-moving-a-page/).

## Old addresses redirect

After a slug change or a move, the old address redirects to the new one. A page can also be given its own public address, a URL Override, and its tree address then redirects there.

## A page, twice over: its fields and its layout

A page has two halves, edited in two different places: the fields its content type declares, which become real database columns, and the layout document that arranges what a visitor actually sees.

### content type

A content type is a base type plus a list of fields, and any field a type declares becomes a real column in that type's own database table rather than a JSON bag. Declaring a type is a code-level decision — where else a type's shape can come from is its own concept, below. See [Designing a content type](/developing/designing-a-content-type/).

### base type

The base type is what decides which platform behavior a content type gets — content, folder, media, event, gallery, link, form, or component — and any type you declare can use any of the eight. Separately, core ships four built-in types, page, folder, link and form, which the Type Designer shows read-only and offers no way to delete. See [Designing a content type](/developing/designing-a-content-type/).

### field

A content type is built from a fixed set of field types — text, a picklist, a relationship, an image, and more — and a page's Body is one of them, a richText field like any other on the type. Knowing that the Body has no special status is what makes the rest of a type's field list predictable. See [Fields, the body, and the rich-text editor](/authoring/fields-the-body-and-the-rich-text-editor/).

### field type

Every field type collapses onto one of a small number of Postgres column shapes through a single mapping — nothing about a field's label, options or validation reaches the database, only its declared type does. That mapping is also why a field's "required"-ness and its column's NOT NULL constraint are two different things. See [What a field type becomes in Postgres](/developing/what-a-field-type-becomes-in-postgres/).

### layout document

A page's layout is one document — regions of sections of columns of modules — and it has exactly one editing surface underneath two different doors: the admin's Layout tab and the front-of-site "Design on site" overlay both write to the same document through the same save endpoint. See [The Layout tab vs "Design on site"](/authoring/the-layout-tab-vs-design-on-site/).

### region

Which regions a page has is fixed by its theme, not by the page: a theme must declare at least one, and every theme a site can switch between has to declare exactly the same set — core refuses to boot if two of them disagree. A layout only ever fills slots the theme already named. See [Regions, sections, columns and modules](/authoring/regions-sections-columns-and-modules/).

### section / row / column

A variant container — the wrapper A/B testing and personalization put around content — goes around a whole section or a single module, and nowhere else: never around a column, never around a region, and never inside another variant container. The editor refuses those drops rather than letting you build them. See [Regions, sections, columns and modules](/authoring/regions-sections-columns-and-modules/).

### module

A module is the actual content piece dropped into a column — a heading, a card, a form embed. The registry declares 47 built-in modules, but the palette an editor sees is smaller: a deprecated personalization module and Section itself are held back from everyone, and one module is admin-only, so what a typical editor drags from is 44. See [The module palette](/authoring/the-module-palette-47-built-ins-in-seven-categories/).

### module category

The palette groups its modules into seven categories — Layout, Elements, Objects, Navigation, Personalization, Compliance, Saved — and what a given editor sees inside each category can differ by role, since the admin-only module sits in Elements. See [The module palette](/authoring/the-module-palette-47-built-ins-in-seven-categories/).

### module prop

Once a module is on the page, its own properties are editable from a rail with no developer needed, and every module additionally carries a fixed Style Overrides section — exactly four free-text CSS properties, nothing more, nothing configurable per module type. See [Module properties, theme tokens, Style Overrides](/authoring/module-properties-theme-tokens-style-overrides/).

## What is shared between pages, rather than owned by one

Everything below is defined once and drawn on from many pages. The distinction to keep hold of is whether reaching for one takes a copy or keeps a live link.

### saved layout (blueprint)

Saving a design as a layout makes a one-time copy: placing it drops its sections into the page as ordinary, disconnected sections, and editing the saved layout afterwards never reaches back into a page that already used it. Think of it as a starting point you copy, not a thing you keep pointing at. See [Reusing a design: layouts vs components](/authoring/reusing-a-design-layouts-vs-components/).

### saved component (linked)

Saving a design as a component is the opposite: the placement keeps a live link, and every page that placed it renders whichever definition the component currently has — published pages included, with nothing to republish. A component nested inside a saved layout stays linked even though the layout around it does not. See [Reusing a design: layouts vs components](/authoring/reusing-a-design-layouts-vs-components/).

### section template

One phrase, two unrelated things in the editor. Saved layouts are stored in a table named `kywi_section_templates` and inserted from what the code calls the section-template picker — the same one-time copy as saved layout (blueprint), above. The editor also uses the same phrase for the seven column-width presets you pick from when adding a section. See [Reusing a design: layouts vs components](/authoring/reusing-a-design-layouts-vs-components/).

### collection

A collection is not a single object in Kywi. It is three things working together: a folder of content nodes holding the items, a feed that queries them, and a Feed Display module that renders what the feed returns. Building one means building all three — and then adding an item to the folder is all it takes for every page to update. See [Feeds](/authoring/feeds/).

### feed

A feed is a saved, named query over one content type, built once and then pointed at by slug from any number of Feed Display modules instead of re-specifying the same query on every page that wants the same list. The public site always forces a feed's results to published content, whatever status the feed's own saved query allows. See [Feeds](/authoring/feeds/).

### menu / menu item

Left alone, navigation is generated straight from the tree. A menu is a separate, hand-built structure for the shapes the tree can't produce — an external link, a heading-only item, an order that diverges from the tree. A menu item linking to a page stores no URL of its own; it looks the page's current address up live, so a move never leaves it stale. See [Menus](/authoring/menus/).

### media item

A media item is an uploaded image or file, scoped to the site it was uploaded on. Deleting one that a page still references is blocked by default — the library shows which pages reference it before you can force the delete through — and even a forced delete moves the file to Trash rather than erasing it outright. See [Media](/authoring/media/).

### media variant

A media variant is a resized derivative of an uploaded image, generated once at upload time from the sizes your project configures and served from a fixed key — asking for a size that wasn't configured then is a 404, not an on-the-fly resize. See [Media: upload, serving, variants, resize](/integrating/media-upload-serving-variants-resize/).

### category

A category groups content and can nest under another category, so it works as a hierarchy; a single piece of content can carry any number of categories at once. Deleting a category is immediate — content carrying it simply loses the assignment, with no trash to recover it from. See [Categories and tags](/authoring/categories-and-tags/).

## Child categories move up a level

Deleting a category moves its child categories up one level, to its own parent or to the top level. The delete is refused if a moved child's slug is already taken at that level, and then nothing changes.

### tag

Tags are the flat half of the pair — the same assignment model as a category, without the nesting. What matters is the delete: it is immediate and there is no trash. The confirm dialog's count of how much content carries the tag is a courtesy, not a gate, and every piece of content carrying it loses that assignment in the same operation. See [Categories and tags](/authoring/categories-and-tags/).

### locale

The set of locales a site supports is declared in code, not managed from the admin — the Translations surface only shows and manages which pages exist in which locale, not the locale list itself. See [Translations](/authoring/translations/).

### translation

A translation is not a locale-switched view of one page — it's a genuinely separate content row, with its own id, related to its source only by convention: the same slug and parent, a different locale. Creating one copies the source's fields, all but its URL Override, and its full layout, but always starts the new row as a draft. See [Translations](/authoring/translations/).
