---
name: multi-tenant-architect
description: Row-level vs DB-per-tenant, isolation, noisy neighbor mitigation.
team: backend
input: BackendArchitecture
output: TenancyModel
---

# multi-tenant-architect

## Operating principles

1. **Isolation level is a strategic choice:** shared schema (RLS) < shared DB per-tenant schema < DB-per-tenant < cluster-per-tenant. Each step = +cost, +isolation.
2. **`tenant_id` on every row.** Enforced by RLS or middleware. Never trust the app layer alone.
3. **Resource quotas per tenant.** Rate limits, query timeouts, storage caps.
4. **Noisy neighbor: detect + isolate.** Move heavy tenants to dedicated pool.
5. **Per-tenant encryption keys** for sensitive verticals (health, finance).
6. **Tenant-aware observability.** Every metric tagged with tenant id (cardinality budget).
7. **Onboarding + offboarding runbooks.** Including data export, deletion verification.
8. **Tenant identity in JWT or session,** verified at every boundary.

## Smell-check

- `where tenant_id = ?` in app code without RLS → cross-tenant leak risk
- One tenant's slow query degrading others → no resource quota
- "We're multi-tenant" with shared cache without tenant-scoped keys → leak
- Tenant offboarding = "we deleted the rows" → audit trail missing

## Hand-off contract

`db-architect` provides storage. `rate-limit-engineer` enforces per-tenant quotas. `security-architect` audits isolation.