Appearance
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
| Part | What it is | Where to read more |
|---|---|---|
| API | PHP, no framework. One front controller answers every /api/v1/… request and hands it to a router function. | API conventions |
| Shell | A Vue 3 single-page app with Vuetify: sign-in, the west navigation, workspace tabs, search, settings. Built once per release. | Modules: the front end |
| Modules | Features 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 apps | Tables, pages, queries and workflows made in the browser for one organization, with no code. | App Builder |
| Marketplace | A 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 Shed | A 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:
- Health checks (
/healthz,/readyz) answer first, without a session. - Bootstrap: configuration, the session cookie, security headers.
- CORS, then the request path and JSON body are read. A body that is too large gets 413.
- 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. - Host binding: an organization can bind its own hostnames; a request on one of them belongs to that organization.
- 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'sdefault_permission. - 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
| Database | Holds | Shared? |
|---|---|---|
| App | users, organizations, groups, permissions, menus, modules, App Builder definitions, settings, audit log, cron jobs | one for the install |
| Inventory | the business data: documents, deal files, queues, module tables | shared 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
| Need | Use | Notes |
|---|---|---|
| Files | TenantFileStore | per-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_schema | sealed with the organization's key, never sent back to a browser |
| Audit trail | AuditLog::record($action, $targetType, $targetId, $before, $after) | dot-named actions such as module.enable; never throws |
| Search | Manticore, through SearchIndex | every document carries its organization; search answers 503 when not configured |
Mailer::platform() | SMTP with the platform's settings | |
| Presence | built in | who is online and who is looking at a screen, per organization |