Appearance
Modules
A module adds a feature to BMA: API routes, screens, menu items, permissions, settings and its own data. It's registered once on a BMA install, then installed and enabled per organization.
Kinds
| Kind | Contains | Ships how |
|---|---|---|
| builder | pages, queries, workflows and tables as JSON, plus images; no code | a zip, uploaded or registered; may be unsigned |
| source | a PHP API router, a UI bundle (Vue), migrations, hooks, settings | in BMA's repository, signed by BMA |
| core | BMA itself | with every release |
A source module made for one organization only is private (owner_tenant_id, visibility: private). Others are listed (any organization admin can install it) or platform (only BMA staff can).
How it plugs in
- API. The module owns path prefixes (such as
/hello). Every request to them passes the entitlement gate: the caller must be signed in, their organization must have the module enabled (otherwise 403module_not_enabled), and they must hold the module's default permission. Then BMA calls the module's router function. Prefixes of two modules never overlap. - Screens. A module ships a JavaScript bundle. After sign-in BMA loads the bundles of the organization's enabled modules from the API and mounts their screens; there's no BMA rebuild.
- Menu and permissions. Install adds the module's permission keys and menu items; enable grants the default groups.
- Data. Tables the module creates through migrations, scoped to the organization.
- Settings. A settings form generated from a schema; secrets are sealed.
Versions and channels
Versions are immutable: any change, even a rebuilt bundle, is a new version. Each version is registered on the stable or beta channel. Organizations follow a channel, or are pinned to one version; upgrading shows a preview of migrations, permissions and menu changes first. A bad version can be withdrawn (yanked) without breaking organizations already on it.
Organizations can adjust a module without forking it: settings, then overrides (rename or hide menu items and screens, within what the module allows), then a variant (a private copy they own).
The module developer's path
Read these in order the first time; afterwards each one is a reference.
- Tutorial: your first module: a sandbox, a scaffold, register, install, enable.
- module.json reference: every field of the manifest.
- The back end: the router, permissions and menus, data scoped to the organization, migrations, hooks and cron tasks, settings and secrets, marketplace keys.
- The front end: the UI bundle and what the host gives it.
- Host calls: workspace tabs, menu badges, keyboard shortcuts.
- Sign, test, release and upgrade: signing, tests, new versions, overrides and variants.
- Worked example: SAWScore: all of the above in one real module.
Background: How BMA is built and API conventions.