Admin UI

A schema-driven admin interface that reads schema-registry.json generated by the Quickback compiler. Every table, column, action, view, and security rule is rendered automatically. Zero UI code per table.

Overview

The CMS generates its entire UI from your Quickback definitions. Define a table with columns, guards, masking, views, and actions in your feature files. Run the compiler. The CMS reads the resulting schema registry and renders a complete admin interface — data tables, inline editing, action dialogs, role-based access, and field masking — all without writing a single line of UI code.

Key Features

• Schema-driven — Zero UI code per table. Add a table, recompile, and it appears in the CMS.
• Dashboard — Stats grid and feature cards showing tables, columns, actions, views, and masked fields at a glance.
• Custom pages — Split-panel layouts with drag-and-drop, matching engine, and page-level actions for workflows like reconciliation.
• Embedded in your Worker — Set cms: true in config. The CMS is served as static assets from the same Cloudflare Worker as your API — same origin, no CORS, auth cookies work naturally.
• Dual view modes — Table browse mode for navigation and Data Table mode for spreadsheet-style editing.
• Role-based access — Owner, admin, and member roles with live switching. CRUD buttons hidden when unauthorized.
• Multi-tenant & fixed-org — Org-scoped access by default, with pinned-organization mode for simpler deployments.
• Inline spreadsheet editing — Excel/Google Sheets-like editing with keyboard navigation (arrows, Tab, Enter, Escape).
• FK typeahead — Server-side search for foreign key fields with debounced queries and keyboard navigation.
• Field masking — Email, phone, SSN, and redaction patterns applied per role. Masked fields show a lock icon.
• Custom actions — Action dialogs with auto-generated input forms, access filtering, CMS metadata (icons, categories, confirmations), and side effects warnings.
• Views — Named column-level projections per role, with an explicit default projection for CMS table entry.
• Auto-form generation — Create and edit forms built from guards (createable/updatable fields). Inputs follow the column's constraints — q.enum renders a select, q.url a URL input, q.text({ maxLength }) a length-capped field — required columns are marked and constraints shown as helper text, untouched optional fields are omitted from the request (cleared ones are sent as null), and a VALIDATION_ERROR from the API is shown inline under the offending fields.
• Human-readable relationships — FK labels and selectors use the target table's displayColumn and an authored schema reference.

CMS Readiness Review

Enabling the CMS makes the definitions visible; it does not invent a safe UI workflow. Before compiling a CMS-backed project, review every visible table against this checklist:

1. Collection entry — A table with no named views can use its ordinary collection projection. Once read.views contains a named view, there is no implicit full-row fallback. Set read.defaultView to an accessible named view when the CMS must open the table directly. Without it, bare GET /api/v1/<table> correctly returns 400 VIEW_REQUIRED; callers must use GET /api/v1/<table>/views/<name>. The registry marks that intentional state with requiresExplicitView: true, so the CMS shows Choose a view and makes no data request until one is selected. It never silently chooses the first accessible projection. defaultSort only chooses ordering and cannot satisfy view selection or fix VIEW_REQUIRED.
2. Labels — Set displayColumn on tables used as FK targets or record titles. Auto-detection is a convenience, but an explicit value makes the intended human label stable.
3. Relationships — For feature-table foreign keys, declare the relationship in the schema with .references(() => target.id). The CMS needs the emitted fkTarget for selector/typeahead controls. Treat a matching *Id sibling table name as a compiler diagnostic suggestion, not as proof of a relationship. Better Auth ids are the exception: they live in AUTH_DB and remain plain text, not cross-database FKs. When a target has named views, its role-accessible read.defaultView must include its primary key and displayColumn; the CMS lookup uses that named route only. Add the label to the view's effective query.searchable for typeahead, or it becomes a first-50 chooser with no search request.
4. CRUD controls — New requires generated create CRUD, admitted create.access, and all required non-default inputs in guards.createable. Edit controls require generated update CRUD, admitted update.access, and fields in guards.updatable. A protected workflow field belongs in neither generic write list. Give it a schema default for creation; only its named transitions/actions may write it.
5. Business actions — A record-bound action needs an existing row. A workflow that creates the first row should be a standalone action with path: and explicit table-toolbar placement, such as cms: { placement: "tables", tables: ["reservations"] }. Check action roles and record conditions, and use cms.hidden only when the action is intentionally API-only. Action input names are humanized (sessionId becomes Session). The CMS resolves a matching fkTarget through the parent-table column metadata, then reads the FK target through its safe collection or named-default-view route. It renders search only when that route supports it. Without an explicit schema relationship, the action dialog falls back to plain text.

Read Schema Registry, Table Views, and Actions before authoring or reviewing a CMS-backed schema.

Architecture

The CMS sits at the end of the Quickback compilation pipeline:

Quickback Definitions (feature files)
        |
        v
    Compiler
        |
        v
  schema-registry.json
        |
        v
    CMS reads it
        |
        v
  Renders admin UI

Your feature definitions are the single source of truth. The compiler extracts all metadata — columns, types, guards, masking rules, views, actions, validation, and firewall config — into a static JSON file. The CMS consumes that file and renders the appropriate UI for each table.

How Embedded Serving Works

When cms: true is set, the compiler builds the CMS SPA from source at compile time (with your project-specific env vars baked in) and outputs the assets to src/apps/cms/. It also configures wrangler.toml:

[assets]
binding = "ASSETS"
directory = "src/apps"
not_found_handling = "none"
run_worker_first = true

All requests go through the Worker first. The Worker handles SPA routing — serving CMS at /cms/ on the unified domain and at root (/) on a custom CMS domain. API paths (/api/*, /auth/*, etc.) are handled by Hono as normal.

See Multi-Domain Architecture for details on hostname-based routing.

Quick Start

1. Enable CMS in config

export default defineConfig({
  name: "my-app",
  cms: true,
  // ...providers
});

2. Compile

quickback build

The compiler generates schema-registry.json and copies CMS static assets to src/apps/. It also adds an [assets] section to wrangler.toml so Cloudflare serves the CMS SPA automatically.

3. Run

npm run dev

Open your Worker URL in a browser — the CMS is served at the root. API routes (/api/*, /auth/*, etc.) pass through to your Hono app as normal. Everything runs on the same origin — no CORS configuration needed, auth cookies work naturally.

Optional: Custom CMS domain

cms: { domain: "cms.example.com" }

This adds a custom domain route to wrangler.toml. Both domains serve the same Worker — api.example.com for the API, cms.example.com for the CMS. The compiler also auto-infers a unified quickback.example.com domain where everything is available. See Multi-Domain Architecture.

Access gate

cms.access answers one question: can anyone in the organization hierarchy use the CMS, or only a platform sysadmin?

cms: { access: "member" }   // let organization members in

Start apps ship that setting. A sysadmin who also holds an organization membership uses the seat (owner / admin / member) rather than the cross-tenant picker — the picker is only for a sysadmin who belongs to nothing.

Where the gate actually lives

The CMS shell is served to any signed-in caller. Authorization is decided in the SPA, which renders a screen naming the caller's state and what to do about it — a signed-in user who can't get in is told why, instead of being silently bounced.

That is a deliberate trade: the old gate answered a wrong-role caller with a 302 so it couldn't be used to probe roles. The shell is a generic prebuilt bundle with no project data in it, and being unable to distinguish a permissions problem from a broken deploy cost more than the deniability was worth.

The gates that carry real data:

1. /api/v1/schema — the metadata endpoint. Admits sysadmin, plus any caller with a membership when access: "member". Otherwise 403 with CMS_ACCESS_DENIED and a hint naming the requirement. Without the registry there is no CMS.
2. custom_view routes — saved views follow whoever is admitted: the sysadmin tier in "sysadmin" mode, org membership or sysadmin in "member" mode.
3. Account UI link — the profile CMS action is hidden for callers who wouldn't get in. For admitted members it activates the selected organization before opening the CMS.

Your resource API endpoints (/api/v1/<resource>) are not affected — they continue to use the per-resource read, create, update, delete, and upsert access rules you defined.

What a blocked caller actually sees

The shell is served to any signed-in caller, and the SPA resolves one of six states — each its own screen naming what is true and what to do next. Nothing redirects: a signed-in user bounced elsewhere cannot tell a permissions problem from a broken deploy.

The decision is a pure function (resolveCmsAccess), so the table above is tested rather than described.

For a zero-membership sysadmin in explicit cross-tenant mode, scope lives in the browser and rides every request as ?organizationId= because Better Auth has no membership row to make active. Change it from the sidebar. A sysadmin who also holds memberships follows the ordinary membership flow instead; selecting a membership clears any older cross-tenant override. The sidebar shows the sole organization as static text and becomes a dropdown only when the user belongs to multiple organizations.

access: "sysadmin" without cms.sysadmin

A sysadmin can still pin a single tenant — ?organizationId= cross-tenant addressing is admitted for sysadmins unconditionally. The "All organizations" unfiltered view is what needs the firewall escape that cms.sysadmin: true emits.

Optional: Skip SPA rebuild

After the first compile, you can skip rebuilding the CMS SPA on subsequent compiles:

cms: { build: false }

This is useful when you're iterating on API features and don't need to rebuild the CMS UI each time — it saves significant compile time. Set build: true (or omit it) when you need to update the CMS assets.

Optional: Custom output directory

cms: { outputDir: "my-custom-path/cms" }

This changes where the compiled CMS assets are placed (relative to project root), instead of the default src/apps/cms/.

Next Steps

• Schema Registry — Understand the JSON format the compiler generates
• Connecting — Demo mode, live mode, CLI command, and auth modes
• Dashboard — Stats grid and feature navigation
• Table Views — Browse and Data Table view modes
• Custom Pages — Split-panel layouts, matching engine, and drag-drop
• Inline Editing — Spreadsheet-style editing and FK typeahead
• Security — How the CMS enforces all four security layers
• Actions — Custom actions with input forms, access filtering, and CMS metadata
• Schema Format Reference — Full TypeScript types for schema-registry.json
• Components Reference — All CMS components and their props