Skip to content
ExplanationForDeveloper⏱ About 10 min

How BMA is built ​

BMA is one PHP API and one browser app (the shell) that many organizations share. Almost every feature is a module that an organization switches on. This page is the map: read it before the module, integration or sign-in pages, so the words they use mean something.

The parts ​

PartWhat it isWhere to read more
APIPHP, no framework. One front controller answers every /api/v1/… request and hands it to a router function.API conventions
ShellA Vue 3 single-page app with Vuetify: sign-in, the west navigation, workspace tabs, search, settings. Built once per release.Modules: the front end
ModulesFeatures that plug into the API, the menu and the shell. core ones ship with BMA; source ones are signed PHP and JavaScript packages; builder ones are App Builder apps packed as JSON.Modules
App Builder appsTables, pages, queries and workflows made in the browser for one organization, with no code.App Builder
MarketplaceA source module that runs storefronts inside host platforms, with its own host and vendor portals, host API and webhooks.Embed a marketplace, Host API
Tool ShedA browser extension that brings BMA tools into other web pages.Tool Shed guide

How a request is handled ​

Every API call takes the same path, in this order:

  1. Health checks (/healthz, /readyz) answer first, without a session.
  2. Bootstrap: configuration, the session cookie, security headers.
  3. CORS, then the request path and JSON body are read. A body that is too large gets 413.
  4. CSRF: a change (POST, PUT, PATCH, DELETE) must carry the session's token. A few sign-in paths, the Tenant API and a module's declared public paths are exempt. See API conventions.
  5. Host binding: an organization can bind its own hostnames; a request on one of them belongs to that organization.
  6. The entitlement gate finds the module that owns the path (the longest matching prefix). If the path is not public, 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.
  7. Routing: BMA calls the router functions that serve that path, one after another. Each one either returns (not mine) or answers and stops. Nothing answered: 404.

Each answer is the same JSON envelope, made by ApiResponse: {"success": true, "message": "", "data": …, "total": …}.

Organizations ​

An organization (in the code and the database, a tenant) is a customer of BMA: its users, groups, permissions, modules, settings and data. Every request runs as one organization, the one the user signed in to.

  • One organization is special: the platform organization (code platform). Its members are BMA staff, who run the platform and can see across organizations.
  • A user can belong to more than one organization; they pick one when they sign in.
  • Data is always scoped: a query reads and writes the rows of the current organization only. Asking for another organization's row gives 404, never 403, so ids can't be probed.

Two databases ​

DatabaseHoldsShared?
Appusers, organizations, groups, permissions, menus, modules, App Builder definitions, settings, audit log, cron jobsone for the install
Inventorythe business data: documents, deal files, queues, module tablesshared by default; an organization can have its own

On the shared inventory database each row carries a tenant_id, and every query filters on it. An organization can also get its own schema on the same server, or a dedicated database server; then the filter is still written but matches all rows. Module code doesn't need to know which: it writes the filter the same way.

BMA runs on MySQL, PostgreSQL and SQLite (the sandbox and the tests use SQLite), so SQL must work on all three.

Modules and the registry ​

The module registry keeps every registered version of every module, and per organization which version is installed and whether it is enabled. Installing runs the module's migrations for that organization, adds its permissions and menu items, and grants them; enabling switches its API, screens and menu on. Disabling hides them and keeps the data. See Modules.

Background work ​

A runner starts every minute and runs the scheduled jobs that are due: BMA's own (presence clean-up, data retention) and module tasks, which run only while the module is enabled for that organization. A module asks for a job from its lifecycle hooks. See Modules: the back end.

Services a module can use ​

NeedUseNotes
FilesTenantFileStoreper-organization folders, local disk or a cloud bucket, encrypted at rest when the organization has encryption on
Secrets in settings"x-secret": true in settings_schemasealed with the organization's key, never sent back to a browser
Audit trailAuditLog::record($action, $targetType, $targetId, $before, $after)dot-named actions such as module.enable; never throws
SearchManticore, through SearchIndexevery document carries its organization; search answers 503 when not configured
MailMailer::platform()SMTP with the platform's settings
Presencebuilt inwho is online and who is looking at a screen, per organization