Copy page

Developer Guide

Entities and CRUD conventions

Every business entity in Primebrick follows the same CRUD contract. List and form pages are thin views over this contract: the entity metadata endpoint declares which columns, labels, tooltips and actions exist, and the table/form components render what the metadata describes.

The metadata endpoint

GET /api/v1/entities/<entity>/meta returns the entity contract:

• columns — key, label, type, visibility/sort/filter flags, tooltips
• translation_key — i18n prefix for labels, fields and the page-title template parameters
• title_key — optional i18n key that overrides the canonical page title (absent on standard CRUD entities, whose titles come from system.entities.page_title.* templates — see below)
• table — default view, sort, page size, custom row actions
• actions — the capability map: every standard operation with an enabled flag and the permissions required to run it

Standard operations

Every entity exposes the same operation vocabulary; operations that are not available for an entity are reported with enabled: false:

• list / meta / get — read
• create.single / update.single — write one record
• delete.single / restore.single / purge.single — soft delete, restore, permanent delete
• read.audit — record audit history
• export, delete.bulk, restore.bulk, duplicate.bulk — collection operations

Endpoint conventions

• GET /api/v1/entities/<entity>/list — paged, filtered, sorted list
• POST /api/v1/entities/<entity> — create ({ entity: {...} } body)
• GET|PUT|DELETE /api/v1/entities/<entity>/<uuid> — get, update, soft delete
• POST /api/v1/entities/<entity>/<uuid>/restore — restore
• DELETE /api/v1/entities/<entity>/<uuid>/purge — permanent delete

Some entities also expose module-specific endpoints (for example /api/v1/auth/users for user creation with invitations). Entity-specific manual pages link back here instead of repeating endpoint details.

API existence is declared, not inferred

A standard endpoint exists only when its permission is declared in the entity router configuration (permissions.<op> in makeEntityRouter) or in a module-specific router (for example users.router.ts with rbacHandler). There is no hidden fallback: an operation without a declared permission has no route at all, on both backend and frontend. The meta actions map the UI reads is generated from the same declaration, so a disabled operation is unavailable end-to-end — not just hidden in the interface.

Sensitive operations can additionally require step-up MFA: the requireMfaStepUp middleware is attached per-operation via hooks.actionMiddlewares (for example permanent-delete of a role mapping) or in module-specific route middleware.

Page titles

List, create and edit page titles share a single source of truth: the generic templates system.entities.page_title.{list|create|edit}, stored as normal translations and interpolated at runtime with the entity's translated names (system.entities.<translation_key>.{plural|singular}).

Kind	en-GB	it-IT
list	{entity_plural} List	Lista {entity_plural}
create	Create {entity_singular}	Crea {entity_singular}
edit	Edit {entity_singular}	Modifica {entity_singular}

Because word order differs per language, the suffix/prefix is never hardcoded in code — each language carries its own template. Frontend pages resolve the H1 through the shared helper entityPageTitle(metaOrTranslationKey, 'list' | 'create' | 'edit', $t), and generated manual pages use the same keys, so documentation titles always match the UI. meta.title_key, when present, wins over the templates — it is reserved for custom pages that need a bespoke title; standard CRUD entity metas do not declare it. On record pages the record's display name goes in the breadcrumb last segment; the H1 stays the standard Edit {entity_singular}.