SaaS Multi-tenancy: Demand-gated Architecture

Why make the decision demand-gated?

Multi-tenancy is not a SaaS badge of maturity. If a product has few tenants, unproven cost pressure, weak operating capacity, or no traceable tenant context across requests and data, premature sharing can increase complexity and blast radius. This lesson does not pick a fashionable pattern. It builds Demand-gated SaaS Multi-tenancy Decision, Isolation & Operations Matrix v1 so POOL, SILO, HYBRID_STAMP, or DEFER can be reconstructed from visible evidence.

Core rule: “we can share” is not the same as “we should share now.” Promotion requires three explicit gates: Demand, Isolation, and Operations/Cost. Missing decisive evidence stays typed as HOLD/DEFER rather than being coerced into a positive architecture decision.

Scope and route

This lesson owns the tenancy architecture decision and its evidence package. AGN-014 owns the self-hosted release/support matrix; MKN-001 owns experience-aware instructional design. AGN-012 is the hard prerequisite and AGN-014 is a soft/context prerequisite.

Work in this order: lock the demand snapshot; define tenant identity and tenant-context propagation; state isolation/compliance requirements; compare POOL / SILO / HYBRID_STAMP; bind noisy-neighbor, blast-radius, operability, unit-cost, and migration-cost evidence; then promote only as far as the evidence allows.

Mental model: four evidence layers, one decision

Treat the matrix as four layers: demand (current tenants, forecast, growth trigger, cost pressure), tenant/isolation boundary (tenant context, compliance, resource sharing), operations (quota, observability, onboarding, blast radius), and economics/migration (unit cost and migration cost). The final decision depends on all four, not on a topology diagram alone.

Azure describes a spectrum from shared to per-tenant isolated resources and deployment stamps. AWS treats isolation as foundational while explicitly avoiding a universal isolation strategy. MAKNOW keeps the boundary: external patterns are FACT inputs, not local decision authority.

Matrix foundations

Decision identity starts with architecture_decision_id and demand_snapshot_id. Demand uses tenant_count_current, tenant_count_forecast, growth_trigger, and cost_pressure_signal. tenant_context_propagation_ref and isolation_requirement_ref must then show how tenant identity reaches authentication, authorization, data access, jobs/queues, and observability and what isolation is required.

Operational evidence includes noisy_neighbor_risk, blast_radius, per_tenant_quota_ref, onboarding_automation_state, and tenant_aware_observability_ref. Unknown values here cannot support pooled promotion.

Demand, isolation, and operations gates

The Demand Gate asks whether growth, cost, and tenant demand justify additional sharing complexity. Its threshold is a product policy, not a universal fact. The Isolation Gate checks whether tenant identity and compliance requirements are compatible with the candidate model. A pure pool cannot satisfy a tier that explicitly requires dedicated infrastructure. The Operations Gate checks quota, tenant-aware telemetry, onboarding automation, support capacity, and blast-radius controls.

Large forecast numbers do not create tenant-context evidence. Excellent isolation also does not create unit-cost, migration-cost, or owner-approval evidence. Promotion is review-ready only when the relevant evidence closes together.

Baseline: DEFER can be the correct success state

Product A has 12 tenants now, a 12-month forecast of 24, low cost pressure, and limited operating capacity. Tenant context and isolation requirements are documented, but the demand trigger is not cleared and migration into shared state is costly. The bounded result is DEFER_SHARED_MULTI_TENANCY / DEFERRED, producing DEFER_REVIEW_READY. This is not an architecture failure; it is a justified timing decision with a visible revisit trigger.

In the lesson mutation, forecast grows while tenant_context_propagation_ref disappears and the decision is forced to PROMOTE_POOL. The evaluator must return HOLD_TENANT_CONTEXT_MISSING: tenant count is not isolation proof.

Failure modes

1. SaaS means pooled by default — SaaS business model and resource sharing are different decisions.
2. Forecast becomes authority — demand evidence is not security approval.
3. Tenant-aware login, tenant-blind jobs — incomplete propagation can cross boundaries.
4. Noisy-neighbor risk without quota — one tenant can consume shared capacity.
5. Observability without tenant dimension — incident blast radius becomes hard to prove.
6. Pure pool for a regulated dedicated tier — explicit isolation conflict.
7. Invented owner approval — unknown authority remains HOLD.

Pool, silo, and hybrid/stamp trade-offs

POOL can improve density and unit cost but demands stronger tenant-context and isolation controls and makes noisy-neighbor/blast-radius concerns central. SILO simplifies isolation reasoning but can raise unit cost and deployment-management overhead. HYBRID_STAMP can keep ordinary tenants in shared stamps while routing regulated/high-risk tiers to dedicated stamps, but it adds control-plane, tenant-to-deployment mapping, and migration complexity.

There is no globally best answer. A good artifact states which option is bounded for this evidence package and which trigger reopens the decision.

Experienced bridge: from pattern catalog to decision system

If you already know pool/silo/stamp patterns, focus on schema and gates. Build a decision record that can be rerun after small mutations: compliance changes to dedicated, forecast grows, tenant-aware telemetry appears, or migration cost doubles. If the output changes without evidence changing, the evaluator is unstable. If evidence changes but the output remains frozen because baseline was copied, transfer fails.

Guided and independent practice

Run the baseline and explain why DEFER_REVIEW_READY is a success state. Next, raise forecast and force promotion while removing tenant-context evidence; expect HOLD. For independent practice, model a product with hundreds of tenants, high cost pressure, tenant-aware observability and quotas, but a regulated tier that must stay dedicated. Recompute HYBRID_STAMP from scratch and make tenant-to-deployment mapping explicit.

All fixtures are synthetic and offline. The lab never touches a network, cloud account, billing system, or production tenant.

Verification evidence

A reviewer must be able to reconstruct: demand snapshot, tenant-context path, isolation requirement, noisy-neighbor controls, blast radius, per-tenant quota, tenant-aware observability, unit and migration cost, decision option/state, owner approval, revisit trigger, and audit reference. If a decisive field is unknown, a positive promotion state is forbidden.

Assessment and transfer

The baseline DEFER result is never an oracle. Product B has hundreds of tenants, high cost pressure, per-tenant quota, and tenant-aware observability, but one regulated tier requires dedicated infrastructure. Pure POOL conflicts; full SILO may be unnecessarily expensive. With a complete tenant-to-deployment map, blast-radius controls, cost/migration evidence, and owner approval, HYBRID_STAMP can reach TRANSFER_HYBRID_REVIEW_READY. Missing decisive evidence keeps HOLD visible.

References, Fact / Inference / Design, and freshness

FACT: Azure documents multitenant approaches from shared through isolated resources and the trade-offs among scale, isolation, cost, performance, complexity, and manageability. FACT: AWS treats tenant isolation as foundational and context-dependent. INFERENCE: demand-gated promotion is a MAKNOW engineering inference from those trade-offs and the cost of complexity. DESIGN: thresholds, success states, owner authority, and revisit policy are MAKNOW-controlled.

The AWS locator frozen in the Bible points to an outdated/unrelated path; the same claim was rechecked against the current official Tenant Isolation — SaaS Lens page. The locator correction is recorded in the freshness/evidence layer without mutating the frozen Bible. Review again by 2027-01-01 or sooner on material guidance changes.