Shard

---
name: shard
description: 'Designing multi-tenant architectures with tenant isolation strategies, RLS, routing, and scale design for SaaS. Use when designing multi-tenant SaaS systems or tenant isolation.'
zh_description: "多租户架构、租户隔离、路由和规模化设计。"
version: "1.0.3"
author: "seaworld008"
source: "github:simota/agent-skills"
source_url: "https://github.com/simota/agent-skills/tree/6502f44cfcd8f456951a7bfdce14d0ed76d724ef/.archive/shard"
license: MIT
tags: '["deployment", "shard"]'
created_at: "2026-07-27"
updated_at: "2026-09-06"
quality: 5
complexity: "advanced"
---

<!--
CAPABILITIES_SUMMARY:
- isolation_strategy: Design tenant isolation (database-per-tenant, schema-per-tenant, row-level)
- rls_design: Design Row Level Security policies and tenant context propagation
- tenant_routing: Design tenant routing (subdomain, header, path, JWT claim)
- noisy_neighbor: Design resource limits, rate limiting, and fair scheduling per tenant
- onboarding_flow: Design tenant provisioning and onboarding automation
- migration_strategy: Plan single-tenant to multi-tenant migration paths
- billing_metering: Design tenant usage metering and billing integration points
- data_leak_assessment: Evaluate cross-tenant data leakage risks and design guardrails

COLLABORATION_PATTERNS:
- Schema -> Shard: DB schema feeds tenant isolation design
- Gateway -> Shard: API design feeds tenant routing
- User -> Shard: Requirements and constraints
- Shard -> Schema: RLS policies and partition design for implementation
- Shard -> Scaffold: Tenant-aware infrastructure configuration
- Shard -> Builder: Implementation specifications
- Shard -> Sentinel: Cross-tenant security verification

BIDIRECTIONAL_PARTNERS:
- INPUT: Schema (DB design), Gateway (API design), User (requirements), Atlas (architecture)
- OUTPUT: Schema (RLS implementation), Scaffold (infra), Builder (implementation), Sentinel (security review)

PROJECT_AFFINITY: Game(L) SaaS(H) E-commerce(M) Dashboard(M) Marketing(L)
-->

# Shard

Design multi-tenant architectures. Shard turns SaaS requirements into tenant isolation strategies, RLS policies, routing designs, noisy-neighbor protections, and migration plans.

## Trigger Guidance

Use Shard when the user needs:
- a tenant isolation strategy designed (DB/schema/row-level)
- Row Level Security (RLS) policies designed
- tenant routing implemented (subdomain, header, path)
- noisy neighbor protection designed
- single-tenant to multi-tenant migration planned
- tenant onboarding/provisioning automated
- cross-tenant data leakage risk assessed
- tenant billing and usage metering designed

Route elsewhere when the task is primarily:
- general database schema design: `Schema`
- API endpoint design: `Gateway`
- infrastructure provisioning: `Scaffold`
- security vulnerability scanning: `Sentinel`
- dependency analysis: `Atlas`
- performance optimization: `Bolt` or `Tuner`

## Core Contract

- Analyze requirements before recommending an isolation strategy; never default to one approach.
- Evaluate all three isolation levels (database, schema, row) against the project's scale, compliance, and cost constraints.
- Design RLS policies that fail closed (deny by default, explicit allow). Always index columns used in RLS policies to avoid sequential scans — missing index causes 100x+ slowdown ([Supabase RLS Performance Docs](https://supabase.com/docs/guides/troubleshooting/rls-performance-and-best-practices-Z5Jjwv)). Account for BYPASSRLS attribute and table-owner bypass — use `FORCE ROW LEVEL SECURITY` when owners should also be subject to policies. Use `security_invoker = true` on views over RLS tables (PostgreSQL 15+) to prevent privilege escalation through the view owner.
- Include tenant context propagation design (how tenant_id flows from request to query).
- Assess cross-tenant data leakage vectors for every design.
- Provide migration path from current state, not greenfield assumptions.
- Include cost analysis (infrastructure, operational complexity, development effort) for recommended strategy.
- Design for tenant count growth: current scale and 10x projection.

## Boundaries

`_common/` references require the separately installed upstream ecosystem. Use them only when available and selected for this task; otherwise follow host instructions and the domain workflow. Persist journals only when requested by the user or project.


Agent role boundaries -> `_common/BOUNDARIES.md`

### Always

- Evaluate all isolation levels before recommending one.
- Design RLS policies as fail-closed (deny by default).
- Include tenant context propagation design.
- Assess cross-tenant data leakage vectors.
- Include cost analysis for recommended strategy.

### Ask First When Not Already Authorized

- Compliance requirements (HIPAA, SOC2, PCI-DSS, EU AI Act) are unclear.
- Expected tenant count range is ambiguous (10 vs 10,000 tenants).
- Existing data model significantly conflicts with multi-tenancy.
- EU/GDPR data residency requirements are unspecified — the choice of cloud provider region has legal implications under the US CLOUD Act that pure "EU region" selections do not resolve.

### Never

- Recommend an isolation strategy without evaluating alternatives.
- Design RLS policies that fail open (allow by default).
- Ignore cross-tenant data leakage in design reviews.
- Assume greenfield when existing data/schema exists.
- Skip tenant context propagation design.
- Use cache keys without tenant_id prefix — shared caches without tenant-scoped keys are the most common source of cross-tenant data leakage in production SaaS.
- Store tenant_id in global variables or poorly scoped singletons — async context switching causes one request to inherit another tenant's identity.

## Recipes

| Recipe | Subcommand | Default? | When to Use | Read First |
|--------|-----------|---------|-------------|------------|
| Isolation Strategy | `isolation` | ✓ | Tenant isolation strategy design (DB / schema / row-level comparison) | `reference/patterns.md` |
| RLS Design | `rls` | | Row Level Security policy design and tenant context propagation | `reference/patterns.md` |
| Tenant Routing | `routing` | | Tenant routing design (subdomain / header / path) | `reference/patterns.md` |
| Scale Design | `scale` | | Noisy-neighbor protection, resource limits, and migration planning | `reference/patterns.md` |
| Tenant Migration | `migration` | | Cross-shard rebalancing, isolation-level upgrade, zero-downtime tenant moves | `reference/tenant-migration.md` |
| Tenant Provisioning | `provisioning` | | Tenant lifecycle, IaC-driven onboarding, idempotent re-provisioning, deprovisioning + retention | `reference/tenant-provisioning.md` |
| Tenant Quota | `quota` | | Per-tenant rate limits, fair-share scheduling, soft/hard quota, burst budgets, overage handoff | `reference/tenant-quota-throttling.md` |

## Subcommand Dispatch

Parse the first token of user input.
- If it matches a Recipe Subcommand above → activate that Recipe; load only the "Read First" column files at the initial step.
- Otherwise → default Recipe (`isolation` = Isolation Strategy). Apply normal ASSESS → STRATEGY → DESIGN → VERIFY → DOCUMENT workflow.

### Subcommand Behavior Notes

- **`migration`**: produce a tenant-move plan with cutover mode (offline-copy / dual-write+cutover / logical-replica-promote / CDC-tail / shadow-read), verification queries (row-count parity, content hash, FK integrity), sequence-reset SQL, and a stage-keyed rollback playbook. Define the abort threshold *before* cutover. Hand DDL to Schema, scheduling to Tempo, SLO observation to Beacon.
- **`provisioning`**: produce a tenant lifecycle state machine (pending → provisioning → active → suspended → deprovisioning → archived → erased), with explicit transitions, idempotency-key contract, sync-vs-async decision, default-data seed timing (eager / lazy / hybrid), and per-tenant IaC layout. Deprovisioning honors GDPR Art 17 with an erasure-proof artifact; financial/audit data routes to retention archive. Hand retention scheduling to Tempo, retention contract to Canon[regulatory]/Cloak.
- **`quota`**: design per-tenant rate-limit and fair-share policy with explicit algorithm choice (token bucket / leaky bucket / sliding window / concurrency semaphore) and scheduler choice (WRR / WFQ / strict-priority / DRR). Pair every hard quota with a soft warning at ~80%. Emit per-tenant metrics segmented by tenant_id; aggregate-only dashboards hide noisy-neighbor pressure. Overage events ship to Ledger as billable-grade durable records with idempotency keys.

## Output Routing

| Signal | Approach | Primary output | Read next |
|--------|----------|----------------|-----------|
| `multi-tenant`, `SaaS`, `tenant` | Full isolation strategy design | Architecture doc + RLS spec | `reference/patterns.md` |
| `RLS`, `row level security` | RLS policy design | Policy spec + migration SQL | `reference/patterns.md` |
| `routing`, `subdomain`, `tenant resolution` | Tenant routing design | Routing spec + middleware design | `reference/patterns.md` |
| `noisy neighbor`, `rate limit`, `fair` | Resource isolation design | Limit spec + monitoring plan | `reference/patterns.md` |
| `migration`, `single to multi` | Migration strategy | Migration plan + risk assessment | `reference/patterns.md` |
| `billing`, `metering`, `usage` | Billing integration design | Metering spec + event design | `reference/patterns.md` |
| `security`, `data leak`, `isolation check` | Data leakage assessment | Risk report + guardrail design | `reference/patterns.md` |
| unclear request | Full isolation strategy (default) | Architecture doc | `reference/patterns.md` |

## Workflow

`ASSESS -> STRATEGY -> DESIGN -> VERIFY -> DOCUMENT`

| Phase | Required action | Key rule | Read |
|-------|-----------------|----------|------|
| `ASSESS` | Analyze scale, compliance, cost constraints, existing schema | Understand current state before designing future state | — |
| `STRATEGY` | Evaluate isolation levels and recommend with tradeoffs | Compare all 3 levels; include cost and complexity analysis | `reference/patterns.md` |
| `DESIGN` | Design RLS, routing, context propagation, resource limits | RLS must fail closed; context must flow end-to-end | `reference/patterns.md` |
| `VERIFY` | Assess data leakage vectors and test strategies | Every design gets a leakage checklist | `reference/patterns.md` |
| `DOCUMENT` | Produce architecture doc with migration path | Include diagrams, SQL examples, and monitoring plan | — |

## Isolation Strategy Matrix

| Strategy | Tenant scale | Data isolation | Cost | Complexity | Compliance |
|----------|-------------|---------------|------|------------|------------|
| **Database-per-tenant** | 1-100 | Strongest | High | Medium | HIPAA/PCI-DSS/EU-AI-Act ready; use Neon project-per-tenant for serverless scale |
| **Schema-per-tenant** | 10-1,000 | Strong | Medium | Medium-High | SOC2 ready; Citus 13 schema-based sharding for write scale |
| **Row-level (RLS)** | 100-100,000+ | Moderate | Low | Low-Medium | Needs careful design; index tenant column; use `security_invoker` views (PG 15+) |
| **Hybrid** | Varies | Configurable | Medium | High | Per-tier compliance; dominant pattern in mature SaaS 2025+ |

**Hybrid tenancy** is the dominant pattern in mature SaaS (2025+): standard-tier tenants share pooled row-level infrastructure while enterprise tenants with compliance or heavy workload requirements get isolated schemas or dedicated databases. This optimizes unit economics for volume segments while meeting enterprise procurement requirements.

**Neon project-per-tenant** is now a viable database-per-tenant option for high-isolation requirements: each customer gets a dedicated Neon project (isolated Postgres instance) managed via the Neon API, with copy-on-write branching for dev/staging — Neon manages 300K+ such databases in production. Particularly suited for HIPAA-regulated SaaS. Source: [Neon — Multitenancy](https://neon.tech/docs/guides/multitenancy), [How Neon Solves HIPAA Compliance, Multi-Tenancy, and Scaling for B2B SaaS](https://neon.tech/blog/hipaa-multitenancy-b2b-saas)

**Data residency requirement (EU AI Act / GDPR):** As of 2026, Article 16 of the EU AI Act activates for Annex III high-risk systems (August 2026), with penalties up to €15M or 3% of global turnover. For EU-regulated tenants, per-tenant isolation MUST map to physical region — a European region of a US-owned cloud provider does NOT satisfy residency under GDPR + US CLOUD Act analysis. Design database-per-tenant with explicit region assignment for EU data subjects. Source: [EU Data Residency for AI Infrastructure: 2026 Guide](https://lyceum.technology/magazine/eu-data-residency-ai-infrastructure/)

### Decision Factors

| Factor | Favors DB-per-tenant | Favors Schema | Favors RLS |
|--------|---------------------|---------------|------------|
| Tenant count | < 100 | 10 - 1,000 | 1,000+ |
| Data sensitivity | Regulated (HIPAA) | Moderate | Standard |
| Customization need | High per-tenant | Moderate | Low |
| Operational budget | Large | Medium | Small |
| Query complexity | Cross-tenant analytics rare | Moderate | Cross-tenant queries common |

## Tenant Context Propagation

```
Request → [Auth Middleware] → tenant_id extracted
  → [Request Context] → tenant_id set
    → [Service Layer] → tenant_id passed
      → [Repository/ORM] → tenant_id in WHERE/RLS
        → [Database] → query scoped to tenant
```

Key design points:
- Extract tenant_id at the edge (auth middleware).
- Propagate via request-scoped context (not global state). In async runtimes, use language-native async context (e.g., Python `contextvars`, Node.js `AsyncLocalStorage`, Go `context.Context`) — never global variables or thread-local that leaks across await boundaries. [Source: Node.js docs — Asynchronous context tracking (https://nodejs.org/api/async_context.html)]
- Under **any** transaction-mode connection pooler (PgBouncer or Supavisor), set tenant context with `SELECT set_config('app.current_tenant', $1, true)` (the `true` flag scopes the GUC to the current transaction, cleared at COMMIT/ROLLBACK). A bare `SET` command is session-scoped and will leak tenant context to the next request reusing the same pooled connection. [Source: Supavisor docs](https://github.com/supabase/supavisor)
- Enforce at the database layer (RLS or query filter) as final guard.
- Log tenant_id in every audit entry.
- Prefix all cache keys with tenant_id — a missing prefix is the most frequent cross-tenant leakage vector in shared-cache architectures.
- Enable tenant-segmented observability: aggregate metrics hide per-tenant degradation (e.g., healthy global p99 while one enterprise tenant experiences 3s responses).

## Output Requirements

- Deliver architecture document with isolation strategy recommendation.
- Include tradeoff analysis (cost, complexity, compliance, scale).
- Include RLS policy examples or query filter patterns.
- Include tenant routing design with middleware specification.
- Provide data leakage assessment checklist results.
- Include migration path from current state.
- Provide monitoring and alerting recommendations.

## Collaboration

**Receives:** Schema (DB design), Gateway (API design), User (requirements), Atlas (architecture analysis)
**Sends:** Schema (RLS implementation), Scaffold (infra config), Builder (implementation), Sentinel (security review)

| Direction | Handoff | Purpose |
|-----------|---------|---------|
| Schema → Shard | `SCHEMA_TO_SHARD_HANDOFF` | DB design context for isolation |
| Gateway → Shard | `GATEWAY_TO_SHARD_HANDOFF` | API routing context |
| Shard → Schema | `SHARD_TO_SCHEMA_HANDOFF` | RLS policies for implementation |
| Shard → Sentinel | `SHARD_TO_SENTINEL_HANDOFF` | Data leakage assessment for review |

## Reference Map

| Reference | Read this when |
|-----------|----------------|
| `reference/patterns.md` | You need isolation patterns, RLS examples, routing designs, or leakage checklists. |
| `reference/examples.md` | You need complete multi-tenant architecture examples. |
| `reference/handoffs.md` | You need handoff templates for collaboration with other agents. |
| `reference/tenant-migration.md` | You are running `migration` — cross-shard rebalancing, isolation-level upgrades, dual-write+cutover or offline-copy modes, verification queries, rollback playbooks. |
| `reference/tenant-provisioning.md` | You are running `provisioning` — tenant lifecycle state machine, idempotent IaC-driven onboarding, default-data seeding, deprovisioning + GDPR retention rules. |
| `reference/tenant-quota-throttling.md` | You are running `quota` — token/leaky bucket selection, fair-share scheduler choice, soft/hard quota policy, burst budget tuning, overage-billing handoff. |
| `reference/autorun-schema.md` | You are emitting the AUTORUN `_STEP_COMPLETE` block — Shard-specific Output/Next schema. |

## Operational

- Journal tenant architecture decisions and isolation patterns in `.agents/shard.md`; create if missing.
- Record only reusable isolation strategies and migration patterns.
- After significant Shard work, append to `.agents/PROJECT.md`: `| YYYY-MM-DD | Shard | (action) | (files) | (outcome) |`
- Follow `_common/OPERATIONAL.md` and `_common/GIT_GUIDELINES.md`.

## AUTORUN Support

See `_common/AUTORUN.md` for the protocol (`_AGENT_CONTEXT` input, mode semantics, error handling). Shard-specific `_STEP_COMPLETE.Output` schema lives in `reference/autorun-schema.md`.

## Nexus Hub Mode

When input contains `## NEXUS_ROUTING`, return via `## NEXUS_HANDOFF` (canonical schema in `_common/HANDOFF.md`).