saas-architecture-advisor

Getting Started

1. Install the skill using the command above
2. Open your AI coding agent (Claude Code, Codex, Gemini CLI, or Cursor)
3. Reference the skill in your prompt
4. The AI will use the skill's capabilities automatically

Example Prompts

• "Review the open pull requests and summarize what needs attention"
• "Generate a changelog from the last 20 commits on the main branch"

Overview

This skill helps teams design and implement multi-tenant SaaS architectures by evaluating isolation strategies, generating tenant routing patterns, and recommending the right tradeoffs based on scale, compliance requirements, and budget constraints.

Instructions

Step 1: Gather Context

Before recommending anything, establish:

• Scale: Expected tenant count (year 1 and year 3)
• Tenant size: Users per tenant (range and distribution)
• Compliance: SOC2, HIPAA, GDPR, or contractual isolation requirements
• Stack: Database, language, framework, hosting
• Budget: Monthly infrastructure budget
• Data sensitivity: What kind of data tenants store
• Customization needs: Do tenants need custom fields, workflows, or branding?

Step 2: Evaluate Tenancy Models

Present trade-offs for these models:

Shared Everything (single DB, shared tables, tenant_id column):

• Best for: <1,000 tenants, uniform data model, no strict isolation requirements
• Cost: Lowest ($1 DB serves all tenants)
• Risk: Query bugs can leak data; noisy neighbor issues
• Mitigation: Row-level security (PostgreSQL RLS), application-layer checks

Schema per Tenant (single DB, separate schemas):

• Best for: 50-500 tenants, moderate isolation needs
• Cost: Low (single DB instance, logical separation)
• Risk: Migration complexity scales with tenant count; catalog bloat
• Mitigation: Automated migration tooling, connection pooling with schema switching

Database per Tenant (dedicated DB per tenant):

• Best for: <100 tenants, strict compliance, large enterprise clients
• Cost: Highest ($274+/mo per tenant on RDS)
• Risk: Operational overhead managing N databases
• Mitigation: Infrastructure-as-code templates, centralized monitoring

Hybrid (shared for standard, dedicated for enterprise):

• Best for: Mixed tenant base with some requiring isolation
• Cost: Moderate (shared DB + N dedicated for premium)
• Trade-off: Two code paths, but repository pattern abstracts them

Step 3: Design Tenant Routing

Recommend routing strategy based on the application type:

• Subdomain routing: tenant.app.com — best for B2B SaaS
• Path routing: app.com/tenant/ — simpler SSL, good for internal tools
• Header routing: X-Tenant-ID — API-first products
• JWT claim: tenant_id in token — serverless/stateless architectures

Step 4: Address Cross-Cutting Concerns

For each recommendation, cover:

• Rate limiting: Per-tenant to prevent noisy neighbors
• Billing metering: How to track usage per tenant
• Background jobs: Tenant context propagation to workers/queues
• Caching: Tenant-namespaced cache keys
• Search: Filtered indices or per-tenant indices
• Audit logging: Tenant-scoped audit trails

Step 5: Generate Implementation Artifacts

Produce:

• Database schema with tenant isolation mechanisms
• Middleware/interceptor code for tenant context
• Repository pattern that abstracts tenancy
• Tenant provisioning/deprovisioning scripts
• Migration strategy for existing single-tenant apps

Examples

Example 1: Early-Stage SaaS

User prompt:

We have 30 tenants and expect 200 in a year. PostgreSQL, no compliance needs yet. What tenancy model?

Agent output:

Recommendation: Shared database with RLS

At 200 tenants with no compliance requirements, a single PostgreSQL database
with row-level security gives you the best simplicity-to-isolation ratio.

Implementation:
1. Add tenant_id UUID column to all tenant-scoped tables
2. Enable RLS: ALTER TABLE <table> ENABLE ROW LEVEL SECURITY;
3. Create policies: USING (tenant_id = current_setting('app.tenant_id')::UUID)
4. Set tenant context per request in middleware via SET LOCAL

Cost: Single db.t3.medium handles this easily at ~$50/month.
Migration path: If you later need dedicated DBs for enterprise clients,
the repository pattern lets you route specific tenants without changing app code.

Example 2: Healthcare SaaS Requiring HIPAA

User prompt:

Building a patient records SaaS. 50 clinic tenants, HIPAA required. Budget: $5k/month infra.

Agent output:

Recommendation: Database per tenant

HIPAA requires demonstrable data isolation. At 50 tenants, per-tenant databases
are operationally feasible and satisfy compliance auditors.

Architecture:
- Tenant registry DB (shared): Stores tenant metadata + routing config
- Per-tenant RDS instances: db.t3.medium ($50/mo each) = $2,500/mo for 50
- Connection routing: Middleware resolves tenant → connection string from registry
- Encryption: RDS encryption at rest + tenant-specific KMS keys

Budget fit: $2,500 for DBs + $1,000 compute + $500 other = $4,000/mo ✅

Key HIPAA controls addressed:
- Physical data isolation (separate DB instances)
- Per-tenant encryption keys (KMS)
- Tenant-scoped audit logs
- Independent backup/restore per tenant

Guidelines

• No one-size-fits-all — always evaluate against the specific context before recommending
• Start simple, migrate up — recommend the simplest model that meets requirements; overengineering multi-tenancy is expensive
• RLS is not optional for shared databases — application-layer filtering alone is insufficient; one missed WHERE clause = data breach
• Test tenant isolation — always recommend integration tests that verify queries cannot access other tenants' data
• Plan for the migration path — even if starting with shared DB, design the data access layer so switching to dedicated DBs later is feasible
• Background jobs are the blind spot — tenant context often gets lost in async flows; always address this explicitly