How the platform works

Everything in this guide follows from one design decision: the engine and the user interface are completely separate. This page explains that separation and the few concepts that fall out of it. If you understand this page, the rest of the platform is detail.

The kernel is a pure engine

The kernel is the platform’s engine. It interprets metadata, serves and stores data, and enforces access on every operation. It exposes APIs and a command-line tool. What it does not contain is an application: there are no built-in screens, no built-in navigation, no built-in setup app compiled into the engine.

The kernel ships exactly two surfaces of its own — a sign-in screen and an empty-workspace landing (what an org shows when nothing else is installed). Everything else a user ever sees is metadata the kernel renders.

This is the whole game. Because the engine renders metadata rather than code, the same engine can present any application. You change what an org is by changing its metadata, not by changing the engine.

Metadata versus data

Two different things live in an org, and keeping them straight is the key to building well:

• Metadata is the shape of the org — the definitions of objects, fields, record types, page layouts, list views, apps, pages, permission sets, automation, the design system. Metadata is what you author and deploy. It changes at the cadence of a release.
• Data is the contents — the records that fill those objects. Data changes at the cadence of a request.

The kernel reads metadata to know how to render and behave, and reads data to fill in the specifics. A page layout is metadata; the account you are looking at through it is data. Build the shape in metadata; keep the contents in data.

UI is metadata, delivered by packages

Since the engine has no application of its own, the user interface has to arrive from somewhere. It arrives as metadata, delivered by installable packages.

A package is a versioned distribution of metadata. It may bundle apps, pages, components, permission sets — and, crucially, it may claim a platform capability. The kernel exposes a fixed set of capability slots, and a package can register as the master of one:

• the shell — the header, navigation, global search, the app switcher;
• the setup app — the administration surface;
• and others.

The kernel enforces one master per capability. It also exposes injection points, so a package can extend a capability it does not own — add an item to the avatar menu, contribute a setup page — without replacing the master. The standard platform experience is simply a set of packages (a shell, setup, apps) installed into an org. Remove them and you are back to the empty workspace.

A package does not extend the engine. Even the package that masters setup only edits metadata the kernel interprets; the enforcement engine underneath — the part that checks access on every read and write — stays in the kernel and cannot be swapped. The line is: the engine owns the rules; a package owns the editor and the presentation.

The API is the floor

There is exactly one way metadata changes an org: a validate-and-commit operation. Metadata is validated against its schemas and referential integrity, then applied in one transaction, or rejected whole. Nothing is half-applied.

Three front doors reach that one operation:

• the CLI — the developer’s ergonomic client, with an on-disk source format, diffing, and schema-aware editing;
• the API directly — for programmatic and headless automation;
• installing a package — the same validate-and-commit run over a versioned bundle and its capability registrations.

“Install” is not a special mechanism. It is the same commit, run over metadata someone else authored and shipped as a managed unit. Because the API is the floor — it needs no package to exist — an org is never trapped: an administrator can always reach the engine over the API to install, remove, or reconfigure anything, even with no UI installed at all. Headless operation is a first-class mode, not a fallback.

What the kernel renders, in order

When a request comes in, the kernel resolves it in a fixed order:

1. Resolve the org from the domain; require a session (or show the sign-in screen).
2. Fetch and validate the org’s metadata.
3. Resolve the shell capability. If no shell is installed, render the empty workspace and stop — this is a valid empty state, not an error.
4. Apply the design system, then render the shell’s surfaces.
5. Resolve the current route — app → tab → object → page → template → components — and render it inside the shell’s content region.
6. Fetch data last, and every read passes through the access engine.

Two things follow. First, swapping the shell package changes the entire frame with no change to the engine. Second, error and empty states before a page resolves — an unknown route, a missing record, an unauthorized request — are the kernel’s responsibility, because no installed metadata exists yet to own them; the kernel guarantees a legible fallback, and a package may present a branded version of it.

Where this goes next

• Getting started turns this model into commands — provision, sign in, and make a first change.
• The developer surface maps every kind of metadata you author onto where it is documented.

For how the engine itself is built — services, caching, boot lifecycle, the instance and trust topology, the full API family taxonomy — see the architecture site.