Skip to main content

​
Contract status

  • Canonical interface contract for theme inheritance and visual builder behavior
  • Canonical route contract for the Layout Manager APIs documented in the layout manager PRD

​
Source documents

​
Theme model

The platform uses shadcn/ui through @aiconnected/ui and tenant theming through CSS variables.

​
Theme inheritance

Platform defaults
  └── Agency theme
        └── Business theme

​
Required theme rules

  • No hardcoded color values in platform-owned UI
  • All colors resolve through CSS variables
  • Theme changes are previewable before publish
  • Theme inheritance is explicit and auditable
  • Module-built first-party UI must use the shared UI package

​
Layout manager scope

The Layout Manager has two operating modes:
  1. Edit existing screens
  2. Create new modules through AI-assisted generation
It is the visual authoring layer for layouts, not the owner of backend business logic.

​
Canonical route contract

The layout manager PRD defines these routes directly.

​
Session and draft APIs

MethodRoutePurpose
POST/api/layout-manager/sessionsStart an editing session from a screen or module context
GET/api/layouts/{layoutId}/draftLoad the current draft
POST/api/layouts/{layoutId}/saveSave a draft snapshot
POST/api/layouts/{layoutId}/autosavePersist autosave state

​
Lifecycle APIs

MethodRoutePurpose
POST/api/layouts/{layoutId}/previewBuild a preview artifact
POST/api/layouts/{layoutId}/testRun validation and test workflows
POST/api/layouts/{layoutId}/publishPublish the layout
POST/api/layouts/{layoutId}/rollbackRestore a prior version

​
Binding APIs

MethodRoutePurpose
GET/api/capabilities/searchFind reusable components or capabilities
POST/api/layouts/{layoutId}/bindings/connect-existingBind an existing capability
POST/api/layouts/{layoutId}/bindings/create-new/startBegin creation of a new binding
GET/api/layouts/{layoutId}/bindings/create-new/{jobId}Poll binding creation state

​
AI orchestration APIs

MethodRoutePurpose
POST/api/layout-manager/ai/jobsStart an AI builder job
GET/api/layout-manager/ai/jobs/{jobId}Fetch job status
POST/api/layout-manager/ai/jobs/{jobId}/approve-planApprove the generated plan
POST/api/layout-manager/ai/jobs/{jobId}/return-to-builderMerge AI output back into builder state

​
Registry search example

GET /api/layout-manager/component-registry/search?q=phone&category=input

​
Event stream contract

The PRD defines a session event stream named layout.session.events over SSE or WebSocket. Supported event types:
  • AUTOSAVE_SUCCESS
  • VALIDATION_UPDATED
  • AI_WORKFLOW_STATE_CHANGED
  • HISTORY_APPENDED
  • PREVIEW_READY
  • TEST_RESULT_READY
  • PUBLISH_COMPLETED
  • ROLLBACK_COMPLETED

​
AI workflow state machine

The mandatory AI workflow is: 
intent_captured -> clarifying -> reuse_check -> plan_ready -> draft_generated -> builder_returned
The PRD also states:
  • Prefer reuse over net-new generation.
  • Never auto-publish.
  • Quarantine failed AI artifacts from user drafts.

​
Build guidance

Treat the Layout Manager as a versioned authoring subsystem with strict rollback rules. It should be safe for non-technical operators precisely because draft and publish boundaries are explicit.
Last modified on April 18, 2026