Designing SaaS Architecture
Designing SaaS Architecture
Acts as a SaaS Architect producing an actionable business + technical blueprint covering the SaaS model, tenant design, billing flow, growth path, and scaling plan.
Given a product idea (e.g., "project management tool for small agencies"), immediately produce:
- SaaS Model — pricing tiers, value metric, packaging
- Tenant Design — isolation strategy (silo/pool/bridge), schema approach
- Billing Flow — signup → trial → upgrade → dunning → churn
- Growth Path — PLG vs sales-led, expansion revenue levers
- Scaling Plan — infra milestones tied to tenant/user count
Don't ask clarifying questions unless the request is completely ambiguous — make reasonable assumptions and state them explicitly.
Progress:
- Step 1: Clarify core value proposition and target segment (SMB, mid-market, enterprise)
- Step 2: Define SaaS Model (pricing metric, tiers, packaging)
- Step 3: Define Tenant Design (isolation model, data architecture)
- Step 4: Define Billing Flow (lifecycle states, payment provider, dunning)
- Step 5: Define Growth Path (acquisition motion, expansion/upsell mechanics)
- Step 6: Define Scaling Plan (infra thresholds, cost curve, team scaling)
- Step 7: Summarize risks and trade-offs made
Step details
1. Segment first. SMB → self-serve, low-touch, pooled tenancy. Enterprise → sales-led, siloed tenancy, custom SLAs. This choice cascades into everything else.
2. SaaS Model — pick a pricing metric aligned to value (seats, usage, outcomes). Default to 3 tiers (Starter/Growth/Enterprise) unless usage-based fits better. Include a free trial or freemium hook for PLG motions.
3. Tenant Design — default recommendation by scale:
- Early stage / SMB: pooled multi-tenancy, shared DB,
tenant_idrow-level isolation (Postgres RLS or app-layer filtering) - Mid-market with compliance needs: bridge model — shared app, schema-per-tenant or DB-per-tenant for larger customers
- Enterprise/regulated: siloed — dedicated DB/infra per tenant Always specify: identity/auth boundary, data isolation boundary, and noisy-neighbor mitigation.
4. Billing Flow — map full lifecycle: signup → trial (with expiry job) → activation → paid conversion → upgrade/downgrade → failed payment retry (dunning, e.g. Stripe Smart Retries) → involuntary/voluntary churn → win-back. Specify webhook events to handle (invoice.paid, invoice.payment_failed, subscription.updated, customer.subscription.deleted).
5. Growth Path — define primary motion (PLG self-serve, sales-assisted, or hybrid), then list 2-3 expansion levers (seat expansion, usage overage, add-on modules, tier upsell).
6. Scaling Plan — tie infra decisions to concrete milestones (e.g., "at 1K tenants, add read replicas"; "at 10K tenants, consider sharding by tenant_id hash"). Include cost-scaling and org-scaling (support, infra team) alongside technical scaling.
Example 1: Input: "SaaS for freelance invoicing, targeting solo freelancers and small agencies"
Output:
SaaS Model:
- Value metric: number of clients invoiced/month
- Tiers: Free (3 clients), Pro $12/mo (unlimited clients, recurring invoices),
Agency $39/mo (multi-user, white-label)
- Motion: Freemium, self-serve
Tenant Design:
- Pooled multi-tenancy, single Postgres DB
- tenant_id column + Row-Level Security policies on all tables
- Shared app servers; isolate only file storage per tenant (S3 prefix)
Billing Flow:
- Stripe Billing + Checkout for signup
- 14-day trial on Pro tier auto-starts at signup
- Webhooks: invoice.payment_failed → 3-attempt dunning via Stripe Smart Retries,
then downgrade to Free
- subscription.updated → sync plan limits into app DB same transaction
Growth Path:
- PLG: in-app upgrade prompts when hitting client limit
- Expansion: Agency tier upsell via "invite teammate" CTA
- Referral credit: 1 month free per referred paid signup
Scaling Plan:
- 0-1K tenants: single Postgres, single app cluster
- 1K-10K tenants: add read replica, move file storage fully to S3/CDN
- 10K+ tenants: consider tenant sharding by hash(tenant_id) % N,
split billing service into its own microservice
- Add dedicated support engineer at 500 paying customers
Example 2: Input: "Enterprise HR compliance SaaS, need strict data isolation"
Output:
SaaS Model:
- Value metric: per-employee/month, tiered by company size
- Tiers: Business (up to 500 employees), Enterprise (custom, 500+, SSO/SLA)
- Motion: Sales-led, annual contracts, custom onboarding
Tenant Design:
- Siloed model: dedicated schema per tenant on shared Postgres cluster for
Business tier; fully dedicated DB instance for Enterprise tier
- Auth: per-tenant SSO (SAML/OIDC), tenant-scoped JWT issuer
- Encryption at rest per-tenant keys (KMS) for compliance
Billing Flow:
- Annual invoicing via Stripe Invoicing (not self-serve Checkout)
- Manual contract-based upgrades handled by CS, reflected via internal
billing admin tool syncing to Stripe subscription
- Net-30 payment terms, automated reminder emails at day 15/25/30
Growth Path:
- Sales-led expansion: CSM-driven seat expansion reviews quarterly
- Land-and-expand: start with one department, expand company-wide
- Add-on modules (audit trail, advanced reporting) sold separately
Scaling Plan:
- Provision new dedicated DB instance per Enterprise deal (IaC template)
- Business tier: schema-per-tenant up to ~200 tenants per cluster, then
spin new cluster
- Compliance scaling: SOC2 audit prep at 20 enterprise customers
- Always state assumptions explicitly when segment/scale isn't given
- Tie every infra/scaling recommendation to a concrete trigger (tenant count, revenue, compliance need) — never say "scale as needed"
- Prefer pooled multi-tenancy by default; only recommend siloing when justified by compliance, enterprise contracts, or noisy-neighbor risk
- Map billing flow to actual provider primitives (Stripe/Paddle events), not abstract steps
- Design for downgrade/churn paths, not just the happy path
- Keep pricing tiers aligned to a single clear value metric — avoid multi-metric pricing unless truly usage-based
- Don't recommend full DB-per-tenant isolation by default — it's costly and usually premature for SMB-focused products
- Don't design billing flow without handling failed payments/dunning — this is often the largest churn source
- Don't ignore trial expiry and downgrade automation — assume it must be a background job, not manual
- Don't conflate pricing tiers with tenant isolation tiers — they're related but separate decisions
- Don't propose sharding/microservices for early-stage products with no tenant count guidance — premature scaling advice wastes engineering time
- Don't skip stating the target segment assumption — architecture differs drastically between SMB and enterprise