SaaS Product Development Rules for Windsurf

# SaaS Product Development Rules for Windsurf

# SaaS Product Development Rules

## Multi-tenancy Architecture
- Every database query must be scoped to the current organization/tenant
- Never query across tenant boundaries — add organizationId to every table
- Row-Level Security (RLS) at the database level as the last line of defense
- Tenant context propagated through the request lifecycle, not passed per function
- Subdomain or path-based tenant routing — decide early, it's hard to change

## Auth & Billing (the two hardest parts)
- Auth: use Clerk, Better Auth, or NextAuth — don't roll your own
- Always check subscription status before showing paid features
- Stripe Customer ID stored alongside your user record from day 1
- Webhook handlers must be idempotent — Stripe may send events multiple times
- Store Stripe price IDs and product IDs in environment config — not hardcoded

```typescript
// Always verify webhook signature
const event = stripe.webhooks.constructEvent(
  rawBody,
  request.headers['stripe-signature'],
  process.env.STRIPE_WEBHOOK_SECRET
);
// Then handle idempotently — check if already processed
```

## Feature Flags & Plans
- Gate features by plan, not by role — plans change, roles don't
- Feature flag system from day 1 — even if it's just a config object
- Graceful degradation when limits are hit (show upgrade prompt, don't error)
- Never hardcode plan limits — they'll change and you'll miss one

## Subscription Lifecycle
- Handle: trial → paid → canceled → reactivated → past_due
- Email sequences for: trial ending, payment failed, cancellation
- Dunning logic: retry failed payments before canceling
- Data retention on cancellation — what stays, what gets deleted, when