// tenant-context.middleware.ts
import { Request, Response, NextFunction } from 'express';

export interface TenantContext {
  orgId: string;
  userId: string;
  role: 'admin' | 'editor' | 'viewer';
}

declare global {
  namespace Express {
    interface Request {
      tenant: TenantContext;
    }
  }
}

export function resolveTenantContext(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing or malformed token' });
  }

  // Decode JWT and extract claims
  const claims = decodeJwtPayload(authHeader.split(' ')[1]);
  if (!claims?.org_id || !claims?.sub) {
    return res.status(403).json({ error: 'Invalid tenant claims' });
  }

  req.tenant = {
    orgId: claims.org_id,
    userId: claims.sub,
    role: claims.role || 'viewer'
  };

  next();
}

function decodeJwtPayload(token: string): Record<string, any> {
  const base64Url = token.split('.')[1];
  const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
  return JSON.parse(Buffer.from(base64, 'base64').toString('utf-8'));
}

// rbac-policy.engine.ts
type Resource = 'project' | 'billing' | 'settings' | 'audit_log';
type Action = 'read' | 'write' | 'delete' | 'export';

const POLICY_MATRIX: Record<string, Action[]> = {
  admin: ['read', 'write', 'delete', 'export'],
  editor: ['read', 'write'],
  viewer: ['read']
};

export function enforcePermissio

n(req: Request, resource: Resource, action: Action) { const allowed = POLICY_MATRIX[req.tenant.role] || []; if (!allowed.includes(action)) { throw new Error(Permission denied: ${req.tenant.role} cannot ${action} ${resource}); } }

**Architecture Rationale:** Hardcoding role matrices in early stages reduces complexity. As the platform grows, this can migrate to a dynamic policy store (e.g., OpenPolicyAgent or Casbin). The enforcement function throws early, preventing unnecessary database queries when permissions fail.

### Step 3: Subscription Billing & Webhook Verification
Stripe subscriptions require idempotent webhook handling. Payment events must be verified cryptographically and processed asynchronously to avoid blocking the payment provider.

```typescript
// billing.webhook.handler.ts
import { Request, Response } from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: '2025-08-31.basil' });
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

export async function handleStripeWebhook(req: Request, res: Response) {
  const signature = req.headers['stripe-signature'] as string;
  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(req.body, signature, webhookSecret);
  } catch (err) {
    return res.status(400).send(`Webhook signature verification failed.`);
  }

  // Acknowledge immediately to prevent Stripe retries
  res.status(200).json({ received: true });

  // Process asynchronously
  await processBillingEvent(event);
}

async function processBillingEvent(event: Stripe.Event) {
  switch (event.type) {
    case 'invoice.payment_succeeded':
      await activateSubscription(event.data.object as Stripe.Invoice);
      break;
    case 'invoice.payment_failed':
      await flagPaymentIssue(event.data.object as Stripe.Invoice);
      break;
    case 'customer.subscription.deleted':
      await suspendTenantAccess(event.data.object as Stripe.Subscription);
      break;
  }
}

Architecture Rationale: Stripe sends webhooks with exponential backoff. Acknowledging receipt before processing prevents duplicate charges and timeout errors. The switch statement routes events to domain-specific handlers, keeping the webhook controller thin and testable.

Step 4: Audit Logging for Compliance

Enterprise procurement requires immutable audit trails. Structured logging with tenant scoping satisfies GDPR and SOC 2 requirements without bloating the primary database.

// audit.logger.service.ts
import { createWriteStream } from 'fs';
import { appendFile } from 'fs/promises';

const AUDIT_LOG_PATH = process.env.AUDIT_LOG_PATH || '/var/log/saas/audit.jsonl';
const logStream = createWriteStream(AUDIT_LOG_PATH, { flags: 'a' });

interface AuditEntry {
  timestamp: string;
  org_id: string;
  actor_id: string;
  action: string;
  resource_type: string;
  resource_id: string;
  metadata: Record<string, any>;
}

export async function writeAuditLog(entry: AuditEntry) {
  const record = JSON.stringify({ ...entry, timestamp: new Date().toISOString() }) + '\n';
  await appendFile(AUDIT_LOG_PATH, record);
  logStream.write(record);
}

Architecture Rationale: JSON Lines (.jsonl) format enables streaming ingestion into log aggregators (Datadog, Loki, or Elasticsearch) without database overhead. Immutable file writes satisfy compliance auditors who require tamper-evident records.

Pitfall Guide

1. Delaying Tenant Isolation Until Scale

Explanation: Teams often store all data in a single table with an org_id column but skip RLS or application-level filtering. When query volume grows, accidental cross-tenant data leaks occur, and performance degrades due to missing composite indexes. Fix: Implement RLS policies or middleware-level query scoping from day one. Add composite indexes on (org_id, created_at) to maintain query performance as data grows.

2. Hardcoding Pricing Tiers in Client-Side Code

Explanation: Embedding plan limits (e.g., MAX_PROJECTS = 50) in frontend bundles allows users to bypass restrictions by modifying local state or API payloads. Fix: Enforce tier limits server-side using a configuration service or feature flag system. Validate usage quotas before executing write operations.

3. Treating Webhooks as Synchronous Operations

Explanation: Processing Stripe or calendar sync webhooks inline blocks the HTTP response, causing provider timeouts and duplicate event delivery. Fix: Always acknowledge webhooks immediately, then push payloads to a message queue (Redis, RabbitMQ, or cloud-native queues). Process asynchronously with idempotency keys.

4. Ignoring Audit Trail Requirements Until Enterprise

Explanation: Startups skip logging because it feels like enterprise overhead. When B2B contracts require SOC 2 or GDPR compliance, retrofitting audit logs requires schema migrations and data backfilling. Fix: Implement structured audit logging from MVP stage. Store minimal fields initially (actor, action, timestamp, org_id) and expand metadata as compliance requirements mature.

5. Underestimating Maintenance & Dependency Drift

Explanation: Teams budget for build costs but ignore the 20–30% annual maintenance overhead. Unpatched dependencies introduce security vulnerabilities, and framework upgrades break integration contracts. Fix: Allocate maintenance budgets upfront. Implement automated dependency scanning (Dependabot, Snyk) and schedule quarterly framework review cycles.

6. Over-Provisioning Infrastructure at MVP Stage

Explanation: Provisioning Kubernetes clusters, multi-region databases, and auto-scaling groups for 100 users wastes capital and increases operational complexity. Fix: Start with serverless or managed PaaS (Vercel, Supabase, Firebase). Migrate to containerized orchestration only when traffic patterns justify the operational overhead.

7. Skipping Compliance Documentation Early

Explanation: GDPR and SOC 2 require documented data flows, retention policies, and breach response procedures. Writing these post-launch delays enterprise sales cycles. Fix: Maintain a living compliance repository. Map data ingestion points, define retention windows, and draft incident response playbooks during the discovery phase.

Production Bundle

Action Checklist

• Define tenant isolation model: shared schema with RLS vs. separate schemas
• Implement JWT-based tenant context extraction before any route handlers
• Configure Stripe webhook signature verification and async event routing
• Establish RBAC policy matrix and enforce server-side before database queries
• Deploy structured audit logging with JSONL format and log rotation
• Map compliance requirements (GDPR, SOC 2) to data retention and access controls
• Allocate 20–30% of build budget for annual maintenance and dependency updates
• Set up monitoring for webhook retry rates, payment failures, and tenant query latency

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Early-stage startup (<1k users)	Shared schema + RLS + Serverless hosting	Minimizes infra overhead, accelerates iteration	Low (€50–€200/mo)
Mid-market SaaS (1k–50k users)	Separate read replicas + Message queue for webhooks	Improves query performance, prevents webhook bottlenecks	Medium (€300–€800/mo)
Enterprise B2B (SOC 2/GDPR required)	Dedicated tenant schemas + Audit log aggregation + SSO	Meets procurement requirements, enables data residency controls	High (€1,000–€3,000/mo)
Heavy third-party integrations	Event-driven architecture + Idempotency store	Prevents duplicate processing, simplifies retry logic	Medium (€200–€500/mo)

Configuration Template

// infrastructure.config.ts
export const SaaSConfig = {
  tenant: {
    isolationStrategy: 'row-level-security',
    orgIdClaim: 'org_id',
    userIdClaim: 'sub',
    roleClaim: 'role'
  },
  billing: {
    provider: 'stripe',
    webhookEndpoint: '/api/billing/webhooks',
    retryPolicy: { maxAttempts: 5, backoffMultiplier: 2 },
    feeStructure: { percentage: 0.005, fixed: 0.25 }
  },
  compliance: {
    auditLogPath: '/var/log/saas/audit.jsonl',
    retentionDays: 365,
    gdprDataExportEndpoint: '/api/compliance/export',
    soc2AuditTrailRequired: true
  },
  observability: {
    metricsEndpoint: '/api/health/metrics',
    logLevel: process.env.NODE_ENV === 'production' ? 'warn' : 'debug',
    alertingChannels: ['email', 'slack']
  }
};

Quick Start Guide

1. Initialize tenant context middleware: Extract org_id and role from JWT claims and attach to the request object. Enforce RLS on all database queries.
2. Configure Stripe webhook handler: Verify signatures, acknowledge receipt immediately, and route events to an async processor with idempotency checks.
3. Deploy audit logging service: Write structured JSONL entries for all write operations. Configure log rotation and retention policies matching compliance requirements.
4. Validate RBAC enforcement: Test permission boundaries using mock tokens for each role. Ensure server-side checks block unauthorized access before database execution.
5. Monitor and iterate: Track webhook failure rates, tenant query latency, and payment success ratios. Adjust infrastructure scaling only when metrics justify the cost.