Core Concepts

Runtime Model

The runtime is generated from the published DomainConfig. It exposes the business app to users, agents, external systems, and custom pages.

Request pipeline

Runtime calls follow the same general path:

  1. Resolve tenant, app, environment, and published config.
  2. Authenticate the caller and resolve the actor.
  3. Authorize the requested command, projection, or tool.
  4. Validate request input against generated schemas.
  5. Execute the command, projection, webhook, subscription, or MCP tool.
  6. Return a structured response or error.

That pipeline is why the published model, auth rules, and generated contracts must stay in sync.

Runtime surfaces

SurfaceUse it for
RESTStable system integration, OpenAPI generation, command execution, projection reads, event import, projection rebuild.
GraphQLUI-friendly command mutations and projection queries.
Runtime MCPAgent tools generated from published commands and projections.
WebhooksInbound external events mapped into commands.
SubscriptionsOutbound event delivery by polling or SSE.
Custom pagesApp-specific UI built on generated runtime behavior.

Generated OpenAPI

Every published app exposes its generated REST contract at:

/api/rest/<tenant-id>/<app-id>/openapi

Use that contract as the canonical reference for command and projection endpoint names. Do not hard-code endpoints from examples without checking the generated contract for the current app.

Projection rebuilds and event import

Projection rebuild and event import are operational tools. Use them deliberately:

  • rebuild projections after projection definition changes or recovery tasks
  • import events only through controlled migration or repair workflows
  • verify projection output after either operation

For normal user workflows, execute commands instead of importing events directly.