Platform Architecture Overview

CAOS is a metadata-driven application platform: a small, fixed engine that renders and runs applications described entirely by metadata. It shares a category with Salesforce — a white-label platform where objects, fields, layouts, permissions, apps, and whole user interfaces are data that can be authored, versioned, deployed, and queried — but it is deliberately not a CRM. It is the layer beneath verticals: an empty org can become a CRM, an ERP, a CMS, an e-commerce back office, or a project-management tool, depending on the metadata it is shaped with (see org shapes and the ecosystem). It is built to be easier to learn, cheaper to run, and far more flexible about both what the product becomes and how it looks than Salesforce is.

The organizing decision that separates this generation of CAOS from everything before it:

The engine knows nothing about the user interface. All UI and UX are metadata.

There is no screen, no theme, no header, and no navigation compiled into the platform. Those are things an organization installs — as metadata — on top of an engine that, by itself, renders only an empty page.

The founding principle: separate the engine from the interface

Every prior attempt baked pieces of the interface into the engine — a login screen here, a shell layout there, a theme token set somewhere else. Each of those is a place where the platform’s look becomes un-overridable and a customer’s flexibility ends. This architecture removes that category of mistake by construction: if it is UI or UX, it is not in the kernel.

The platform therefore has four distinct planes, and a change is always in exactly one of them:

Plane	What it is	Examples
Kernel	The engine. Platform logic + a set of exposed APIs that interpret metadata. No UI.	Metadata interpreter, access engine, the API + CLI surface, local authentication, the read-only metadata-of-metadata layer.
Metadata	The authored content of an org that the kernel interprets. Deployable, versioned, queryable.	Objects, fields, layouts, list views, permission sets, apps, page/component definitions, branding.
Packages	Versioned distributions of metadata — optionally namespaced, optionally locked — that can register for and satisfy platform capabilities.	CAOS Core (the shell), Setup, Guidance Center, Report a Bug, AI, Sales Atlas.
Authoring surface	The only ways metadata enters an org: author it with the CAOS CLI or the platform API, or install a package that carries it. All three commit through the same validated write path.	The caos CLI, the deploy/query APIs, package install, and the local VS Code tooling that drives them.

Because the authoring surface is the same tooling we hand to customers, building the platform’s own standard interface and building the customer-facing toolchain are one effort, not two. We dogfood from the first line.

The empty workspace — what the engine renders alone

Provision an org, install nothing, log in, and the engine renders a designed empty-workspace landing: a finished “no apps installed” page — kernel online, workspace awaiting a shell — with actions to install a shell or deploy an app. This is not a placeholder or a blank void; it is the correct output of the engine when no UI metadata exists to interpret, and it is deliberately a real, on-brand screen so a first-time org looks finished rather than broken.

It is painted in the kernel’s baked-in default design system — the platform’s own first-generation look. This is the one design system compiled into the engine, for exactly two surfaces: the sign-in screen and this empty-workspace landing — the screens an org needs before any package exists. They are the only UI the engine renders that a package did not put there; the moment a shell and apps install, installed metadata takes over every surface. The baked-in default is a fixed provisioning-time signature — frozen against later rebrands and overridden by any installed brand — so it does not make the kernel opinionated about how a finished product looks. (The reasoning and boundary are detailed in the Kernel document.)

To change what the org renders past that landing, metadata has to land in the org — and there are exactly three surfaces that put it there:

1. The CLI — you author metadata locally and caos deploy it.
2. The API — a program writes metadata in directly (the CLI is itself a client of this; see below).
3. Installing a package — you take someone else’s finished, versioned bundle of metadata and install it into your org, from the marketplace or a file.

All three end at the same place: metadata rows in this org, validated and committed by the kernel. The first two are how you author your own metadata; the third is how you adopt metadata someone else already authored. Reload the org’s URL after any of them and the engine now finds metadata describing a shell, an app, a component — and renders it. This is the whole model in miniature: the kernel is a set of hooks; three surfaces write metadata into the org; the engine interprets it on load.

Under the hood — what these three surfaces actually do

The visibility is worth spelling out, because it demystifies the whole platform:

• The API is the one true door. Every write to an org — a single field, a whole app, an entire package — is the same primitive: validate a set of metadata documents against their type schemas, then commit them transactionally. Nothing reaches the metadata store except through that primitive.
• The CLI is a client of the API, not a second engine. caos deploy reads your local JSON source, diffs it against the target org, and calls the deploy API. It adds developer ergonomics — a project format, a git-friendly diff, schema-aware editing — but every byte it writes goes through the same validate-then-commit API a program would call. There is no “CLI-only” path into the org.
• Installing a package is that same commit, over a bundle. A package is just a versioned, self-describing collection of metadata documents plus its capability registrations. “Install” means: resolve the package’s namespace and dependencies, run the same schema validation and referential-integrity checks a deploy runs, register whatever capabilities it claims (subject to the one-master rule, below), and commit the whole set in one transaction. The difference between “I deployed my app” and “I installed a package” is not the mechanism — it’s who authored the metadata and whether it arrived as a managed, versioned unit.

So the honest one-liner is: there is one way metadata enters an org — the validate-and-commit API — and three front doors to it. The CLI and package install are conveniences layered on the API, not separate powers.

Packages vs. apps vs. metadata — telling them apart

These three words get used interchangeably, and they shouldn’t be. This section isn’t the full definition of each — the Object Model gives packages their complete treatment (namespacing, locking, versioning, dependencies). The point here is only to draw the boundaries so the rest of the overview reads cleanly:

• Metadata is the raw authored content — an object, a field, a list view, a page, a permission set. Metadata is the atom. Not everything is wrapped in a package: metadata can be authored and deployed directly to an org with the CLI or API.
• A package is a distribution unit — a bundle of metadata you install as one versioned thing, carrying its own capability registrations. Its defining power is that it can register to become, or to extend, a platform capability (the shell, the setup app, …). A package can be namespaced or un-namespaced, and locked (managed) or unlocked — those are options a package chooses, not requirements; being a package does not force a namespace on you. The full matrix lives in the Object Model.
• An app is one kind of metadata — a named surface in the App Launcher, a bundle of tabs and branding. An app is a thing you build; a package is a thing you ship. A package may contain an app (or several, or none), and an app can be authored directly without ever being packaged.

So the mental model is: metadata is what you author, an app is one shape metadata takes, and a package is how metadata travels. You install packages; packages may carry apps and other metadata; but building on the platform does not require a package. Packages exist specifically for distribution and for anything that must claim or extend a platform capability.

Capabilities and contracts — how the interface gets owned

The kernel exposes a fixed set of capabilities — named roles a package can claim, such as the shell or the setup application. The rules are uniform:

1. One master per capability. Only one installed package may be the shell; only one may be the setup app. The kernel enforces this.
2. Contracts, not implementations. To claim a capability, a package must satisfy that capability’s contract — the set of things the kernel guarantees will exist because the capability is filled. The kernel does not care how the package renders them.
3. Injection points for everyone else. A capability master must expose the extension points the kernel requires, so other packages can contribute without owning the capability — inject an item into the avatar menu, register a page under the setup menu, add a surface to the shell.
4. Policy is exposed, not hard-coded. Whether a second package may seize an already-owned capability (e.g. replace the shell) is itself a setting the owning package surfaces — not a rule welded into the kernel. The kernel provides the mechanism; the package decides the policy.

This is why the platform can look like anything. A third party can ship a completely different shell — left rail instead of top bar, a different template entirely — and as long as it satisfies the shell contract, the engine runs it.

The shell contract, in brief

The default outer template is a global header over a main canvas. The CAOS Core package claims the shell capability and provides, at minimum:

• an impersonation banner,
• a global header — environment chip, global search, help, notification bell, avatar menu, a company-name slot, and the light/dark theme switch,
• an app-navigation strip (an app’s top-level tabs),
• a record-tabs strip, and
• a navigation system and app switcher.

Each of these is an injectable surface. The full contract — required surfaces, required injection points, and what a replacement shell must guarantee — is specified in the Shell document. The point of the overview is only this: the shell is installed, not built in.

The standard packages

The “CAOS platform experience” is simply a known set of packages installed together:

• CAOS Core — claims the shell capability: global header, app-nav, record tabs, app switcher.
• Setup — claims the setup capability; lets other packages register their own setup pages (each contributor brings at least one setup group containing one or more pages).
• Guidance Center — an edge-anchored guidance surface; ships its own setup page for admin options.
• Report a Bug and AI — two edge-anchored custom surfaces (the bottom-right orb and a pinnable right-edge panel) that share components but are distinct packages; each ships its own setup page.

“Edge-anchored” means a surface that lives pinned to an edge of the viewport — a corner orb, a slide-out right rail — above the app rather than inside it. Unlike an app’s tabs or a record page, an edge-anchored surface is always reachable no matter which app or record you’re on, because it’s mounted to the shell’s frame, not to the current route. It’s the opposite of in-flow content (nav tabs, list views, record pages) that occupies the main canvas and changes as you navigate.

• Sales Atlas — the first CRM application package (the “Sales Cloud” analog; Atlas is the CAOS product-line word — Sales Atlas, Service Atlas, Field Atlas — after Atlas, the first king of Atlantis in Plato’s telling and the figure the island itself is named for).

“Not privileged by the kernel” — what that means, precisely

None of these packages is special-cased in the engine. The kernel has no if (package == "Setup") anywhere; each package earns its place purely by satisfying a capability contract, and each could in principle be replaced by a different package that satisfies the same contract. That is the sense in which none is privileged: the engine treats CAOS Core exactly the way it would treat a third party’s competing shell.

But “not privileged” is not the same as “the kernel has no stake in what they do.” There’s a firm line, and it’s the same line everywhere on the platform:

The kernel owns the engine; a package owns the editor and the presentation of that engine.

Permissions are the cleanest illustration. The engine that enforces permissions (evaluating grants, field-level security, and sharing on every read and write) is in the kernel and cannot be swapped; it is what makes the platform safe, so it can’t be metadata a package overrides. But which permission sets exist, what they’re named, who’s in them, and the point-and-click page an admin uses to edit them are metadata and package surfaces. A package ships the editor for permissions; the kernel ships the engine that obeys them. Which package is decided by one rule — a page that administers a thing belongs to the package that defines that thing — so because permissionSet is kernel-defined, the permissions editor ships with the package that surfaces the kernel rather than with the one that masters the setup capability. Setup is where it is shown, not where it lives. A different package could present that editor completely differently — but it would still be driving the same kernel permission engine underneath, because there is only one, and it is not overridable.

So each “core” setup capability splits the same way: an enforcement/interpretation engine in the kernel (permissions, the object/data engine, the metadata interpreter, referential integrity) that no package can replace, and a configuration surface in a package (the Setup pages that read and write that engine’s metadata) that any conforming package could re-implement. The Setup package is the master of the setup capability — only one package may own it, and it exposes injection points so other packages (Guidance Center, Report a Bug, …) register their own setup pages under it — but even the master is only editing metadata the kernel will interpret; it is not extending the kernel.

The platform is not an application — org shapes and the ecosystem

Everything above has a strategic consequence worth stating at altitude: CAOS is not a CRM, and must never be branded as one. Salesforce’s “Cloud” is a vertical — Sales Cloud, Service Cloud. CAOS is the layer beneath all verticals. A CRM, an ERP, a CMS, an e-commerce back office, a project-management tool, a marketing-automation system — each is only a particular set of objects, apps, a shell, and workflows. So an empty CAOS org can become any of them, because each is a configuration, not a separate product.

Org shapes

The first-class concept this implies is the org shape: a provisioning template — a bundle of packages, default metadata, and a starting configuration — that makes an empty org become a class of system. Provisioning a “CRM org” or a “CMS org” means applying that shape to a new org. An org shape is therefore a provisioning artifact, which is one reason provisioning is architected early rather than bolted on. A shape is not itself a license (licensing is treated separately, below); it is the metadata that gives an org its initial identity. First-party shapes and third-party shapes are the same kind of thing.

Why the ecosystem is larger than an app store

Because the shell and every capability are packages that claim contracts, the unit a vendor can sell is not “an app confined inside a fixed frame” — it is the frame itself, and any capability, up to the whole shape of the org. A third party can ship a distinct shell, a distinguishing look-and-feel, entire capability sets, or a complete application class that resembles the default platform experience in no way at all. That is a categorically larger surface to build a business on than a platform that only permits apps inside its fixed chrome, and it is what makes a marketplace an ecosystem rather than an add-on catalog. Vendors build against published, versioned capability contracts, never against the platform’s internals, so the quality of those contracts determines the health of the ecosystem.

An ecosystem of ecosystems

Each application class grows its own vendor ecosystem — CRM vendors, ERP vendors, CMS vendors — and one kernel hosts all of them. First-party branded variations of the standard shells and packages, whole first-party application classes, and third-party equivalents at every level all coexist on the same engine. That is the sense in which the platform is an ecosystem of ecosystems.

One platform, many systems — federation is a capability, not custom code

A customer may run several systems at once — a CRM, an ERP, a CMS. There are two provisioning choices, and the platform serves both natively; the customer never writes navigation code to stitch them together:

• One org, many apps. A single org houses every system as separate apps over one metadata graph. Cross-references are trivial because everything shares that graph; licensing, security, and isolation are shared too. Suited to smaller footprints.
• Federated orgs. Each system is its own org on its own subdomain (by the domain-resolves-the-org rule), giving clean isolation — separate data, shape, and security boundary. Suited to larger footprints that want systems kept apart.

Which of the two applies is a provisioning decision, and the ability to federate is itself a platform capability — not a bespoke integration a customer builds. When orgs are federated, the platform provides the linking:

• Linked workspaces. Federated orgs can be linked so that edge-anchored surfaces — the AI assistant above all — and cross-system navigation span the linked set without forcing a user to switch orgs. Working inside the ERP org, a user reaches the same assistant and the same master navigation as in the CRM org.
• Branding is per-org, shared or distinct by choice. Each federated org is provisioned independently, including its white-label design system. A customer may apply one shared design system across the whole linked set, so the experience reads as a single seamless system even while crossing subdomains — or brand each system distinctly. The choice is theirs, per org; neither is imposed.

Cross-system data flow is where the two boundaries that matter meet: a security boundary (each federated org is its own tenant boundary, so a CRM quote spawning an ERP order crosses that boundary through governed events and APIs, never through shared tables) and a license boundary (what one system is entitled to does not silently extend to another). Both are enforced by the platform, not left to the customer to police.

Licensing and entitlements

Licensing attaches to real cost and to intellectual property — never a flat toll for merely combining system types. An org shape dictates its license through the infrastructure it requires, not through its name: a shape whose needs are met by the platform’s baseline infrastructure is included in the platform license, while a shape that requires infrastructure beyond that baseline carries a tier license priced to cover it. The layers:

1. The platform license — the right to run on CAOS, including any org shape whose infrastructure is already covered by the baseline every org runs on.
2. The infrastructure tier (by org shape) — a shape that requires infrastructure beyond the baseline (for example an analytical/warehouse tier, a search cluster, high-volume event ingestion, or always-on model hosting) carries a vertical tier license. It is priced upfront to cover that infrastructure — a known figure per shape, not a metered pass-through and not an itemized exposure of hosting cost. Which shapes fall into this tier is determined by each vertical’s actual infrastructure footprint, assessed against the baseline. Because the tier is keyed to the infrastructure, it applies regardless of who authored the vertical software: a third-party ERP or CMS package set that meets the tier’s criteria incurs this license in addition to the third-party package fee in (4).
3. First-party vertical products — licenses for the platform’s own branded versions of a vertical (a first-party CRM, ERP, or CMS package set), sold above the platform license. This licenses the IP of a ready-made system — distinct from the raw capability to build one, and distinct from any infrastructure tier that shape also requires.
4. Third-party marketplace packages — vendors set their own pricing; the platform meters and enforces their entitlements.

Entitlements are the enforcement layer beneath all four: a queryable, kernel-checked record of what an org is licensed to use, so the infrastructure tier, first-party products, and third-party packages are each gated at runtime. The guiding principle: a customer pays for infrastructure that genuinely costs money and for IP they did not build — the shape’s infrastructure footprint sets the tier, known in advance, never a per-usage meter.

The baseline that decides what is included

Every org runs on a fixed baseline whose reach is wider than it first appears, and that reach is what determines which shapes are included in the platform license. It provides, at minimum: a managed relational database with vector search, a scheduler, and a database-native job queue; realtime subscriptions and connection pooling; edge compute; object storage with a CDN and on-the-fly image transformation; and durable, queued background jobs. Because the baseline already supplies the worker, queue, media, and image tiers that self-hosted business applications normally add themselves, most verticals require nothing above it.

Which shapes require the infrastructure tier

Org shape	On the baseline?	Additional infrastructure, and when it applies
CRM	Yes	None — transactional records and search sit on the baseline.
CMS	Yes	None — object storage, CDN, edge rendering, and image transformation cover it fully.
Project management	Yes	None — the queue, broker, and realtime needs map onto baseline primitives.
E-commerce	Yes, small catalog	A dedicated search engine (typo-tolerant, faceted product search) once the catalog grows past trivial. Payment processing is always an external processor, never platform infrastructure.
Marketing automation	Yes, early scale	A durable workflow engine for real journeys (multi-day waits, branching, guaranteed retries); a columnar analytics store only at very high event volume. Email/SMS deliverability is always an external provider, never platform infrastructure.
AI-driven marketing	Yes, early scale	A dedicated vector store past roughly ten million vectors, and self-hosted model hosting only past a high, steady token volume; below those, the baseline’s vector search and hosted model gateway suffice.
ERP	Yes, small-to-mid transactional	The clearest case for a tier: an analytical / columnar database once reporting and financial consolidation outgrow the transactional core (row-oriented Postgres provably degrades there).

Two consequences make the model precise:

• External integrations are not infrastructure. Email/SMS providers and payment processors are third-party accounts a customer connects; they never appear as platform infrastructure or platform cost, so they are never part of the tier. The tier charges only for infrastructure the platform itself hosts.
• The tier is banded, not metered. Where a shape’s need is scale-triggered — an ERP’s analytics tier, a vector store, dedicated model hosting — the infrastructure tier is sold in capacity bands chosen at provisioning and upgradeable: a known figure, not a per-unit meter that would pass through or expose raw hosting cost.

The result is that CRM, CMS, and project management are included shapes; e-commerce and marketing add only a light tier at real scale; and ERP is the one shape that most clearly warrants a vertical infrastructure tier, because its analytical needs are the single place the baseline provably gives out.

Package trust and security

A package installs into an org and runs there. One that claims the shell, or requests broad permissions, can therefore see and act on everything the signed-in user can — so installation cannot be blind trust. Stating the threat plainly is what defines the checks:

What makes an untrusted package dangerous — and what does not. On the server, a package is already bounded: every data read passes through the access engine under the signed-in user’s session, so a package can never retrieve a record the user themselves could not. That plane is not the exposure. The real risk is the client runtime a package shares. If package code runs in the same browser context as everything else, it can read what is on screen, intercept keystrokes and inputs (capturing credentials or data typed into other surfaces), act autonomously with the live session token, and present deceptive or phishing UI — none of which requires elevated server permission, because it is ambient access to the page itself. A shell claim is the highest-risk case not because drawing a frame is inherently powerful, but because the shell is present on every page, legitimately needs broad scope (global search, navigation, notifications), and hosts the inner content it could otherwise observe or tamper with. A small component with a narrow declared scope is low-risk even when it renders inside the shell.

The checks that make installation safe form layers, no single one sufficient alone:

1. Declared permissions, least privilege. A package declares the capabilities and data scopes it requires; install surfaces them for explicit consent, in the spirit of app-install permissions. The kernel grants only what was declared, and the access engine enforces that grant at runtime regardless of what the package code attempts.
2. Confinement. Package code runs without ambient authority — it can touch only what its grants allow, and network egress is governed rather than open. It cannot reach around its declared scope.
3. Provenance and signing. Packages are signed by a verified publisher and installs verify the signature, so a tampered or impersonated package is rejected before it runs.
4. A review tier by risk. First-party and trusted publishers, reviewed packages, and unreviewed packages are distinguished. High-risk requests — the shell capability, broad data access — are gated behind the strictest tier, combining automated analysis with human review; low-risk packages pass more freely.
5. Runtime backstop and revocability. Because the access engine already checks every read and write, a package cannot exceed its granted scope even if it tries; installs are revocable and uninstallable; anomalous behavior can suspend a package.

The backstop is the load-bearing point: the trust checks decide what an org grants a package, and the access engine guarantees the package cannot exceed it no matter what its code does. Trust review narrows the grant; the engine enforces the grant.

The residual after isolation is exfiltration, and governed egress is its answer. Strong client isolation removes the whole scrape-the-page, capture-keystrokes, read-sibling-surfaces class. What remains is narrow: a package still legitimately receives the data its own surface needs — a global-search surface, for instance, consumes server results to render them — and a malicious one could ship that data to its own servers. The control is an outbound allow-list: a confined package may make network calls only to the platform’s first-party API and to destinations it declared and the org approved at install, never an arbitrary address. The distinction that matters is the destination — the platform calling its own API is first-party and expected; a package sending data to a non-platform address is exactly what the allow-list refuses. Capability granularity shrinks this further: if avatar, navigation, and global search are separate grants rather than one bundled component, only the search grant ever receives searchable data, so only it carries the egress-controlled concern. The review tier remains for the highest-trust unknown-publisher cases, where covert channels within an allow-list are still conceivable and publisher trust — not egress alone — is the backstop.

This is specified in full when the marketplace is built; it is placed in the architecture now because the first third-party shell makes it mandatory.

Metadata of metadata — the read-only describe layer

Like Salesforce, CAOS exposes read-only, queryable descriptions of an org’s own metadata: every object, every field, every permission set, which are standard and which are custom, and so on. These describe rows are queryable exactly like any object, but they are not editable and do not appear in the Object Manager — they are the org describing itself. Editable metadata (the custom objects and fields you can deploy and change) is what appears in the Object Manager. The object model that formalizes this split — including how one custom field is simultaneously editable source and a read-only describe row — is specified in the Object Model document.

How the platform gets built — order of operations

Because the only way to author UI is the CLI and the APIs, the engine and its tooling necessarily come first:

1. Kernel — the engine, its APIs, the access model, local auth, and the metadata-of-metadata layer.
2. CAOS CLI — the command surface the kernel exposes for deploying and querying metadata, plus local VS Code tooling that drives it.
3. Org provisioning — what kinds of orgs exist, what a request to spin one up must capture, how features are installed per org. Foundational, architected early — not an afterthought.
4. Standard packages — Core (shell), Setup, Guidance Center, Report a Bug, AI, Sales Atlas — authored with the CLI, deployed to a development org, and playtested.

No interface is hand-built into the engine at any step.

Where the default styling lives — and why

A design system (brand tokens, component style variants, icons, wordmark) is its own metadata type — it skins every surface, not just the shell, so it is authored as separable branding metadata, deployable and overridable on its own. An org rebrands by deploying a new design system; it never reinstalls the shell to change a color.

But something has to deliver that default look so the platform isn’t unstyled out of the box, and the right owner is CAOS Core. The justification is coherence-on-install: Core claims the shell capability, and a shell is the surface where branding is most load-bearing (the header, the nav, the type). Bundling the default design system with Core means “install the shell, get a complete, styled shell” rather than a raw one an admin must then theme before it’s usable. So Core ships the default design system as part of its bundle, but ships it as its own design-system metadata, not as styling welded into the shell’s components. The result: installing Core gives you a styled platform; deploying a different design system afterward restyles everything without touching Core. Delivery and ownership are separated on purpose — Core is the convenient carrier of the default; the design system is the independently-changeable thing.

Documentation surfaces

Two separate surfaces, kept apart so neither is lost inside the other:

• Architecture (this site) — the high-level, standalone architecture of the platform: this overview, then Kernel, The API Surface, CAOS CLI, Shell, Object Model, Guidance Center, and Instances & Trust.
• Developer documentation (the platform-developer docs site) — task-oriented, reference-style documentation for people building on CAOS, in the spirit of Salesforce’s developer docs.

What is already settled

Substantial prior work carries forward as reference and as decided design, subject only to minor revision under this architecture: the security model (grants, permission sets, business roles, platform roles, sharing), the App Manager and Object Manager, branding, and login/identity. This overview does not restate them; it places them. Where a prior decision conflicts with the engine/UI separation, the separation wins and the decision is revised in its own document.