core/docs/ICD/surfaces.md

Surfaces

Dynamic surface lifecycle. Core surfaces are registered at startup. Extension surfaces are uploaded by admins and served from the surface_registry table.

User Endpoints

List Enabled Surfaces

GET /surfaces

Returns surfaces the user can access (enabled in registry).

{
  "surfaces": [
    { "id": "chat", "title": "Chat", "source": "core", "enabled": true },
    { "id": "editor", "title": "Editor", "source": "core", "enabled": true },
    { "id": "hello-dashboard", "title": "Hello Dashboard", "source": "extension", "enabled": true }
  ]
}

Auth: Authenticated.

Admin Endpoints

List All Surfaces

GET /admin/surfaces

Returns all surfaces including disabled ones.

Auth: Platform admin.

Get Surface

GET /admin/surfaces/:id

Returns full surface details including manifest.

Install Surface

POST /admin/surfaces/install
Content-Type: multipart/form-data

Field: archive — a .surface archive (tar.gz containing manifest.json

• static assets). The manifest declares id, title, route, required data loaders, scripts, and CSS.

Auth: Platform admin.

Enable / Disable

PUT /admin/surfaces/:id/enable
PUT /admin/surfaces/:id/disable

Disabled surfaces redirect to / and hide from navigation.

Auth: Platform admin.

Delete Surface

DELETE /admin/surfaces/:id

Removes the surface and its static assets. Core surfaces cannot be deleted.

Auth: Platform admin.

Surface Registry Object

{
  "id": "hello-dashboard",
  "title": "Hello Dashboard",
  "manifest": { "route": "/s/hello-dashboard", "scripts": [...], "css": [...] },
  "enabled": true,
  "source": "core|extension",
  "installed_at": "...",
  "updated_at": "..."
}

Page Routes

Extension surfaces are served at /s/:slug via RenderExtensionSurface(). The page engine does a runtime DB lookup — no server restart needed after install.

Static assets are served from /surfaces/:id/ (nginx location block in both unified and split deployment).

Surface Archive Format

A .surface file is a tar.gz containing:

manifest.json     — required
script.js         — optional
style.css         — optional
assets/           — optional (icons, images, etc.)

See EXTENSION-SURFACES.md for the full authoring guide including manifest schema, platform API, and CSS custom properties.