Architecture

--- title: Architecture description: Conceptual architecture and core flows. ---

Architecture

This section describes the conceptual architecture of Ekairos as implemented today.

Core flow

1) Define the root domain using @ekairos/domain. 2) Compose subdomains using includes(). 3) Push schema to InstantDB via toInstantSchema(). 4) Configure runtime in a bootstrap module (server only). 5) Register threads and workflows. 6) Expose runtime and domain via well known endpoints. 7) Execute workflows from UI or API.

Domain-first design

Ekairos is domain first. The domain schema is the source of truth for:

• Entity types, links, and rooms.
• Action contracts (defined outside schema but attached in runtime config).
• AI context and prompt materialization via domain.context().

The narrative part of the domain is carried by DOMAIN.md. This lives at the root of every domain repo and is loaded by the runtime when available.

Runtime boundaries

There are two runtime layers:

• Domain runtime: @ekairos/domain/runtime provides the domain config and the DOMAIN.md loader.
• Thread runtime: @ekairos/thread/runtime binds threads to a concrete environment (InstantDB, workflow runner, etc).
• App configuration: @ekairos/domain/runtime owns the runtime bootstrap + domain/MCP wiring.

API surfaces

The platform exposes a well known domain API:

• GET /.well-known/ekairos/v1/domain
• Returns domain summary, schema, and context string.
• POST /.well-known/ekairos/v1/domain
• Executes an InstaQL query against the configured org database.
• Requires auth when EKAIROS_DOMAIN_* env vars are set.

The platform also exposes Workflow DevKit endpoints:

• /.well-known/workflow/v1/step
• Step execution endpoint used by workflow runtime.

Identity and access

Domain APIs can be protected with:

• Static token EKAIROS_DOMAIN_TOKEN
• OIDC validation with JWKS (default Vercel OIDC).

These controls are implemented in the generated domain route (see @ekairos/domain/next).