saas

---
name: saas
description: Production SaaS core engine architecture covering B2B multi-tenancy, organization management, RBAC/ABAC permissions, payment billing engines (Stripe, Lemon Squeezy, Paddle, Polar), usage metering, admin backoffice, user impersonation, webhooks, and API key management.
license: MIT
---

# SaaS Engine & Multi-Tenancy Skill

Architect and build real-world B2B and B2C Software-as-a-Service (SaaS) applications. Implement robust multi-tenancy, flexible subscription billing, organizational RBAC, usage-based metering, admin backoffices, and developer platform features.

## Core Rules

1. **Strict Multi-Tenant Data Isolation**: Every database table containing tenant data must enforce `organization_id` column scopes and Row-Level Security (RLS) or repository-level tenant boundaries.
2. **Idempotent Webhook Processing**: Payment gateway webhooks (Stripe, Paddle, Lemon Squeezy) must process idempotently. Store processed webhook event IDs in the database before mutating subscription states.
3. **Graceful Quota Enforcement**: Metered features must evaluate usage limits server-side before execution (`402 Payment Required` or `429 Limit Exceeded` when quotas are depleted).
4. **Audit Logging for Enterprise Actions**: Record immutable audit logs for all security-sensitive organization events (role changes, member invites, billing updates, API key creation).

---

## 1. Initial Requirements Discovery

When building a SaaS engine, clarify missing parameters across these core domains:

### Multi-Tenancy & Org Hierarchy
- Is the application B2B (Organization -> Team -> User) or B2C (User-centric)?
- What tenant isolation model applies? (Shared Database with Discriminator `organization_id` Column, Schema-per-Tenant, or Isolated DB per Tenant).
- What member invite workflow is required? (Email token invites, domain auto-join `@company.com`).

### Role-Based & Attribute Access Control (RBAC / ABAC)
- What default organization roles apply? (`Owner`, `Admin`, `Member`, `BillingManager`, `Viewer`).
- Can enterprise customers define custom RBAC permissions?

### Monetization & Billing Engine
- Which payment gateway processes subscriptions? (Stripe Billing, Lemon Squeezy, Paddle, Polar, Adyen).
- What pricing models apply? (Tiered monthly/annual subscriptions, Usage-based per-unit metering, Seat-based pricing, Freemium with free trial).
- Is dunning management (failed payment email sequences and grace periods) enabled?

### Developer Platform & Extensions
- Does the SaaS expose public developer API keys? (Format: `sk_live_...` hashed via SHA-256).
- Does the platform dispatch outbound webhooks to customer endpoints?

---

## 2. Multi-Tenant Database Schema Standard

```
  ┌──────────────────────┐         ┌──────────────────────────┐
  │    Organizations     │ 1 ──── *│   OrganizationMembers    │
  │ ──────────────────── │         │ ──────────────────────── │
  │ id (PK)              │         │ id (PK)                  │
  │ name                 │         │ organization_id (FK)     │
  │ slug                 │         │ user_id (FK)             │
  │ stripe_customer_id   │         │ role (OWNER/ADMIN/MEMBER)│
  └──────────┬───────────┘         └──────────────────────────┘
             │ 1
             │
             │ *
  ┌──────────┴───────────┐         ┌──────────────────────────┐
  │    Subscriptions     │         │        AuditLogs         │
  │ ──────────────────── │         │ ──────────────────────── │
  │ id (PK)              │         │ id (PK)                  │
  │ organization_id (FK) │         │ organization_id (FK)     │
  │ stripe_sub_id        │         │ actor_user_id (FK)       │
  │ status (ACTIVE/PAST) │         │ action (MEMBER_INVITED)  │
  │ current_period_end   │         │ ip_address               │
  └──────────────────────┘         └──────────────────────────┘
```

---

## 3. Integration with Other Skills

- Refer to `skills/security` for API key SHA-256 hashing, session cookie security, and passkey authentication.
- Refer to `skills/backend` for async background processing of webhook payloads via BullMQ queues.
- Refer to `skills/frontend` for admin backoffice tables, member invite modals, and pricing tier cards.