Back-office Operations & RBAC

Section 1

What it is

Ummah runs one staff console — ummah-platform-backoffice, a Next.js app over the backend's api/admin/* surface — and one permission system that serves both that console and the merchant portal. There is no separate admin auth stack: the same NestJS auth module mints every JWT, and a single Role table split by scope decides whether a token is staff or merchant.

The mechanism is deliberately simple: roles are rows, permissions are strings, and everything is resolved once, at token time. When a user signs in (POST api/auth/login, with TOTP MFA where enrolled), the backend loads their UserRole links, expands each role — system roles expand to the full registry for their scope, custom roles to their stored list — flattens the result, and stamps it into the JWT. Guards never touch the database again: RolesGuard compares the token's scope and permission set against each handler's @RequireScope(...) and @RequirePermissions(...) metadata.

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13.5px","primaryColor":"#FFFFFF","primaryTextColor":"#00273A","primaryBorderColor":"#D2D8DE","lineColor":"#8195A1","secondaryColor":"#F1F4F8","tertiaryColor":"#F7F8FA","clusterBkg":"#F7F8FA","clusterBorder":"#E5E8EC","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","nodeSpacing":36,"rankSpacing":48,"padding":10}}}%%
flowchart TD
  U["Sign-in
POST api/auth/login + TOTP"]:::client
  R["Load UserRole → Role rows"]:::plain
  S{"Role.isSystem?"}:::plain
  ALLP["allPermissions for the scope
from the permission registry"]:::ummah
  EXP["Role.permissions as stored
custom fine-grained names"]:::plain
  FLAT["flattenRolePermissions
+ TEMPORARY bridge fine → coarse"]:::warn
  TOK["JWT minted
scope STAFF or MERCHANT + permissions"]:::ummah
  G["JwtAuthGuard → RolesGuard
@RequireScope + @RequirePermissions"]:::ummah
  OKN["Handler runs"]:::sub
  NO["403 Forbidden"]:::danger
  U --> R --> S
  S -->|"system role"| ALLP --> FLAT
  S -->|"custom role"| EXP --> FLAT
  FLAT --> TOK --> G
  G -->|"scope matches and ALL listed permissions held"| OKN
  G -->|"any check fails"| NO
  classDef ummah fill:#FBE5D6,stroke:#E86C2B,stroke-width:1.5px,color:#00273A;
  classDef liable fill:#E86C2B,stroke:#B84E1F,stroke-width:1.5px,color:#FFFFFF;
  classDef adyen fill:#00273A,stroke:#00273A,color:#FFFFFF;
  classDef client fill:#E8F0FE,stroke:#1A73B8,stroke-width:1.5px,color:#00273A;
  classDef sub fill:#E6F4EA,stroke:#1E8E3E,stroke-width:1.5px,color:#00273A;
  classDef warn fill:#FEF3DC,stroke:#B26A00,stroke-width:1.5px,color:#00273A;
  classDef danger fill:#FCE8E6,stroke:#C5221F,stroke-width:1.5px,color:#00273A;
  classDef plain fill:#FFFFFF,stroke:#D2D8DE,stroke-width:1.5px,color:#00273A;

ummah-platform-backend/prisma/schema.prisma:227-273 · ummah-platform-backend/prisma/seed.ts:29-59 · ummah-platform-backend/src/modules/auth/permissions.registry.ts:37-179 · ummah-platform-backend/src/modules/auth/roles.guard.ts:11-50 · ummah-platform-backend/src/modules/auth/auth.service.ts:72-158

Section 2

The vocabulary

Section 3

Permission resolution, step by step

Everything the guards will ever know about a user is decided in auth.service.ts when the token is minted. Three rules govern it.

• Scope is derived, not stored on the user. If any of the user's roles has scope: STAFF, the JWT scope is STAFF; otherwise it is MERCHANT. A user holding a mix of staff and merchant roles therefore becomes a staff token — and @CurrentMerchant() will then 403 them off merchant-bound routes, so mixed assignments are effectively staff assignments.
• System roles are registry mirrors. StaffAdmin and MerchantOwner resolve to allPermissions(scope) at token time. That is why the seed stores them empty: adding a menu to the registry instantly widens every system-role holder without a migration.
• Custom roles are literal. A merchant- or staff-built role contributes exactly its stored permissions[] strings, then flattenRolePermissions merges all roles and applies the legacy bridge before the set is stamped into the token.

The TEMPORARY legacy bridge — and where it leaks

The registry speaks fine-grained names (sub-merchants.create, merchants.view), but most controllers still guard on an older coarse pair: merchant.read / merchant.write. The bridge in permissions.registry.ts:120-161 translates fine to coarse at token time. It is explicitly marked temporary, and it is incomplete in both directions:

Concretely: a marketplace Client builds a custom "Partnerships" role and ticks sub-merchants.create and sub-merchants.edit but not subscriptions.edit. Members of that role open the sub-merchants screen (bridged merchant.read via sub-merchants.view) but every POST /api/clients/:clientId/submerchants/invites and every split write returns 403, because those handlers demand merchant.write — reachable only through the subscriptions permission. The inverse failure is worse: a bookkeeping role granted subscriptions.edit for dunning tweaks can invite sub-merchants and rewrite the Client's split assignments.

ummah-platform-backend/src/modules/auth/auth.service.ts:72-158 · ummah-platform-backend/src/modules/auth/permissions.registry.ts:37-179 (bridge 120-161) · ummah-platform-backend/src/modules/auth/roles.guard.ts:11-50 · ummah-platform-backend/src/modules/submerchant/submerchant.controller.ts:144-285

Section 4

Staff & merchant teams

The same role machinery is administered from two consoles: staff manage staff, merchants manage their own teams — and neither can touch the two seeded system roles.

• Staff management lives at api/admin/staff (guarded by the staff.view/create/edit/delete permissions): create staff users, assign STAFF-scope roles, deactivate. Role CRUD itself is api/admin/roles. New staff receive set-password onboarding links; the back-office sign-in flow under app/(auth) shares the platform JWT module rather than shipping its own.
• Merchant team management lives at api/portal/team/members (invite, role-assign) and api/portal/team/roles (custom MERCHANT-scope roles), guarded by the team.* permissions. Custom roles are scoped to the merchant via Role.merchantId.
• System roles are immutable. Any attempt to edit or delete StaffAdmin or MerchantOwner returns 422 — their meaning is owned by the registry, not by any editor.
• MFA is TOTP on both sides: POST api/auth/mfa/setup issues the secret, POST api/auth/mfa/enable confirms the first code, DELETE api/auth/mfa/disable removes it. Merchant owners enrol during onboarding first login; the portal ships dedicated mfa / mfa-setup pages.

ummah-platform-backend/src/modules/staff/staff.controller.ts:36-80 · ummah-platform-backend/src/modules/roles/roles.controllers.ts:39-169 · ummah-platform-backend/src/modules/team/team.controller.ts:37-90 · ummah-platform-backend/src/modules/auth/auth.controller.ts:49-246 · ummah-platform-backoffice/app/(auth)

Section 5

The console map

The back-office nav is a faithful map of the ops feature set — every screen is a thin client over an api/admin/* module. One group name is verbatim from the sidebar ("Pricing & money", which also gates /fee-schedules behind NEXT_PUBLIC_FEATURE_PRICING); the rest are grouped here by function.

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13.5px","primaryColor":"#FFFFFF","primaryTextColor":"#00273A","primaryBorderColor":"#D2D8DE","lineColor":"#8195A1","secondaryColor":"#F1F4F8","tertiaryColor":"#F7F8FA","clusterBkg":"#F7F8FA","clusterBorder":"#E5E8EC","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","nodeSpacing":36,"rankSpacing":48,"padding":10}}}%%
flowchart LR
  BO["Back-office console
STAFF JWT · api/admin/*"]:::ummah
  ENT["Entities
dashboard · merchants/:id · sub-merchants
onboarding-queue · kyc-queue · customers"]:::plain
  PAY["Payment ops
transactions/:id · refunds · disputes/:id
subscriptions/:id · payouts · payout-approval · transfers"]:::plain
  MON["Pricing & money
split-profiles · fee-profiles · calculator
platform-earnings · fx · fee-schedules behind flag"]:::liable
  VIS["Integrity & visibility
reconciliation · reports · events
audit · notifications"]:::plain
  PLAT["Platform
staff · settings: defaults · rate-limits
sumsub-levels · profile"]:::plain
  BO --> ENT
  BO --> PAY
  BO --> MON
  BO --> VIS
  BO --> PLAT
  classDef ummah fill:#FBE5D6,stroke:#E86C2B,stroke-width:1.5px,color:#00273A;
  classDef liable fill:#E86C2B,stroke:#B84E1F,stroke-width:1.5px,color:#FFFFFF;
  classDef adyen fill:#00273A,stroke:#00273A,color:#FFFFFF;
  classDef client fill:#E8F0FE,stroke:#1A73B8,stroke-width:1.5px,color:#00273A;
  classDef sub fill:#E6F4EA,stroke:#1E8E3E,stroke-width:1.5px,color:#00273A;
  classDef warn fill:#FEF3DC,stroke:#B26A00,stroke-width:1.5px,color:#00273A;
  classDef danger fill:#FCE8E6,stroke:#C5221F,stroke-width:1.5px,color:#00273A;
  classDef plain fill:#FFFFFF,stroke:#D2D8DE,stroke-width:1.5px,color:#00273A;

Most payment-ops screens are admin twins of merchant surfaces — admin-payments, admin-refunds, admin-subscriptions, admin-captures, admin-balances, admin-customers — giving staff the cross-merchant view of the same data each merchant sees for itself. Where flows are documented elsewhere in this series, this page does not repeat them: transactions on Checkout & Payments, disputes on Disputes & Recovery, and the whole pricing console family — split-profiles, fee-profiles (with its fee-charges deduction ledger and per-row Retry), calculator — on Pricings, Splits & Fees.

merchants/:id — the lifecycle cockpit

The merchant detail screen is where staff operate a single merchant end to end. Every control is a small, explicit endpoint on admin-merchants.controller.ts:

Onboarding & KYC queues

Two queue screens keep stuck merchants visible: onboarding-queue reads GET api/admin/merchants/onboarding-queue (everyone between invite and ACTIVE, with their current state-machine status), and kyc-queue reads the review queue at api/admin/onboarding/review-queue (merchants awaiting or failing Sumsub review, where the simulate and resend tools earn their keep). The state machine itself — INVITED → OPENED → VERIFIED → IN_PROGRESS → SUMSUB_REVIEWED → ADYEN_PROVISIONING → ACTIVE — is documented on Onboarding & KYC.

ummah-platform-backoffice/app/(app)/ · ummah-platform-backoffice/components/nav/Sidebar.tsx:75-92 · ummah-platform-backend/src/modules/admin/admin-merchants.controller.ts:34-237 · ummah-platform-backend/src/modules/api-keys/api-key.guard.ts:39-84

Section 6

Approval consoles

Two money movements pause for a human: payouts and refunds. Both follow the same shape — a request lands in a queue with a configurable auto-approval cap, ops approve or reject, a worker executes. The caps live in two places: platform defaults (Settings → Defaults) and, for sub-merchants, per-sub caps set by the parent Client (0 or blank = everything needs approval).

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13px","primaryColor":"#FBE5D6","primaryTextColor":"#00273A","primaryBorderColor":"#E86C2B","lineColor":"#8195A1","actorBkg":"#FFFFFF","actorBorder":"#D2D8DE","actorTextColor":"#00273A","actorLineColor":"#D2D8DE","signalColor":"#33505F","signalTextColor":"#33505F","activationBkgColor":"#FBE5D6","activationBorderColor":"#E86C2B","noteBkgColor":"#FEF3DC","noteBorderColor":"#E8D5A8","noteTextColor":"#00273A","labelBoxBkgColor":"#F1F4F8","labelBoxBorderColor":"#D2D8DE","loopTextColor":"#33505F"},"sequence":{"mirrorActors":false,"actorMargin":46,"messageMargin":30,"boxMargin":8}}}%%
sequenceDiagram
  participant M as Merchant portal
  participant B as Backend
  participant O as Ops console
  participant W as Payout worker
  participant A as Adyen
  M->>B: POST api/portal/payouts
  B-->>O: queue row + payout.requested email
  Note over B,O: requests within the auto-approval cap skip straight to execution
  alt approved
    O->>B: POST api/admin/payouts/:id/approve
    B->>W: enqueue payout job
    W->>W: Redis lock payout:ba:{id}:lock NX EX 60
    W->>A: bank transfer sized from live balance
    A-->>B: balancePlatform.transfer.created / updated
    B-->>M: payout.sent / payout.settled webhook + email
  else rejected
    O->>B: POST api/admin/payouts/:id/reject
    B-->>M: request rejected
  end

Section 7

Money oversight

Three screens watch the platform's own money and the integrity of everyone else's.

Platform earnings — the liable-account view

platform-earnings reads GET api/admin/platform-earnings (add ?refresh=1 or use the "Refresh from Adyen" button to bypass cache): per-currency balance cards for Ummah's liable balance account plus its movement list, filterable by category — platformPayment ("Commission legs", the split commission booked at authorisation), internal (fee-charge transfers), and bank. Direction and status filters are applied server-side per page because Adyen accepts but ignores both query parameters (verified 2026-08-11). The screen is strictly read-only — no pricing inputs live here.

Transfers

The transfers screen is the raw movement ledger — the platform-wide view over Adyen transfer activity recorded from balancePlatform.transfer.created/updated webhooks (AdyenTransferLeg rows), sitting alongside the payout screens for tracing where a specific leg went.

Reconciliation panel

The reconciliation screen reads GET api/admin/reconciliation/summary, /mismatches, /awaiting, /runs and /runs/latest, and can trigger a manual sweep with POST api/admin/reconciliation/run — the same queue as the nightly 02:00 UTC cron ('0 2 * * *'). Each run checks four invariants: splits mismatched (Adyen booked ≠ recorded), split legs stale beyond 24 h, payments stuck 3 days, recoveries stuck 24 h — and records a ReconciliationRun with ReconStatus; an Adyen outage yields DEGRADED plus the reconciliation.alert ops email. The checks themselves are documented on Reconciliation & Integrity.

ummah-platform-backend/src/modules/balances/admin-platform-earnings.controller.ts · ummah-platform-backoffice/app/(app)/platform-earnings/page.tsx:14-45 · ummah-platform-backend/src/modules/reconciliation/reconciliation.controller.ts:21-58 · ummah-platform-worker/src/workers/reconciliation.processor.ts:1-16

Section 8

Visibility surfaces

Four screens answer "what happened?" at different altitudes: reports aggregate, events show the wire, audit shows the humans, notifications show the emails.

ummah-platform-backend/src/modules/reports/report-registry.ts · ummah-platform-backend/src/modules/reports/reports.controllers.ts · ummah-platform-backend/src/modules/events/events.controller.ts:24-160 · ummah-platform-backend/src/modules/audit-log/audit-log.controller.ts · ummah-platform-backend/src/core/notifications/admin-notifications.controller.ts · ummah-platform-backend/prisma/schema.prisma:816, 847, 2168

Section 9

Platform settings

Settings is four screens over two backend modules — and it holds the platform's biggest lever: a key/value store that can switch off API endpoints without a deploy.

• Defaults (settings/defaults) is a mostly read-only view of platform configuration: pricingModel, refund and payout auto-approval caps, the MIT cap, webhook timeouts, rate limits and feature-flag pills. Exactly one field is editable in place: paymentLinkExpiryDays (1–365).
• Rate limits (settings/rate-limits) configures the platform rate limiter via api/admin/rate-limits, backed by the guard in common/guards — the throttle-side companion to the kill-switch below.
• Sumsub levels (settings/sumsub-levels) manages which Sumsub verification levels invites may use — the same catalogue the invite dialogs validate against.
• PlatformSetting KV (api/admin/settings) is the generic store behind it all. Its sharpest key is api.disabled_endpoints: any /v1 endpoint can be switched off without a deploy, and ApiExposureGuard honours the change live within 30 seconds. GET api/admin/system/info rounds out the ops picture with platform build/runtime info.

ummah-platform-backend/src/modules/settings/admin-settings.controller.ts:28-35 · ummah-platform-backend/src/modules/settings/admin-rate-limits.controller.ts · ummah-platform-backoffice/app/(app)/settings/defaults/page.tsx:19-86 · ummah-platform-backend/prisma/schema.prisma:1139 (PlatformSetting) · ummah-platform-backend/src/modules/api-catalog/api-exposure.guard.ts

Section 10

Implementation notes

The endpoints this page leans on, with their guards. All api/admin/* routes sit behind JwtAuthGuard + RolesGuard with @RequireScope('STAFF'); portal routes demand MERCHANT scope. Named permissions are shown where the code declares them.

Data-model notes: the whole permission system is three tables (User, UserRole, Role) plus a code-side registry — there is no Permission table, so permission renames are code changes and the registry is the migration. Role.merchantId scopes merchant custom roles; Role.isSystem plus the 422 guard keeps the two seeded roles stable for the allPermissions expansion to lean on.

Section 11

Gaps & recommendations

What the code verifies as missing or misleading, ranked by how much it can hurt.