Skip to content
ExplanationForDeveloper⏱ About 6 min

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 ​

KindContainsShips how
builderpages, queries, workflows and tables as JSON, plus images; no codea zip, uploaded or registered; may be unsigned
sourcea PHP API router, a UI bundle (Vue), migrations, hooks, settingsin BMA's repository, signed by BMA
coreBMA itselfwith 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 403 module_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.

  1. Tutorial: your first module: a sandbox, a scaffold, register, install, enable.
  2. module.json reference: every field of the manifest.
  3. The back end: the router, permissions and menus, data scoped to the organization, migrations, hooks and cron tasks, settings and secrets, marketplace keys.
  4. The front end: the UI bundle and what the host gives it.
  5. Host calls: workspace tabs, menu badges, keyboard shortcuts.
  6. Sign, test, release and upgrade: signing, tests, new versions, overrides and variants.
  7. Worked example: SAWScore: all of the above in one real module.

Background: How BMA is built and API conventions.