Manifest and Routes

Audience: Federated app developers and Shell host team
Stored in: Control Plane Postgres (apps.manifest_json)
Validated by: app/domain/entities/shell_manifest.py when app_kind = shell_federated

The manifest is the contract between Portal, Control Plane bootstrap API, and the Shell host. Extra keys are allowed until the joint full schema is locked.

Identity: slug vs appId

Convention: keep slug and appId identical unless you have a deliberate reason not to. Bootstrap uses slug; webpack remotes use appId.

appId pattern: ^[a-zA-Z][a-zA-Z0-9._-]{0,62}$

Required fields (Phase 1)

Route object

Shell URL convention:

/apps/{slug}/{route.path}

Example: slug my-app, route path page-1 → /apps/my-app/page-1

The federated remote must export a module matching the route contract your Shell host expects (see Shell starter-kit CONTEXT.md).

Theme object

Shell applies these to CSS variables / design tokens for app chrome around the federated remote.

Set on publish

Empty before first publish. Shell uses SHELL_REMOTE_DEV_URL in dev when empty.

Optional fields (pass-through)

Draft fields (joint schema session — not validated yet)

These may appear in manifests today but are not enforced by Control Plane validation. Documented for alignment with future Coderunner/Shell unified schema:

See docs/HANDOVER-AMIN.md Ask 5 for the proposed merged shape.

Sample manifest

From Portal apps/customer/src/lib/apps/manifest.ts:

{
  "version": "1.0",
  "appId": "my-app-2",
  "name": "My App 2",
  "displayName": "My App 2",
  "description": "Starter remote; Shell federated app.",
  "icon": "Sparkles",
  "theme": {
    "primaryColor": "#2563EB",
    "accentColor": "#7C3AED",
    "mode": "light"
  },
  "collections": [],
  "routes": [
    {
      "path": "page-1",
      "title": "Page 1",
      "icon": "FileText",
      "layout": []
    }
  ],
  "remoteUrl": ""
}

Register and update (Portal / API)

Register:

POST /v1/workspaces/{workspace_id}/apps
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "My App",
  "slug": "my-app",
  "app_kind": "shell_federated",
  "manifest": { … }
}

Patch manifest:

PATCH /v1/workspaces/{workspace_id}/apps/{app_id}
Authorization: Bearer {token}
Content-Type: application/json

{ "manifest": { … } }

Validation runs on register/patch for shell_federated apps. Invalid appId or missing required fields return 422.

Publish flow (updates remoteUrl)

Publishing does not replace the whole manifest — it adds/updates remoteUrl and creates an app_releases row.

1. POST …/apps/{app_id}/releases/upload-url — presigned PUT for bundle
2. Client PUTs remoteEntry.js or .zip
3. POST …/apps/{app_id}/releases/{release_id}/finalize — extracts zip if needed, writes remoteUrl into manifest

Bootstrap returns the latest published release plus current manifest.

Module Federation mapping

const scope = config.manifest.appId;
const entry = config.manifest.remoteUrl; // full URL to remoteEntry.js

// remotes[scope] = `${base}@${entry}`  — see 02-shell-bootstrap.md

Remote package name / exposed modules must match what Shell imports (starter-kit documents the exact export names).

Validation errors (common)

Related

• 01-getting-started.md — end-to-end walkthrough
• 02-shell-bootstrap.md — consume manifest at runtime
• 12-troubleshooting.md — publish and bootstrap issues