RBAC and permissions

RBAC runs on three concepts: roles (bundles of permissions), scopes (which records a role applies to), and constraints (extra conditions).

Built-in roles

• TENANT_ADMIN — everything on the tenant.
• ADMIN — administrative but not destructive (can't delete tenant).
• OPS_ADMIN / OPS_USER — forwarding operations.
• ROAD_ADMIN / ROAD_USER — road module.
• WAREHOUSE_ADMIN / WAREHOUSE_USER — warehousing.
• FINANCE_ADMIN / FINANCE_USER — finance.
• COMMERCIAL_ADMIN / COMMERCIAL_USER — CRM / sales.
• PROCUREMENT_ADMIN / PROCUREMENT_USER — vendor management.
• COMPLIANCE — read-only access to all data + compliance actions.
• SUPPORT_READONLY — read-only, no exports.

Custom roles

Tenants can build custom roles picking from the permission catalog. Example: "Contract Desk" = read all quotes, create/edit rate cards, no finance access.

Permissions

Permissions are <domain>.<action> tokens:

• shipment.view, shipment.edit, shipment.create, shipment.delete.
• invoice.view, invoice.issue, invoice.dispute.
• ratecard.publish, ratecard.approve.
• user.invite, user.reset-password.

Full catalog at /app/admin/permissions.

Scopes

A role can apply to:

• Tenant-wide — all records.
• Entity — multi-entity groups.
• Warehouse / depot — ops staff bound to a location.
• Own records — records where the user is owner / creator / AE / collector.

Example: a warehouse operator has WAREHOUSE_USER scoped to WH-DXB-01 only — can't see WH-LHR-01.

Constraints

Extra conditions on top of role + scope:

• Amount ceilings — can approve only up to X USD.
• Segregation — can't approve something you created.
• Time windows — contractor-type accounts active only during business hours.

Object-level overrides

Rare cases: lock an individual record (highly confidential opportunity, legal-hold invoice) to a named list of users. Overrides the usual role + scope rules for that object only.

Role audit

Every role change + permission change + assignment change is audited. Quarterly access review (templated report) supports SOX / SOC 2.

Best practice

• Prefer specific roles over TENANT_ADMIN for everyday work.
• Use scope to limit warehouse / depot users to their location.
• Review roles quarterly — joiners / movers / leavers drift.