SaaS Multi-Tenant Patterns

# SaaS Multi-Tenant Patterns for Google Antigravity

Build scalable multi-tenant SaaS applications with proper data isolation in your Google Antigravity projects.

## Row-Level Security

```sql
CREATE TABLE tenants (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name TEXT NOT NULL,
    slug TEXT UNIQUE NOT NULL,
    plan TEXT NOT NULL DEFAULT 'free',
    settings JSONB DEFAULT '{}'::jsonb,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE tenant_members (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID REFERENCES tenants(id) ON DELETE CASCADE,
    user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
    role TEXT NOT NULL DEFAULT 'member',
    UNIQUE(tenant_id, user_id)
);

ALTER TABLE tenants ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Users can view their tenants" ON tenants
    FOR SELECT USING (id IN (SELECT tenant_id FROM tenant_members WHERE user_id = auth.uid()));
```

## Tenant Context Provider

```typescript
// contexts/TenantContext.tsx
"use client";

import { createContext, useContext, useState, useEffect, useCallback } from "react";
import { createClient } from "@/lib/supabase/client";

interface Tenant {
    id: string;
    name: string;
    slug: string;
    plan: string;
}

interface TenantContextType {
    tenant: Tenant | null;
    tenants: Tenant[];
    loading: boolean;
    switchTenant: (tenantId: string) => Promise<void>;
}

const TenantContext = createContext<TenantContextType | undefined>(undefined);

export function TenantProvider({ children }: { children: React.ReactNode }) {
    const [tenant, setTenant] = useState<Tenant | null>(null);
    const [tenants, setTenants] = useState<Tenant[]>([]);
    const [loading, setLoading] = useState(true);
    const supabase = createClient();

    useEffect(() => {
        async function loadTenants() {
            const { data: { user } } = await supabase.auth.getUser();
            if (!user) { setLoading(false); return; }

            const { data: memberships } = await supabase.from("tenant_members").select("tenant:tenants(*)").eq("user_id", user.id);
            const userTenants = memberships?.map((m) => m.tenant as Tenant) || [];
            setTenants(userTenants);

            const storedId = localStorage.getItem("current_tenant_id");
            const current = userTenants.find((t) => t.id === storedId) || userTenants[0];
            setTenant(current || null);
            setLoading(false);
        }
        loadTenants();
    }, [supabase]);

    const switchTenant = useCallback(async (tenantId: string) => {
        const newTenant = tenants.find((t) => t.id === tenantId);
        if (newTenant) {
            setTenant(newTenant);
            localStorage.setItem("current_tenant_id", tenantId);
        }
    }, [tenants]);

    return (
        <TenantContext.Provider value={{ tenant, tenants, loading, switchTenant }}>
            {children}
        </TenantContext.Provider>
    );
}

export function useTenant() {
    const context = useContext(TenantContext);
    if (!context) throw new Error("useTenant must be used within TenantProvider");
    return context;
}
```

## Tenant-Scoped API Routes

```typescript
// app/api/[tenant]/projects/route.ts
import { NextRequest, NextResponse } from "next/server";
import { createClient } from "@/lib/supabase/server";

export async function GET(request: NextRequest, { params }: { params: { tenant: string } }) {
    const supabase = createClient();
    const { data: { user } } = await supabase.auth.getUser();
    
    if (!user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });

    const { data: membership } = await supabase.from("tenant_members").select("role").eq("user_id", user.id).eq("tenant_id", params.tenant).single();
    if (!membership) return NextResponse.json({ error: "Access denied" }, { status: 403 });

    const { data: projects } = await supabase.from("projects").select("*").eq("tenant_id", params.tenant);
    return NextResponse.json({ projects });
}
```

## Tenant Switcher Component

```typescript
// components/TenantSwitcher.tsx
"use client";

import { useState } from "react";
import { useTenant } from "@/contexts/TenantContext";

export function TenantSwitcher() {
    const { tenant, tenants, switchTenant } = useTenant();
    const [open, setOpen] = useState(false);

    if (!tenant) return null;

    return (
        <div className="tenant-switcher">
            <button onClick={() => setOpen(!open)} className="tenant-button">
                <span>{tenant.name.charAt(0)}</span>
                <span>{tenant.name}</span>
            </button>
            {open && (
                <div className="tenant-dropdown">
                    {tenants.map((t) => (
                        <button key={t.id} onClick={() => { switchTenant(t.id); setOpen(false); }} className={t.id === tenant.id ? "active" : ""}>
                            {t.name}
                        </button>
                    ))}
                </div>
            )}
        </div>
    );
}
```

## Best Practices

1. **Data Isolation**: Use RLS policies to ensure complete data isolation
2. **Slug-Based Routing**: Use tenant slugs in URLs for better UX
3. **Plan Enforcement**: Check tenant plan limits before resource creation
4. **Audit Logging**: Log all tenant-scoped actions for compliance
5. **Subdomain Support**: Consider subdomain-based routing for larger deployments