DEV Community: Oladejo Babatunde

Building Role-Based Access Control for Enterprise Systems: Lessons from Banking Software

Oladejo Babatunde — Tue, 07 Jul 2026 21:26:03 +0000

How I designed an authorization system that balances security, flexibility, and developer experience — without over-engineering it.

The Problem No One Talks About

Authentication gets all the blog posts. OAuth flows, JWT debates, session vs. token — the internet is full of opinions. But authorization — deciding what an authenticated user can actually do — is where enterprise systems quietly fail.

I've built RBAC systems for multiple enterprise platforms, including internal tools for a regulated banking environment. The challenge isn't implementing roles. It's designing a system that:

Scales with organizational complexity (departments, hierarchies, cross-functional access)
Remains auditable (who approved what, when, and why)
Doesn't become a bottleneck for feature delivery
Is simple enough that non-engineers can understand the permission model

Here's what I've learned.

Why Simple RBAC Breaks in Enterprise

The textbook RBAC model — User → Role → Permissions — works great for SaaS products with 3 roles (admin, member, viewer). It falls apart in enterprise because:

1. People wear multiple hats. A facilities manager might also be a budget approver. A compliance officer might need read access across all departments but write access to none.

2. Context matters. The same "manager" role means different things in different departments. An engineering manager shouldn't approve procurement requests, even though they share a title with a procurement manager.

3. Temporary access is real. An auditor needs full read access for two weeks. An intern needs restricted access that expires. A contractor needs access to exactly one module.

4. Regulatory requirements demand granularity. In banking, you can't just have "admin." You need separation of duties — the person who initiates a transaction cannot be the person who approves it.

The Model I Use

After iterating across multiple projects, I've settled on a layered model:

User
  └── has many → UserRoles (with scope + expiry)
        └── belongs to → Role
              └── has many → RolePermissions
                    └── belongs to → Permission (resource + action + scope)

The key additions beyond basic RBAC:

Scoped Roles

A role assignment isn't global — it's scoped to a context:

interface UserRole {
  userId: string;
  roleId: string;
  scope: {
    type: 'global' | 'department' | 'project' | 'resource';
    scopeId?: string; // e.g., department ID
  };
  expiresAt?: Date;
  grantedBy: string;
  grantedAt: Date;
}

This means "Manager of Department X" is a different assignment than "Manager of Department Y" — same role, different scope. The user might have both, or just one.

Granular Permissions

Permissions aren't just "can access module." They're structured as resource + action + constraint:

interface Permission {
  resource: string;    // e.g., 'work_orders', 'budgets', 'reports'
  action: string;      // e.g., 'create', 'read', 'update', 'delete', 'approve'
  constraint?: string; // e.g., 'own_department_only', 'below_threshold'
}

A real permission set for a facilities supervisor might look like:

const facilitiesSupervisor: Permission[] = [
  { resource: 'work_orders', action: 'create' },
  { resource: 'work_orders', action: 'read', constraint: 'own_department' },
  { resource: 'work_orders', action: 'approve', constraint: 'below_50k' },
  { resource: 'budgets', action: 'read', constraint: 'own_department' },
  { resource: 'reports', action: 'read' },
  { resource: 'reports', action: 'export', constraint: 'own_department' },
];

Separation of Duties

For regulated environments, certain action combinations are explicitly forbidden:

const separationRules: SeparationRule[] = [
  {
    action1: { resource: 'purchase_orders', action: 'create' },
    action2: { resource: 'purchase_orders', action: 'approve' },
    reason: 'Initiator cannot be the approver (4-eyes principle)',
  },
  {
    action1: { resource: 'payments', action: 'initiate' },
    action2: { resource: 'payments', action: 'authorize' },
    reason: 'Payment initiation and authorization must be separate actors',
  },
];

These rules are checked at role assignment time (preventing conflicting roles) AND at action time (catching edge cases).

Implementation: Middleware + Policies

The enforcement layer has two levels:

Route-Level Middleware (Coarse Check)

Before any request reaches a controller, middleware verifies the user has at least one relevant permission for the resource:

// Middleware: checks "can this user interact with this resource at all?"
function requirePermission(resource: string, action: string) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const user = req.user;
    const hasPermission = await authService.checkPermission(user.id, {
      resource,
      action,
      scope: extractScope(req), // department from route params, etc.
    });

    if (!hasPermission) {
      auditService.logDenied(user.id, resource, action);
      return res.status(403).json({
        error: 'Insufficient permissions',
        required: `${resource}:${action}`,
      });
    }

    next();
  };
}

// Usage on routes
router.post('/work-orders', requirePermission('work_orders', 'create'), createWorkOrder);
router.patch('/work-orders/:id/approve', requirePermission('work_orders', 'approve'), approveWorkOrder);

Business Logic Level (Fine-Grained Check)

Inside the service layer, constraints are evaluated against the specific resource:

async approveWorkOrder(userId: string, workOrderId: string): Promise<WorkOrder> {
  const workOrder = await this.workOrderRepo.findById(workOrderId);
  const user = await this.userService.getWithRoles(userId);

  // Constraint: can only approve below threshold
  const constraint = await this.authService.getConstraint(userId, 'work_orders', 'approve');
  if (constraint === 'below_50k' && workOrder.estimatedCost >= 50000) {
    throw new ForbiddenException('Work order exceeds your approval threshold');
  }

  // Separation of duties: creator cannot approve
  if (workOrder.createdBy === userId) {
    throw new ForbiddenException('Cannot approve your own work order');
  }

  // Proceed with approval
  workOrder.status = 'approved';
  workOrder.approvedBy = userId;
  workOrder.approvedAt = new Date();

  await this.auditService.log({
    actor: userId,
    action: 'approve',
    resource: 'work_orders',
    resourceId: workOrderId,
    metadata: { estimatedCost: workOrder.estimatedCost },
  });

  return this.workOrderRepo.save(workOrder);
}

The Audit Trail: Non-Negotiable

In regulated environments, every permission check — whether granted or denied — must be traceable. My audit log captures:

interface AuditEntry {
  id: string;
  timestamp: Date;
  actor: string;           // who performed the action
  action: string;          // what they did
  resource: string;        // what resource type
  resourceId?: string;     // which specific resource
  outcome: 'granted' | 'denied';
  reason?: string;         // why denied (if applicable)
  metadata: Record<string, any>; // additional context
  ipAddress: string;
  sessionId: string;
}

This isn't just for compliance — it's invaluable for debugging. When someone reports "I can't access X," I can trace exactly which permission check failed and why.

Performance: Caching Without Compromising Security

Permission checks happen on every request. Without caching, you're hitting the database dozens of times per page load. But stale cache means users keep access after it's revoked — a security risk in banking.

My approach:

class PermissionCache {
  private readonly TTL = 60; // 60 seconds — short enough for security

  async getPermissions(userId: string): Promise<Permission[]> {
    const cached = await this.redis.get(`permissions:${userId}`);
    if (cached) return JSON.parse(cached);

    const permissions = await this.computePermissions(userId);
    await this.redis.set(`permissions:${userId}`, JSON.stringify(permissions), 'EX', this.TTL);
    return permissions;
  }

  // Immediate invalidation on role changes
  async invalidate(userId: string): Promise<void> {
    await this.redis.del(`permissions:${userId}`);
  }
}

Key decisions:

Short TTL (60s): Permissions refresh frequently, limiting the window of stale access
Immediate invalidation on changes: When a role is assigned or revoked, cache is cleared instantly
Compute once, check many: Permissions are flattened into a single array at cache time, so individual checks are O(1) lookups

What I Got Wrong (And Fixed)

Mistake 1: Hardcoding permissions in the codebase.

My first iteration had permissions defined in config files. This meant every permission change required a code deployment. In an enterprise environment where compliance teams need to adjust access weekly, this was unacceptable.

Fix: Store permissions in the database with an admin UI. The codebase only knows about permission shapes (resource + action), not specific role-permission mappings.

Mistake 2: No permission inheritance.

Initially, "Department Manager" didn't automatically include "Department Member" permissions. Every role had to explicitly list every permission, leading to massive duplication.

Fix: Role hierarchy with inheritance:

const roleHierarchy = {
  department_head: {
    inherits: ['department_manager'],
  },
  department_manager: {
    inherits: ['department_member'],
  },
  department_member: {
    inherits: [], // base level
  },
};

Mistake 3: Treating all denials the same.

A user denied because they lack the role is different from a user denied because of separation of duties. The UI needs to communicate this — one means "ask your admin for access," the other means "this action requires a different person."

Fix: Typed denial reasons that the frontend can act on:

type DenialReason =
  | { type: 'missing_role'; requiredRole: string }
  | { type: 'scope_mismatch'; userScope: string; requiredScope: string }
  | { type: 'separation_of_duties'; conflictingAction: string }
  | { type: 'expired_access'; expiredAt: Date }
  | { type: 'threshold_exceeded'; limit: number; actual: number };

Key Takeaways

Start with the simplest model that works, then extend. Don't build role hierarchy, scoping, and constraints on day one unless you need them immediately. I add complexity when real requirements demand it.
Audit everything. In enterprise, the audit trail isn't a nice-to-have — it's often a legal requirement. Build it from day one; retrofitting is painful.
Separate policy from enforcement. The rules (who can do what) should be configurable without code changes. The enforcement (how checks happen) lives in code.
Cache aggressively, invalidate immediately. Permission checks are hot paths. But stale permissions are security vulnerabilities. Short TTL + instant invalidation on changes is the balance.
Design for the "no" case. Most of your work will be denying access correctly and communicating why. Good error messages save hours of support tickets.

The Bigger Picture

RBAC isn't a solved problem — it's a spectrum. SaaS apps need simple role checks. Enterprise systems need contextual, auditable, hierarchical authorization. Financial systems need all of that plus separation of duties and regulatory compliance.

The craft is in knowing where on that spectrum your system sits today, and building just enough flexibility to handle where it's going tomorrow.

Built with TypeScript, PostgreSQL, Redis, and Next.js.

Connect with me on LinkedIn or explore my work on GitHub.

Designing a Reliable Wallet Engine: Event-Driven Architecture with Kafka and TypeScript

Oladejo Babatunde — Thu, 02 Jul 2026 23:23:57 +0000

The Problem

If you've ever built a fintech product, you know this truth: the hardest part isn't moving money — it's making sure you never lose it.

A wallet engine sounds simple on the surface. Credit. Debit. Balance. But the moment you introduce concurrency, network failures, and the need for auditability, it becomes one of the most demanding distributed systems problems you can tackle.

I built a wallet engine that needed to:

Handle credits, debits, and wallet-to-wallet transfers
Guarantee that no money is created or destroyed (even during failures)
Process concurrent transactions without race conditions
Maintain a full audit trail for every operation
Notify downstream services reliably via events

Here's how I approached it.

Architecture Overview

The system is built on NestJS (TypeScript), PostgreSQL, Apache Kafka, and Redis. Each plays a distinct role:

Component	Responsibility
PostgreSQL	Source of truth — wallets, ledger entries, transactions
Kafka	Asynchronous event distribution to downstream consumers
Redis	Idempotency locks and duplicate request detection
NestJS	Application layer — orchestrates business logic

┌──────────────┐        ┌──────────────┐        ┌──────────────┐
│   Client     │───────▶│  Wallet API  │───────▶│  PostgreSQL  │
│  (REST)      │        │  (NestJS)    │        │  (Source of  │
└──────────────┘        └──────┬───────┘        │   Truth)     │
                               │                └──────┬───────┘
                               │                       │
                        ┌──────▼───────┐        ┌──────▼───────┐
                        │    Redis     │        │ Outbox Table  │
                        │ (Idempotency │        │ (Pending      │
                        │   Locks)     │        │  Events)      │
                        └──────────────┘        └──────┬───────┘
                                                       │
                                                ┌──────▼───────┐
                                                │ Outbox Relay  │
                                                │ (Polls every  │
                                                │  2 seconds)   │
                                                └──────┬───────┘
                                                       │
                                                ┌──────▼───────┐
                                                │    Kafka     │
                                                │  (Events)    │
                                                └──────┬───────┘
                                                       │
                                         ┌─────────────┼─────────────┐
                                         │             │             │
                                  ┌──────▼──┐   ┌─────▼───┐   ┌────▼────┐
                                  │Webhooks │   │Analytics │   │ Notif.  │
                                  │Consumer │   │Consumer  │   │Consumer │
                                  └─────────┘   └─────────┘   └─────────┘

The key insight: the database transaction is the boundary of correctness, and Kafka is the boundary of communication. We never publish to Kafka directly from within business logic — we use the Transactional Outbox pattern to guarantee delivery.

Double-Entry Ledger: The Financial Correctness Foundation

The most critical design decision was implementing a double-entry bookkeeping system. Every financial operation produces exactly two ledger entries: one debit and one credit.

// Every transfer creates a paired debit + credit
const debitEntry = manager.create(LedgerEntry, {
  walletId: sourceWalletId,
  transactionId,
  type: EntryType.DEBIT,   // money leaves this wallet
  amount: amount.toString(),
  runningBalance: newSourceBalance.toString(),
});

const creditEntry = manager.create(LedgerEntry, {
  walletId: destinationWalletId,
  transactionId,
  type: EntryType.CREDIT,  // money enters this wallet
  amount: amount.toString(),
  runningBalance: newDestBalance.toString(),
});

Why this matters: The sum of all ledger entries for any transaction is always zero. This is a provable invariant — if it's ever violated, something has gone seriously wrong. I built a verification method that can audit any transaction:

async verifyTransactionBalance(transactionId: string): Promise<boolean> {
  const entries = await this.ledgerRepo.find({ where: { transactionId } });
  const net = entries.reduce((sum, entry) => {
    const amount = BigInt(entry.amount);
    return entry.type === EntryType.CREDIT ? sum + amount : sum - amount;
  }, 0n);
  return net === 0n; // Must ALWAYS be zero
}

Each entry also carries a runningBalance — the wallet's balance at that point in time. This gives us a full historical trail: you can reconstruct any wallet's balance at any moment by looking at its ledger entries.

Preventing Race Conditions with Pessimistic Locking

When two transfers hit the same wallet simultaneously, you can get phantom reads or double-spending. The naive approach — read balance, check if sufficient, then debit — breaks under concurrency.

I solved this with pessimistic row-level locking (SELECT ... FOR UPDATE):

// Lock both wallets within the same DB transaction
const [sourceWallet, destWallet] = await Promise.all([
  manager.findOne(Wallet, {
    where: { id: sourceWalletId },
    lock: { mode: 'pessimistic_write' },
  }),
  manager.findOne(Wallet, {
    where: { id: destinationWalletId },
    lock: { mode: 'pessimistic_write' },
  }),
]);

const sourceBalance = BigInt(sourceWallet.balance);
if (sourceBalance < amount) {
  throw new BadRequestException('Insufficient balance');
}

The pessimistic_write lock ensures that while one transaction is modifying a wallet's balance, all other transactions on that wallet wait. No race conditions. No double-spending.

Trade-off: This serializes operations on the same wallet. For a wallet processing thousands of transactions per second, you'd need a different approach (like balance reservation or saga patterns). For the volume this system handles, the simplicity of pessimistic locking wins.

Idempotency: Handling Duplicates Without Losing Money

Network timeouts, client retries, message redelivery — in distributed systems, you will receive the same request multiple times. The system must handle this gracefully without duplicating financial operations.

Every request carries an idempotency_key. The flow:

Check Redis for an existing result with this key
If found and completed → return the cached result (no-op)
If found and processing → reject (another instance is handling it)
If not found → acquire a distributed lock, execute the operation, cache the result

async wrap<T>(idempotencyKey: string, operation: () => Promise<T>): Promise<T> {
  const existing = await this.getExistingResult(idempotencyKey);
  if (existing?.status === IdempotencyStatus.COMPLETED) {
    return existing.result as T; // Safe replay
  }
  if (existing?.status === IdempotencyStatus.PROCESSING) {
    throw new ConflictException('Request already being processed');
  }

  const locked = await this.acquireLock(idempotencyKey);
  if (!locked) {
    throw new ConflictException('Duplicate request detected');
  }

  await this.markProcessing(idempotencyKey);
  try {
    const result = await operation();
    await this.markCompleted(idempotencyKey, result);
    return result;
  } catch (error) {
    await this.markFailed(idempotencyKey, error.message);
    throw error;
  }
}

A subtle detail: the lock has a TTL of 60 seconds, with automatic extension every 15 seconds while processing. This handles the case where a database transaction takes longer than expected — the lock won't expire mid-operation and allow a duplicate through.

The Transactional Outbox Pattern: Reliable Event Publishing

This is where Kafka enters the picture. The challenge: after completing a transfer, we need to notify downstream services (webhooks, analytics, notifications). But publishing to Kafka directly from within a database transaction creates a dangerous coupling — if Kafka is down, the transaction fails even though the business operation was valid.

The Transactional Outbox solves this cleanly:

Within the same database transaction as the business operation, write events to an outbox_events table
A separate relay process polls the outbox every 2 seconds and publishes pending events to Kafka
Once published, mark the event as delivered

// Inside the same DB transaction as the transfer
await this.outboxService.write(
  {
    aggregateId: completedTxn.id,
    aggregateType: 'transaction',
    eventType: 'transaction.completed',
    kafkaTopic: 'transaction.completed',
    payload: {
      transactionId: completedTxn.id,
      type: 'transfer',
      sourceWalletId,
      destinationWalletId,
      amount,
      currency: completedTxn.currency,
      timestamp: new Date().toISOString(),
    },
  },
  manager, // Same EntityManager = same DB transaction
);

Guarantees:

If the business transaction commits, the outbox event is guaranteed to exist
If the transaction rolls back, the outbox event disappears with it
The relay delivers at-least-once — Kafka consumers must be idempotent (which they are, using the same idempotency pattern)

The relay itself is simple but robust:

private async relay() {
  const events = await this.outboxService.getPendingEvents(50);
  for (const event of events) {
    try {
      await this.kafkaProducer.publish(event.kafkaTopic, event.payload, event.aggregateId);
      await this.outboxService.markPublished(event.id);
    } catch (error) {
      await this.outboxService.markFailed(event.id, error.message, event.retryCount + 1);
    }
  }
}

After 5 failed attempts, an event is marked as permanently failed — this triggers alerting and manual investigation.

Atomic Transfers: Everything or Nothing

A wallet-to-wallet transfer involves multiple operations: creating the transaction record, writing ledger entries, updating both wallet balances, logging the audit trail, and writing outbox events. All of this happens inside a single PostgreSQL transaction:

const transaction = await this.dataSource.transaction(async (manager) => {
  // 1. Create transaction record
  const savedTxn = await manager.save(Transaction, txn);

  // 2. Audit log
  await this.auditService.logWithManager({ ... }, manager);

  // 3. Double-entry ledger (with pessimistic locks)
  await this.ledgerService.createDoubleEntry({ ... }, manager);

  // 4. Settle entries
  await this.ledgerService.settleEntries(savedTxn.id, manager);

  // 5. Mark complete
  savedTxn.status = TransactionStatus.COMPLETED;
  const completedTxn = await manager.save(Transaction, savedTxn);

  // 6. Outbox events for Kafka
  await this.outboxService.write({ ... }, manager);

  return completedTxn;
});

If any step fails — insufficient balance, database error, constraint violation — everything rolls back. No partial state. No orphaned ledger entries. No wallet with a deducted balance but no corresponding credit.

Reversals: Undoing Without Destroying History

When a transfer needs to be reversed, I don't delete or modify existing entries. Instead, the system creates a new transaction in the opposite direction:

async reverseEntries(originalTransactionId, reversalTransactionId, manager) {
  const originalEntries = await manager.find(LedgerEntry, {
    where: { transactionId: originalTransactionId, status: EntryStatus.SETTLED },
  });

  // Reversal swaps the direction
  return this.createDoubleEntry({
    transactionId: reversalTransactionId,
    sourceWalletId: creditEntry.walletId,      // original recipient sends back
    destinationWalletId: debitEntry.walletId,   // original sender receives
    amount: BigInt(debitEntry.amount),
    description: `Reversal of transaction ${originalTransactionId}`,
  }, manager);
}

The original transaction is marked as REVERSED, and the new reversal transaction is its own complete record. The audit trail is preserved end-to-end — you can always trace what happened, when, and why.

Webhook Delivery with Retry Logic

Downstream services need to be notified of completed transactions. The webhook system consumes from Kafka and delivers HTTP payloads with exponential backoff:

Attempt 1: immediate
Attempt 2: after 5 seconds
Attempt 3: after 30 seconds
After 3 failures: mark as permanently failed

Each delivery attempt is tracked with response codes, error messages, and duration — full observability into integration health.

The consumer uses manual offset commits — it only advances the Kafka offset after successfully processing a message. If processing fails, the message will be redelivered on the next consumer restart.

What I'd Do Differently at Scale

This architecture works well for its current volume, but at 10x or 100x scale, several things would change:

Replace polling-based outbox relay with CDC (Change Data Capture via Debezium). Eliminates the 2-second polling delay and reduces database load.
Partition Kafka topics by wallet ID. This ensures all events for a given wallet are processed in order, enabling parallel consumption without ordering violations.
Add a balance reservation step for high-throughput wallets. Instead of locking the row for the entire transaction, reserve the amount upfront and settle asynchronously.
Introduce a dead-letter queue for permanently failed events. Currently failed outbox events just sit — at scale, they need automated alerting and recovery workflows.
Move to event sourcing for the ledger. Instead of storing the current balance as a field, derive it entirely from the ledger entries. This eliminates any possibility of balance drift.

Key Takeaways

Building a wallet engine taught me that financial systems demand a different mindset. You can't think in terms of "usually works" — you have to think in terms of invariants that must never be violated.

The patterns that made this system reliable:

Double-entry bookkeeping — provable correctness via zero-sum invariant
Pessimistic locking — eliminates race conditions at the database level
Transactional Outbox — decouples event publishing from business logic
Idempotency everywhere — safe retries at every layer
Atomic transactions — no partial state, ever
Append-only audit trail — nothing is deleted, everything is traceable

These aren't novel ideas. They're proven patterns from decades of financial systems engineering. The craft is in applying them correctly, understanding their trade-offs, and building them into a cohesive system that a team can maintain and evolve.

Built with NestJS, TypeScript, PostgreSQL, Apache Kafka, and Redis.

Have questions about the implementation? Find me on LinkedIn or GitHub.