Dibya Sarothi
Dibya Sarothi
SaaSProduction ReadyOctober 2026

ClientForge

Enterprise Workforce & Client Intelligence OS

Multi-tenant workforce orchestration and billing architecture powered by Django 6, Next.js 16, PostgreSQL 16, Redis 8, Celery, and Stripe.

ClientForge overview
Project Overview

ClientForge is an enterprise B2B multi-tenant workforce and client operations OS built with Next.js 16 / React 19, Django 6 / DRF 3.18, PostgreSQL 16, Redis 8, and Celery 5.6. Designed for high-certainty organizational isolation via TenantContextMiddleware, RBAC permissions, Firebase SSO, AES-256 encrypted document storage with SHA-256 seals, immutable HMAC audit logs, and idempotent Stripe Checkout billing.

Problem Statement

Most SaaS platforms for agencies suffer from leaky tenant data abstraction, brittle role enforcement, and non-deterministic business logic for sensitive operations like billing cycles and financial invoices. Ad-hoc authorization middleware often allows IDOR vulnerabilities across client boundaries.

Engineering Rationale

In multi-tenant B2B environments, data crossover between organizations is catastrophic. Financial contracts and client invoicing require mathematical audit trails where floating-point errors, unverified tenant contexts, and unvalidated third-party webhooks are completely unacceptable.

Engineering Objectives

Strict multi-tenant organization context enforced at the database query set level.
Custom JWT authentication with organization-switching without re-authenticating.
Deterministic billing engine with verifiable invoice and payment statement generation.
Enterprise audit logging tracking every state mutation across tenant boundaries.
Webhook-driven Stripe subscription lifecycles with idempotency guarantees.
Architecture Blueprint

System Architecture

ClientForge employs a decoupled architecture: an asynchronous-ready Django REST Framework backend serving clean RESTful APIs to an optimized Next.js frontend. Tenant identification is resolved via custom request middleware with thread-local context isolation, enforcing strict tenant scoping on every ORM query.

01

Deterministic Multi-Tenancy

Middleware extracts the tenant header, verifies active user membership and roles, and scopes the base QuerySet automatically, preventing cross-tenant leakage by design.

02

Double-Entry Invoicing Engine

Billing calculations run as atomic database transactions with deterministic rounding, tax rates, and itemized billing lines before PDF receipt compilation.

03

Resilient Webhook Handlers

Stripe billing webhooks execute within idempotent handlers, verifying cryptographic signatures and caching processed event IDs to prevent duplicate credits.

Core & Backend Implementation

  • Custom Django user model utilizing Email as the primary identifier with bcrypt password hashing.
  • Dynamic tenant middleware injecting verified organization context into request lifecycle.
  • Granular role-based permissions (SuperAdmin, OrgAdmin, Manager, Member, Contractor).
  • Celery task queues backed by Redis for asynchronous email deliveries and invoice batch jobs.
  • Comprehensive E2E integration test suite validating multi-tenant boundary compliance.

Client & Interface Layer

  • Next.js App Router with TypeScript and modern server/client component boundaries.
  • Dynamic organization context provider allowing instantaneous workspace switching.
  • Interactive data grids with client-side sorting, pagination, and multi-field filtering.
  • Accessible modal workflows for client project creation, invoice management, and Stripe billing.
  • Lightweight SVG charting for revenue velocity and monthly contract metrics.

Data & Schema Design

Engine / Tier: PostgreSQL with connection pooling & Redis cache tier

Normalized schema featuring strict foreign key cascade rules, unique compound indexes per tenant, and UUID primary keys for external-facing resources.

Core Models & Entities
Organization & OrganizationMembershipCustomUser & DepartmentClientAccount & ProjectContractInvoiceBatch & InvoiceLineItemAuditLog & WebhookEvent

Authentication & Security Controls

Auth Model: Stateless JWT with rotating refresh tokens and organization-scoped claims
  • Cryptographic signature verification on incoming webhooks.
  • Automatic tenant-level database query filtering.
  • Strict CORS origin white-listing with secure cookie handling.
  • Comprehensive audit logging for all critical data modifications.

Engineering Challenges & Technical Decisions

Key Challenges Solved

Challenge: Preventing cross-tenant data leaks across nested foreign key relations.
Engineering Solution: Implemented an abstract TenantAwareModel with a custom ModelManager that injects request tenant context into all default querysets.
Challenge: Handling concurrent invoice batch calculations without race conditions.
Engineering Solution: Utilized PostgreSQL row-level locks ('select_for_update') inside atomic transactions to ensure zero state mutation collisions.

Trade-Off Decisions

Decision: Single Database Multi-Tenancy with Tenant ID Column
Architectural Rationale: Provides superior operational simplicity, unified connection pooling, and simplified database backups compared to schema-per-tenant, while custom managers enforce strict data isolation.
Decision: Stateless JWT with Active Membership Verification
Architectural Rationale: Ensures high throughput for API consumers while middleware still checks user active status and revocation against Redis in under 2ms.

Testing & Verification Methodology

Frameworks & Approach: Django TestCase, Pytest, Postman / Newman E2E Suite
  • E2E tenant boundary penetration test verifying Org A cannot read Org B entities via forged headers.
  • Invoice math precision checks across varying tax brackets and currency decimals.
  • JWT renewal, expiration, and multi-tenant claim validation.

Results & Engineering Takeaways

Deepened mastery in multi-tenant data isolation patterns in relational databases.
Learned that financial logic must never rely on floating point operations; decimal precision and deterministic rounding are non-negotiable.
Architected clean decoupling between business workflows and external payment services.