# 00 · Cedros Platform Primer

Read this first if you have never worked with Cedros. It explains just enough
of the platform that the rest of the guide — which is entirely about
extensions — makes sense. Nothing here requires access to Cedros source code.

## What Cedros is

Cedros is a self-hostable platform for running a complete business website:
public pages, docs, a blog, commerce, forms, newsletters, bookings, media, a
CRM, and an owner admin console, all from one server. A Cedros deployment has
three big pieces:

- **The server** (`cedros-data`, Rust) — stores all site configuration and
  content, and serves both the public site and the admin APIs.
- **The public site** — server-rendered React pages built from private host
  frontend workspaces; those workspaces are not extension dependencies.
- **The admin** — the owner console where site settings, content, pages,
  media, CRM, themes, and **extensions** are managed.

One deployment serves one site. There is no multi-tenant workspace model —
"per customer" data inside a site is something an extension models itself.

## How pages come to be

A Cedros site serves two kinds of public pages:

**1. Built-in route templates.** The platform ships templates for the standard
pages every site has: home, about, contact, legal, docs, blog, plus supporting
pages (errors, search, newsletter, checkout, and so on). Owners fill these
with content; the template decides structure.

**2. Authored pages (the page builder).** Owners compose custom pages in the
admin page builder. An authored page is stored as a small document of
**blocks**:

```jsonc
{
  "version": 1,
  "template": "default",          // which zone layout the page uses
  "zones": {
    "main": [                      // each zone holds an ordered list of blocks
      { "id": "b1", "type": "hero-banner", "props": { "title": "…" } },
      { "id": "b2", "type": "acme-shop:product-grid", "props": { "collection": "…" } }
    ]
  }
}
```

A block is one unit of page content — a hero, a text section, a product grid,
a login form. Blocks carry `props` (their content), and the runtime renders
each block type with a registered renderer. **Extensions add new block types**
(namespaced like `acme-shop:product-grid`) with their own React renderers.

Presentation is a separate system: **themes** re-skin the whole site through a
declarative manifest and never contain code. If your goal is a new look rather
than new behavior, follow **Theme Authoring** from the public `/skill.md`
entrypoint instead.

## The admin console

The admin is a React app organized as **groups → sections** in a sidebar
(Content, Users, Email, Settings, Tools, …). Owners manage pages, posts, docs,
media, forms, the CRM, analytics, site settings, themes, and extensions there.
Extensions contribute their own admin sections (leaf pages), dashboard cards
on the shared admin dashboard, and content-editor panels — all rendered inside
the shared admin shell.

The admin also hosts the **Extensions** area: upload a package ZIP, review the
permissions its manifest requests, install, enable, disable, update, and
uninstall — the whole lifecycle is operator-driven from the UI.

## Site services extensions can use

The host owns a set of site-wide services that extensions reach through
declared, operator-reviewed seams (never by shipping their own credentials):

- **Site database** — extension-owned JSONB collections in the site's
  Postgres, host-mediated.
- **Providers** — the site's configured AI (chat/structured output, image,
  voice), storage, email, and blockchain-config providers.
- **CRM** — customer profiles; extensions can assign/read namespaced customer
  tags and submit attribution events.
- **Analytics** — the shared analytics pipeline with extension-attributed
  events.
- **Site brain** — a durable operational record store that operators and AI
  agents read.
- **Notifications, Contracts, Email marketing, Scheduling, Shop** — owning
  systems extensions can seed setup content into.
- **The assistant** — Cedros AI surfaces that discover extension **skills**
  (docs) and execute extension **capabilities** (tools/actions).

## First-party product extensions

Cedros builds its own products as extensions on the same platform: **Cedros
Login** (identity for site end users), **Cedros Pay** (payments,
subscriptions, credits, entitlements), **Cedros Shop** (storefront), plus
Wallet, Compliance, Scheduling, Notifications, Contracts, and Email. Your
extension can depend on their published contracts — for example, gate a
feature on a Pay entitlement or serve signed-in Login users — through the
integration registry in
[`18-official-extension-integrations.md`](18-official-extension-integrations.md).

## Where extensions fit

Extensions add **behavior**: server APIs and jobs, admin workflows, public
blocks and pages, data models, AI tools, and integrations. An extension is one
versioned, operator-installable package; the operator reviews what it asks for
and can disable or remove it at any time without a server rebuild.

| Concern | Owner (site data & settings) | Theme | Extension |
| --- | --- | --- | --- |
| Page copy, products, posts, media | ✅ | — | seeds starters, never owns owner content |
| Which pages/routes exist | ✅ | — | ✅ (adds seeded pages + `/extensions/{id}` routes) |
| Colors, typography, chrome style | — | ✅ | consumes theme tokens |
| Block behavior, data loading, new block types | — | — | ✅ |
| Server APIs, jobs, integrations | host core | — | ✅ (sandboxed) |
| Admin sections and dashboard cards | host core | — | ✅ (adds) |
| Provider credentials (AI, email, storage) | ✅ | — | uses via declared access, never owns |
| Extension install/enable/permissions | ✅ | — | requests, never self-grants |

## Trust model in one paragraph

The operator is the trust root. An extension arrives as a ZIP; the host
validates its manifest, shows the operator every requested capability, and on
install grants exactly those. Server code runs in a WebAssembly sandbox with
no filesystem/network/env access — every effect passes through a granted,
scope-checked host import with per-call attribution and hard resource limits.
Browser code loads through a restricted module loader (no remote code, fixed
import allowlist). Nothing an extension declares executes by itself, and
nothing it ships can reach another extension's data or the host's tables.

## Glossary

| Term | Meaning |
| --- | --- |
| **Extension family** | The one installable unit: server + React + React Native packages under one `extensionId`. |
| **Manifest** | `cedros-extension.manifest.json` — the canonical declaration of identity, surfaces, and capabilities. |
| **Bootstrap** | `cedros-extension.bootstrap.json` (`{ "manifest": … }`) and the runtime objects package registrations return. |
| **Archive / ZIP** | The upload deliverable carrying manifest, bootstrap, compiled runtime, and the wasm component. |
| **Surface** | One place an extension contributes: a route, job, admin section, dashboard card, block, page seed, starter, AI skill, … |
| **Capability seam** | A declared, operator-granted, host-enforced channel to a privileged resource (database, providers, tags, …). |
| **Wasm component** | `cedros-extension.server.wasm` — the compiled Rust server backend, sandboxed by the host. |
| **Route** | An HTTP endpoint the wasm component serves under `/extensions/{extensionId}/…`. |
| **Job** | A scheduled executor the wasm component exports, dispatched by site automation. |
| **Content model** | An extension-owned JSONB collection (`{extensionId}:name`) in the site database. |
| **Block** | One unit of page content with a type and serializable props; extensions register renderers for their types. |
| **Page seed** | Manifest metadata that provisions a real, owner-editable Cedros page on enable. |
| **Starter** | A form/docs/policy template the owner can materialize (or that auto-provisions on enable). |
| **Site brain** | The durable operational record store operators and AI agents read. |
| **Owner / operator** | The person running the site through the admin (and granting extension capabilities). |
| **Host** | The cedros-data deployment an extension is installed into. |
| **Self-serve / metadata-first / host-coordinated** | The three classes of extension work — see [`01-extension-system-overview.md`](01-extension-system-overview.md). |

Next: [`01-extension-system-overview.md`](01-extension-system-overview.md).