supabase-reference-architecture

name	supabase-reference-architecture
description	Implement enterprise Supabase reference architectures — monorepo layout, multi-tenant RLS, microservices with cross-project access, framework integration, edge functions, caching, queue patterns, and audit logging. Use when designing a new Supabase project from scratch, reviewing project structure for production readiness, planning multi-tenant isolation, or establishing team architecture standards. Trigger with phrases like "supabase architecture", "supabase project structure", "supabase monorepo", "supabase multi-tenant", "supabase reference design", "how to organize supabase at scale".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(supabase:*), Grep, Glob
version	1.53.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","supabase","architecture","patterns","multi-tenant","monorepo"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Supabase Reference Architecture

Overview

Production Supabase applications need more than a flat lib/supabase.ts file. This skill covers five enterprise architecture patterns: monorepo with shared types, multi-tenant RLS isolation, microservices with separate Supabase projects, framework integration (Next.js / SvelteKit), and operational patterns (edge functions, caching, queues, audit trails). Each pattern stands alone — pick the ones that match your scale.

For the full monorepo directory layout and microservices cross-project access, see Project Structure. For edge functions, caching, queue, and audit trail patterns, see Operational Patterns.

Prerequisites

• @supabase/supabase-js v2+ installed (npm install @supabase/supabase-js)
• Supabase CLI installed (npm install -g supabase)
• A Supabase project at supabase.com/dashboard
• Familiarity with supabase-install-auth (project URL, anon key, service role key)
• PostgreSQL basics (RLS policies, triggers, functions)

Instructions

Step 1: Client Singleton — The Foundation

Every app in the monorepo imports from a shared package instead of creating its own client. This guarantees a single source of truth for the URL, keys, and type definitions.

// packages/supabase/src/client.ts
import { createClient, SupabaseClient } from '@supabase/supabase-js'
import type { Database } from './database.types'

let client: SupabaseClient<Database> | null = null

export function getSupabaseClient(): SupabaseClient<Database> {
   (!client) {
     url = process.. ?? process..
     key = process.. ?? process..
     (!url || !key) {
        ()
    }
    client = createClient<>(url, key)
  }
   client
}


  ():  {
  client = 
}