SaaS
Architecture

Multi-tenancy

• The four patterns: Pool, Bridge, Silo, Hybrid
• Tenant isolation — at app, DB, network
• Postgres Row-Level Security
• Cell-based architecture for scale

The unique problems SaaS poses

• Isolation — Tenant A must never see Tenant B's data, ever
• Noisy-neighbour — one tenant must not be able to degrade everyone else
• Tenant lifecycle — sign-up, trial, paid, churn, GDPR delete
• Tenant-aware billing — usage, seats, tiers, overage, mid-cycle changes
• Tenant-aware identity — every tenant brings their own IdP, ideally
• Tenant-aware compliance — DPA, BAA, residency, audit
• Tenant-aware ops — debug Customer X's bug without copying their data

The schema pattern

CREATE TABLE projects (
  id          uuid PRIMARY KEY,
  tenant_id   uuid NOT NULL REFERENCES tenants(id),
  name        text NOT NULL,
  created_at  timestamptz NOT NULL DEFAULT now()
);

-- Index every tenant-scoped query on (tenant_id, ...)
CREATE INDEX projects_by_tenant
  ON projects (tenant_id, created_at DESC);

Every query must include WHERE tenant_id = $1. Forgetting once = cross-tenant leak.

Schema per tenant

CREATE SCHEMA tenant_acme;
CREATE TABLE tenant_acme.projects (id uuid PRIMARY KEY, ...);

-- Per request, in middleware:
SET search_path = tenant_acme, public;

Same DDL applied to every schema. Migrations replay across thousands of schemas.

Why customers ask for silo

• "Our auditor demands data isolation" — HIPAA, FedRAMP, financial
• "We need our own backup & restore SLA"
• "We need a different SLA" — 99.99% on top, 99.9% in pool
• "BYO encryption keys (BYOK)"
• "Our network team needs to peer into your VPC"

Application layer

• Tenant ID extracted from JWT / session, never from URL or query params
• Middleware that refuses to query without one
• Tests that simulate cross-tenant access and assert 403/404
• Lint rule: any query without WHERE tenant_id = ? is a build failure

The B2B identity matrix

A minimal usage event

{
  "event_id":     "evt_01HRX2...",
  "tenant_id":    "tnt_acme",
  "user_id":      "usr_alice",
  "metric":       "tokens_used",
  "value":        1284,
  "timestamp":    "2026-05-04T10:33:21Z",
  "idempotency":  "req_01HRX2...",
  "metadata": { "model":"gpt-5", "feature":"chat" }
}

Idempotency key prevents double-billing on retry. Stored append-only — never updated or deleted (audit, replay).

The four golden signals — per tenant

• Latency by tenant — find noisy / starved tenants early
• Traffic by tenant — detect ramp / leak / abuse
• Errors by tenant — separate "their bug" from "our bug"
• Saturation by tenant resource — DB connections, rate-limit tokens, queue depth

Three architectures

• Single-region — start here for B2C and small B2B
• Multi-region active-passive — primary region serves; DR site warm. Easy.
• Multi-region per-tenant — tenant pinned to a home region; data, compute, even auth stay there. The "real" multi-region SaaS.

What to log

• Who — user_id, IP, user agent, session
• What — action verb (create, update, delete, share, login)
• On what — resource type + ID + before/after diff
• When — server timestamp (UTC, ISO 8601)
• Where — region, edge POP
• How — auth method (password / SAML / API key)
• Why? — request_id, parent operation

What a cell is

• An independent deployment of the SaaS — its own DB, queue, cache, services
• Hosts N tenants, sized to a known capacity (e.g. 1000 tenants)
• Failure of one cell ≠ failure of the platform — blast radius is one cell
• Routing layer (cell-router) maps tenant → cell

Three takeaways

1. SaaS architecture is multi-tenancy + B2B identity + metering + per-tenant ops. Each is its own discipline; treat them as load-bearing from day one.
2. Build pool, expect to slice into cells, leave a silo escape hatch. The hybrid model is where every successful B2B SaaS ends up.
3. Buy the auth platform, buy the metering platform, buy compliance automation. The differentiation isn't there; the engineering cost is.