10 Saas Multi Tenancy Architecture Spec

SaaS Multi-Tenancy Architecture Specification Skill

Use When

• Tenant boundaries materially affect service, data, deployment or operating design.

Do Not Use When

• Do not use for a single-tenant system or to claim isolation without enforcement and detection evidence.

Required Inputs

Workflow

1. Read the named inputs and confirm their approval, version and unresolved decisions.
2. Apply the decision rules below before drafting; stop on a missing authority, unsafe assumption or unresolved scope driver.
3. Produce the Multi-Tenancy Architecture Specification and ADR seeds through the existing domain procedure and load only the references needed for the chosen branch.
4. Trace each material statement in the Multi-Tenancy Architecture Specification and ADR seeds to an input, decision or explicitly qualified assumption.
5. Verify the observable acceptance conditions, record unassessed checks, and hand the artefacts to their named consumers.
6. If validation fails, recover by correcting the source decision or artefact and rerun the affected check; do not weaken the acceptance condition.

Outputs

Evidence Produced

Capability and permission boundaries

Read-only is the default for analysis, review, evaluation and planning. Read and search access to authorised project artefacts are required. Editing is limited to an explicitly requested project deliverable. Execution may run document, syntax or validation checks. Network access is used only for facts that require current verification. Do not publish, spend, change production, approve policy, or claim certification without explicit authority.

Degraded mode

If any required capability is unavailable, return the narrowest useful qualified Multi-Tenancy Architecture Specification and ADR seeds draft plus a gap register showing the missing item, affected sections, risk and owner. Never convert an unassessed check into a pass.

Decision Rules

Quality Standards

• Preserve repository terminology and trace every material choice to project context.
• Use deterministic acceptance conditions; replace vague quality claims with an observable check, threshold or named approval.
• Cover error, empty, edge, recovery and operational cases relevant to this skill.
• Verify standards, citations, APIs and package names before relying on them; qualify what cannot be checked.
• Stop release for a failed safety, security, legal, financial, accessibility or data-integrity gate.

Anti-Patterns

• Declaring multi-tenant without a service matrix. Fix: decide per service and store.
• Trusting a request header for tenant context. Fix: derive and verify context from authenticated identity.
• Using row filters without bypass tests. Fix: add database and service enforcement evidence.
• Ignoring background jobs. Fix: propagate tenant context through queues and schedulers.
• Calling throttling a noisy-neighbour strategy. Fix: define quotas, fairness, detection and tier behaviour.

References

• Tenancy decision template
• Control-plane services
• HLD neighbour

Overview

This skill produces the SaaS-distinctive architecture artefact that no generic HLD captures: the explicit two-plane decomposition, the per-microservice tenancy-pattern matrix, tenant-context propagation, isolation strategy, noisy-neighbor controls, per-tenant cost-attribution method, and the ADR seeds. It is the canonical Phase 03 SaaS skill.

The skill is anchored in Tod Golding, Building Multi-Tenant SaaS Architectures (O'Reilly, 2024). It assumes a generic HLD.md already exists (from 01-high-level-design) and that the present skill augments it with the SaaS-specific viewpoints.

When to Use

• The project's vision.md or PRD.md describes a multi-tenant SaaS (B2B, B2C, vertical, horizontal).
• A generic HLD.md already exists or will be created in the same Phase 03 run.
• Tenancy decisions, isolation evidence, or per-tenant cost attribution are in scope.

Quick Reference

Input Files

Output Files

Core Instructions

Follow these nine steps in order. Halt if any required input is missing.

Step 1: Read context

Read SRS_Draft.md, HLD.md, tech_stack.md, PRD.md, vision.md. Identify regulatory constraints, data-residency requirements, target ICP segments, expected tier mix, and any "enterprise must have dedicated infra" obligations. Log all source citations.

Step 2: Declare the two-plane decomposition

Per Golding Ch.2, every SaaS architecture has a control plane (onboarding, identity, tenant management, metering, billing, deployment automation, operations, analytics) and an application plane (the domain microservices that carry tenant context).

Produce a Mermaid diagram showing the two planes, the services in each, and the events/APIs crossing the boundary. Every service in scope shall be classified as control-plane or application-plane.

flowchart LR
    subgraph CP[Control Plane]
        Onb[Onboarding]
        Idn[Identity]
        TMg[Tenant Management]
        Met[Metering]
        Bil[Billing]
        Dep[Deployment Automation]
        Ops[Operations Console]
    end
    subgraph AP[Application Plane]
        Svc1[Domain Service 1]
        Svc2[Domain Service 2]
        SvcN[Domain Service N]
    end
    CP -- "tenant lifecycle events" --> AP
    AP -- "metering events" --> CP

Step 3: Fill the per-microservice tenancy-pattern matrix

For every microservice in the application plane, fill the following table:

Patterns are drawn from Golding Ch.3:

• Full-Stack Silo — dedicated compute and storage per tenant. Highest isolation, simplest cost attribution, hardest cost efficiency.
• Full-Stack Pool — shared compute and storage. Best efficiency, requires explicit isolation, noisy-neighbor controls, per-tenant metering.
• Mixed-Mode — pool one resource (e.g. compute) while silo another (e.g. storage).
• Pod — group N tenants per stack; rebalance as needed.
• Account-per-Tenant / VPC-per-Tenant — silo at the cloud-account or network boundary; often used by migrating ISVs or strict-isolation industries.

Every row shall name at least one driver from the regulated list. Drivers without measurable thresholds are not drivers — replace with a measurable threshold (e.g. "P95 cross-tenant latency interference < 10 ms" not "low interference").

Step 4: Write the tenant-context specification

Document the token format, claims (tenant_id, tier, region, roles), how the token is issued (control-plane → application-plane), how it is propagated across services (HTTP header, gRPC metadata, async-event envelope), how it is validated at each service boundary, and the fail-safe behaviour when the context is missing or invalid (reject request, audit log, alarm).

Cite SRS-section identifiers for each rule and write a Verification Procedure table — how each rule is tested in CI.

Step 5: Write the isolation strategy

For each tenancy pattern in use, document the isolation enforcement at each layer:

• Network — VPC, subnet, security groups, service mesh policy.
• Compute — process, container, namespace, dedicated worker, throttling.
• Storage — database, schema, row-level security, encryption-key boundary (per-tenant KMS key?), index partitioning.
• IAM — IAM role-per-tenant, attribute-based access, signed-context propagation.
• Code path — repository query helpers that reject queries without tenant filter, lint rules, runtime assertions.

Cross-link to 09-governance-compliance/11-saas-data-isolation-evidence-pack which produces the evidence artefact.

Step 6: Document noisy-neighbor controls and per-tier SLOs

For every pooled service, document:

• Throttling / rate-limit per tenant and per tier.
• Quotas (concurrent jobs, request-rate, queue depth).
• Per-tier SLOs (Bronze / Silver / Gold / Enterprise) for latency, availability, support response.
• Burst headroom and the back-off behaviour.

Cross-link to 06-deployment-operations/08-saas-slo-and-error-budget-doc.

Step 7: Document per-tenant cost attribution

For every pooled service, state the method by which infrastructure cost is attributed back to the tenant: metered usage events (API calls, storage GB-month, compute seconds), allocation of shared costs (per-tenant share of base infrastructure), reporting cadence (daily / monthly), and the destination (FinOps dashboard, finance ERP). This feeds the Pricing & Packaging Spec and the Billing & Metering SRS.

Step 8: Emit ADR seeds

For each microservice, emit one ADR file at adr-seeds/0001-tenancy-pattern-<service>.md using the template at references/saas-tenancy-decision-template.md. Each ADR contains: context, decision, status, consequences, drivers, alternatives considered, evidence references, sign-off owners.

Also emit one ADR for the control-plane / application-plane boundary: where API calls cross the boundary, what events propagate, what isolation exists.

Step 9: Write the spec

Write Multi_Tenancy_Architecture_Spec.md with the following sections in order:

1. Two-Plane Decomposition Diagram
2. Control-Plane Services Inventory
3. Application-Plane Services Inventory
4. Per-Microservice Tenancy-Pattern Matrix
5. Tenant Context Specification
6. Isolation Strategy (per layer × per pattern)
7. Noisy-Neighbor & Per-Tier SLOs
8. Per-Tenant Cost Attribution
9. Tenant Lifecycle Event Catalogue (cross-link to lifecycle runbook)
10. ADR Seed Index
11. Traceability Matrix (every section → SRS clause or PRD requirement)

Log the section count and ADR-seed count.

Output Format

Strict heading order as above. Mermaid for all diagrams. LaTeX for any quota / cost formulas. Tables for the tenancy-pattern matrix and SLOs. No vague adjectives — every NFR has a measurable threshold per 02-requirements-engineering/references/saas-nfr-catalog.md.

Common Pitfalls

Verification Checklist

• Every microservice appears in the tenancy-pattern matrix.
• Every row cites at least one driver with a measurable threshold.
• Tenant context spec defines token format, claims, propagation rule, validation rule, fail-safe behaviour.
• Isolation strategy covers network, compute, storage, IAM, code path for every pooled pattern.
• Per-tier SLOs exist for every pooled service.
• Per-tenant cost attribution method exists for every pooled service.
• One ADR seed exists per microservice plus one for the control-plane boundary.
• Traceability matrix maps every section to SRS or PRD.

Integration

Standards

• IEEE 1016-2009 Sec 5 — Architectural Design Viewpoints.
• ISO/IEC 25010 — Quality model (capability, performance, security, maintainability, portability).
• AWS Well-Architected SaaS Lens — control-plane / application-plane vocabulary.
• Golding (2024) — silo / pool / mixed / pod taxonomy.

Resources

• logic.prompt — Executable prompt.
• README.md — Quick-start.
• references/saas-tenancy-decision-template.md — ADR template per service.
• references/saas-control-plane-services.md — Canonical control-plane service catalogue.
• book-extractions/saas-architectures-srs-extraction.md — Source synthesis.