saas

Files (1)

• SKILL.md

SKILL.md (first lines)

# saas

SaaS state-of-the-art — multi-tenancy, usage-based billing, PLG, AI feature integration, modern observability, compliance, and security for production Software-as-a-Service products.

## Instructions

### Multi-Tenancy

Choose the right isolation model for your use case:

| Model | Description | When to use |
|-------|-------------|-------------|
| **Shared schema** | All tenants share tables; rows tagged with `tenant_id` | Early stage, cost-sensitive, straightforward compliance |
| **Schema-per-tenant** | Separate DB schema per tenant | Medium isolation, easy per-tenant migrations |
| **DB-per-tenant** | Separate database per tenant | Enterprise, strict data residency, high compliance (SOC 2, HIPAA) |
| **Hybrid** | Core data shared; sensitive data siloed | Regulated industries with mixed-tier offerings |

**Rules for shared-schema tenancy:**
- Every query **must** filter by `tenant_id` — enforce via a base repository or ORM middleware, not developer discipline
- Use PostgreSQL **Row-Level Security (RLS)** as a second layer of defence:
  ```sql
  ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
  CREATE POLICY tenant_isolation ON orders
    USING (tenant_id = current_setting('app.current_tenant')::uuid);
  ```
- Index `tenant_id` on every tenant-scoped table
- Write integration tests that assert cross-tenant data isolation
- Scope all object storage paths: `s3://bucket/{tenantId}/uploads/{fileId}`
- Never expose predictable sequential IDs — use UUIDs (v7 for sortability)

### Subscription & Billing

#### Flat-rate subscriptions
- Delegate billing to a provider (Stripe, Paddle, LemonSqueezy) — never implement payment processing in-house
- Store only `customerId` and `subscriptionId` in your DB; never card data
- Sync state via webhooks — treat your DB as an eventually-consistent read replica of the billing provider's truth:
  ```
  customer.subscription.created  → activate plan
  customer.subscription.updated  → upgrade / downgrade / seat change
  customer.subscription.deleted  → cancel + start grace period
  invoice.payment_failed         → dunning: notify → restrict → cancel
  ```
- Use the webhook event `id` as an idempotency key — store it before processing; skip if already seen
- Store raw webhook payloads for audit and replay

#### Usage-based / metered billing (modern default)
- Track usage events as they happen (API calls, seats, tokens consumed, storage GB):
  ```ts
  await stripe.subscriptionItems.createUsageRecord(subscriptionItemId, {
    quantity: tokensUsed,
    timestamp: Math.floor(Date.now() / 1000),
    action: 'increment',
  });
  ```
- Expose a live usage dashboard to customers — surprises on invoice day cause churn
- Implement soft limits (warn at 80%) and hard limits (block at 100%) per billing period
- Consider a free tier + usage-based upsell as a Product-Led Growth (PLG) on-ramp

### Product-Led Growth (PLG)

- **Free tier / freemium** — let users experience value before asking for payment; set limits that make paid plans obviously worthwhile
- **Time-to-value (TTV)** — measure and minimise the time from signup to first meaningful action ("aha moment")
- **In-app upgrade prompts** — surface upgrade CTAs contextually at the moment a plan limit is hit, not in a generic settings page
- **Product-qualified leads (PQL)** — score users by product usage signals (not just demo requests) to route to sales
- **Viral / collaborative features** — invite teammates, share reports, public pages — each action is a distribution channel

### AI Feature Integration

Modern SaaS products are expected to ship AI-native capabilities. Apply these patterns:

**AI assistants and copilots:**
- Use streaming responses (SSE / `ReadableStream`) so users see tokens as they arrive — never make them wait for a full response
- Always make AI output editable — users need to correct, refine, and own the output
- Show confidence signals and cite sources (RAG) to build trust

**Retrieval-Augmented Generation (RAG):**
- Store per-tenant vector embeddings in an isolated namespace (Pinecone, pgvector, Qdrant) — never mix tenant data
- Embed content on write; query on read with cosine similarity
- Chunk documents intelligently (512–1024 tokens with overlap); re-embed when source content changes

**Usage and cost controls:**
- Track LLM token consumption per tenant — bill or rate-limit accordingly
- Cache deterministic prompts (same input → same output) to cut costs
- Use cheaper models for classification/triage; reserve frontier models for generation tasks

**Data privacy:**
- Offer a data-processing addendum (DPA) that explicitly states whether tenant data is used for model training
- Provide an opt-out; enterprise customers will require it

### Feature Flags & Plan Gating

- Gate features at the **service layer** — client-side hiding is UI polish, not security
- Centralise entitlement logic in a single `can(tenant, feature)` helper:
  ```ts
  function can(tenant: Tenant, feature: Feature): boolean {
    return tenant.plan.features.includes(feature);
  }
  ```
- Decouple feature **deployment** from feature **release** using a flag system (LaunchDarkly, Unleash, GrowthBook, or a simple DB-backed table)
- Use flags for: gradual rollouts (% of tenants), beta programs, A/B tests, kill switches

### Onboarding

- **Minimise TTV**: guide users to their first meaningful action in < 5 minutes
- Use a checklist-driven onboarding flow with clear progress indicators
- Pre-populate sample / demo data so the product doesn't feel empty on first use
- Collect the absolute minimum data upfront; defer everything else
- Trigger onboarding emails based on **product events** (not just time): welcome on signup, nudge if they haven't completed step 2 after 24h, celebrate first milestone
- Offer an interactive product tour (not a video) so users learn by doing

### Observability & Operations

**Structured logging** — every log line must include:
```json
{ "level": "info", "msg": "...", "tenantId": "...", "userId": "...", "requestId": "...", "timestamp": "..." }
```

**Distributed tracing with OpenTelemetry:**
- Instrument at the framework level (Next.js `instrumentation.ts`, Express middleware)

From Satcomx00-x00/skills-db, MIT.

More from Satcomx00-x00/skills-db