Engineering a compliance-grade SaaS, with multi-tenancy, RBAC and audit trails

The hardest product decision came first. How many applications is this, really? A naive read says three, a back-office app for the firm, a tool for delegated staff, and a self-service app for the firm's clients. Build it that way and you get three codebases, three drifting copies of the same business rules, and an audit trail that depends on which app happened to write the row.

I built it as one modular NestJS 11 API with one PostgreSQL schema behind Prisma 7, fronted by a single React 19 SPA that renders three role-scoped experiences. The portals differ in what they expose, never in the logic underneath. A client uploading a document and an assistant approving it hit the same service, the same validation and the same audit hook. They just see different surfaces. 36+ feature modules live in that one API, and the portal you're in decides which ones light up.

Three roles sounds simple. Then the firm asks whether this one assistant can approve questionnaires but not delete clients, and whether that senior can have the audit log and nothing else extra. Coarse roles can't express that without spawning a new role for every exception, and role explosion is how RBAC systems rot. The platform settled on 92+ fine-grained permissions with a three-tier resolution model that keeps per-user flexibility without abandoning role defaults.

Permissions are named domain.action, for example documents.upload, questionnaires.approve and audit.read. Roles are bundles of those keys. On top of a role, an individual user can carry explicit overrides, either a grant that adds a permission their role lacks or a revoke that takes one away. Resolution runs in strict priority order. A per-user override wins. Absent that, the role's grants apply, with wildcard support so documents.* covers every documents. action. Absent that, a legacy fallback. The result is cached briefly per user-and-permission so the check is cheap on the hot path, and the cache is invalidated the instant permissions change.

// Generic illustration of a domain.action RBAC check.// Priority: explicit per-user override > role grant (wildcards) > deny. type Override = { key: string; granted: boolean }; function matches(required: string, owned: string[]): boolean {  for (const grant of owned) {    if (grant === required) return true;    // Wildcard: "documents.*" covers "documents.upload"    if (grant.endsWith(".*") && required.startsWith(grant.slice(0, -1))) {      return true;    }  }  return false;} function can(  required: string, // e.g. "questionnaires.approve"  rolePermissions: string[], // bundle granted by the user's role  userOverrides: Override[], // explicit per-user grants/revokes): boolean {  // 1. An explicit per-user override always wins (grant OR revoke).  const override = userOverrides.find((o) => o.key === required);  if (override) return override.granted;   // 2. Otherwise fall back to the role bundle (with wildcard support).  return matches(required, rolePermissions);}

In the running system this lives in a guard. An endpoint declares its requirement with a decorator, @RequirePermission('questionnaires.approve'), and a single PermissionGuard reads that metadata, resolves the caller's effective permissions, and either lets the request through or throws a 403 naming the missing permission. The controller method stays clean, and the authorization decision is declarative and lives next to the route it protects.

That last point bit me once. An early version invalidated the permission cache and pushed the live "refetch your permissions" event as fire-and-forget, after returning 200 to the admin who made the change. The admin saw success, but affected users kept their stale cached permissions until the TTL lapsed. The fix was to await invalidation before responding. The admin save is deliberately synchronous, so paying about 100ms to guarantee correctness is the right trade. In a regulated system, a revoke that doesn't take effect promptly is a control that didn't fire.

This is the part that justified building bespoke software at all. The compliance module implements the firm's full Belgian AML (AWW) obligations as a first-class workflow, not a folder of PDFs. It is by far the most complex area of the system. A multi-stage lifecycle per client, fed by live business-registry lookups and external screening services, all of it producing durable evidence.

Three portals looking at shared data create a coherence problem. When an assistant approves a submission, the admin's queue and the client's status should both update now, without a refresh. The platform handles this with a Socket.io gateway and an event-driven core of 80+ typed domain events that flow whenever state changes.

The model is rooms and audiences. Connections join rooms keyed by identity and scope, so there is a user room, a role room for admin or assistant, a client room, a company room and a period room. Every mutation emits a typed event addressed to the relevant audiences. The most common pattern is a tenant fan-out that notifies the admins, the assistants and the one specific client a change concerns, and nobody else. Because audiences are a small typed vocabulary rather than ad-hoc string concatenation, it's hard to accidentally broadcast a client's data into the wrong room.

On the receiving side, the SPA doesn't trust pushed payloads to mutate UI. It uses events to invalidate the right query keys, letting TanStack Query refetch authoritative data. That keeps the source of truth on the server while still feeling instant. Optimistic updates make the actor's own change appear immediately, with rollback on failure.

The same event stream powers more than UI sync. Permission changes push a 'refetch your permissions' nudge to the affected user's browser so a revoke takes hold immediately. Background jobs, meaning 20+ scheduled tasks plus on-demand queues over Redis and BullMQ, drive periodic AML rechecks, reminders and document-collection chases. That is the slow, scheduled spine of a compliance workflow, decoupled from the request cycle.

Stripped of the Belgian specifics, here is what generalizes to any vertical where the software has to defend its own decisions. Fintech, healthtech, legaltech, anything supervised.

• One API, many surfaces beats many apps. Role-scoped portals over a single type-safe contract gave me one place for every business rule and one audit trail regardless of who acted. Three separate apps would have triplicated the logic and fractured the evidence.
• Compliance is an evidence pipeline rather than a feature. The deliverable is not 'we screened the client'. It is 'here is the durable, reconstructable record that we screened, when, against what, and with what result.' Design for the auditor's question 'show me', and persist intermediate results, failures included.
• Make the audit trail append-only and non-blocking. Insert-only rows with before/after change sets, written through a durable queue so logging never blocks or silently drops. If a row can be edited from the app, it has stopped being evidence.
• Permissions are data, so resolve them in tiers. Fine-grained domain.action permissions, composed into roles, with per-user overrides as the pressure valve against role explosion. Cache the resolution, but invalidate it the instant it changes.
• Treat external compliance services as hostile infrastructure. Registry and screening APIs are slow and flaky. Wrap each in timeouts, rate limits, retries and a circuit breaker, so one bad upstream degrades a single check rather than the whole onboarding. Record the outcome either way.
• Tag every real-time event with its actor. It's the small detail that lets optimistic UI and live cross-portal broadcast coexist without echo flicker, and it doubles as provenance for the event log.
• Type-safety at the boundary pays compound interest. When one record is read by three portals and written by one service, Prisma-generated types plus Zod/class-validator at the edge turn a whole class of cross-portal shape bugs into compile errors.
• You don't need a team to ship agency-scale regulated software. This was a solo build taken to production, with three portals, a full AML module, real-time collaboration and an audit trail. What made it possible was consistency. One contract, one set of patterns, one source of truth.

The firm now runs its fiscal periods, document collection and AML obligations on a single system it owns outright, one that can answer show me the record in seconds instead of a frantic search through inboxes. Compliance-grade software is not prettier than spreadsheets. It can prove what happened.