Modules

Modules are the unit of product behavior.

A module owns a feature area. It declares metadata, models, UI, actions, tools, agents, skills, commands, locales, and assets while relying on the SDK for platform services.

Module structure

A module keeps feature files together without owning the platform.

The folder shape is intentionally boring: domain models, UI, actions, tools, agents, skills, locales, and assets are easy to locate.

01

manifest.json

Declares module identity, title, description, version, permissions, routes, and public metadata.

02

models.py

Defines persistent module tables by extending the module base model so runtime filters and migrations can work consistently.

03

utils/ui/yaml

Contains YAML layouts. Python views load these files and provide data rather than building UI imperatively.

Runtime behavior

Actions mutate state and publish UI effects through the SDK.

A page can be static, but most product modules react to user events. Those events should stay inside the module boundary.

01

Actions

Handle user events, write module data, return effects, or publish stream updates.

02

Tools and agents

Expose capabilities to model orchestration without leaking core internals into module code.

03

Locales

Keep display strings translatable and separate from business logic.

Persistence

Module models participate in core-managed storage behavior.

The module defines the table shape. The runtime handles migrations, filters, and access context through the base model and SDK.

01

Scoped rows

User and organization filters can be applied consistently when the model declares the relevant fields.

02

Autogenerated migrations

The module provides models; the core migration workflow generates and applies the database migration.

03

Model methods

Module code should prefer public model/SDK operations over direct database access.

Example

Module folders

The example shows the contract shape without turning the page into implementation documentation.

Module foldersexcerpt

modules/example/
  manifest.json
  models.py
  actions/
  agents/
  tools/
  skills/
  ui/
  utils/ui/yaml/
  locales/
  assets/

Use these pages to move from the concept to adjacent parts of the runtime.