# rphlmr/drizzle-supabase-rls architecture

> Architecture diagram of the GitHub repository rphlmr/drizzle-supabase-rls, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rphlmr/drizzle-supabase-rls
- Repository: https://github.com/rphlmr/drizzle-supabase-rls

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time chat application built with Next.js 13 (App Router) and React on the frontend, Node.js on the backend, Supabase for authentication and realtime messaging, and Drizzle-ORM for schema management and RLS (Row Level Security) enforcement.
- Users log in via Supabase Auth, create or join chat rooms, and send ephemeral messages in authorized channels guarded by RLS policies.

##### File Structure Overview
- **app/**
- Next.js routes and layouts (login, auth callbacks, protected chat page, global CSS).
- **components/**
- Reusable UI (SubmitButton, SupabaseLogo).
- **utils/supabase/**
- Supabase client setup for browser, server, and middleware.
- **database/**
- Drizzle schema definitions (`schema.ts`), migrations, db/drizzle client factories (`db.ts`, `drizzle.ts`), JWT helper.
- **supabase/**
- Local Supabase config (config.toml, seed.sql) for Docker-based local dev and RLS client creation.
- **middleware.ts**
- Next.js middleware for enforcing auth.
- **Configs**
- next.config.js, tailwind.config.js, tsconfig.json, turbo.json, etc.

##### Key Architectural Patterns
- **Separation of Concerns**
- Frontend (React/Next.js client components) vs. Backend (Next.js server components, API routes, Drizzle ORM).
- **Database as a Service + ORM**
- Supabase provides Auth, Realtime, and Postgres hosting; Drizzle-ORM manages schema, migrations, and wraps Supabase connections to enforce RLS.
- **Event-Driven Real-Time Messaging**
- Supabase Realtime channels with presence and broadcast, scoped per room by RLS.
- **Security Boundary: RLS**
- All protected queries run through `db.rls(...)`, which under the hood sets JWT claims and user role before executing SQL.

##### Main Components
a. **Browser Client**
– Next.js React pages/components
– Supabase JS client for Auth and Realtime (channels)
b. **Next.js Server**
– Server Components & Server Actions (`app/` pages, actions.ts)
– `createDrizzleSupabaseClient` factory → returns `{ admin, client }` Drizzle instances
– Middleware layer enforcing session/cookie auth
c. **Supabase Service**
– Auth (JWT generation, Hooks)
– Realtime (Pub/Sub engine for channels)
– Postgres hosting
d. **PostgreSQL Database**
– Tables: `profiles`, `rooms`, `rooms_users`, plus `realtime.*` tables
– Triggers and functions (e.g., `insert_user()` for `profiles`)
– RLS Policies on tables and external real-time tables
e. **Local Dev Infrastructure**
– Supabase CLI Docker containers
– Config files (`supabase/config.toml`, `supabase/seed.sql`)

##### Relationships and Data Flows
- **User → Browser**: logs in via Supabase Auth UI → receives JWT
- **Browser → Supabase Realtime**: subscribes to channel `room-<topic>` via `supabase.channel(...)`
- **Browser → Next.js Server**: fetches initial data/server actions; sends `/invite`, `sendMessage` via server functions
- **Next.js Server → Drizzle-ORM**:
- `admin` instance for schema setup and `profiles` inserts
- `client.rls` instance for all read/write operations subject to RLS
- **Drizzle-ORM → Postgres**: executes SQL with configured JWT claims and role
- **Postgres → Realtime Engine**: triggers broadcast/presence events to subscribed clients
- **Realtime Engine → Browser**: pushes updates to authorized users only

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Client
    subgraph "Browser Client" 
        direction TB
        Pages["Next.js React Pages & Layouts"]:::frontend
        UI["Reusable UI Components"]:::frontend
        SupaJS["Supabase JS Client (Auth & Realtime)"]:::frontend
    end

    %% Next.js Server
    subgraph "Next.js Server" 
        direction TB
        Middleware["Auth Middleware"]:::backend
        ServerActions["Server Actions & Components"]:::backend
        DrizzleFactory["Drizzle-ORM + Supabase Client Factories"]:::backend
        JWTHelper["JWT Helper for User Claims"]:::backend
    end

    %% Supabase Cloud / Local
    subgraph "Supabase Cloud / Local" 
        direction TB
        AuthService["Supabase Auth Service"]:::supa
        RealtimeService["Supabase Realtime Service"]:::supa
        Postgres[(PostgreSQL Database)]:::db
        RLSNote["RLS Policies Enforced via db.rls"]:::supa
    end

    %% Dev Infrastructure
    subgraph "Local Dev Infrastructure" 
        direction TB
        SupabaseCLI["Supabase CLI Docker"]:::infra
        ConfigSeed["Local Config & Seed Scripts"]:::infra
    end

    %% User Interaction
    User(["User"]):::frontend

    %% Connections
    User -->|"interacts via UI"| Pages
    Pages -->|"uses UI Components"| UI
    Pages -->|"calls Supabase JS Client"| SupaJS
    SupaJS -->|"login & subscribe"| AuthService
    SupaJS -->|"subscribe to channels"| RealtimeService
    Pages -->|"fetch/send via Server Actions"| ServerActions
    ServerActions -->|"enforced by"| Middleware
    ServerActions -->|"invokes"| DrizzleFactory
    DrizzleFactory -->|"admin & rls clients"| JWTHelper
    JWTHelper -->|"sets JWT claims"| DrizzleFactory
    DrizzleFactory -->|"executes SQL"| Postgres
    Postgres -->|"triggers real-time events"| RealtimeService
    RealtimeService -->|"push updates"| SupaJS
    SupabaseCLI -->|"runs supabase locally"| AuthService
    SupabaseCLI -->|"runs supabase locally"| RealtimeService
    ConfigSeed -->|"provides config & seed"| SupabaseCLI

    %% Click Events
    click Pages "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/app/layout.tsx"
    click Pages "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/app/page.tsx"
    click Pages "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/app/login/page.tsx"
    click Pages "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/app/auth/callback/route.ts"
    click Pages "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/app/protected/page.tsx"
    click Pages "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/app/globals.css"
    click UI "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/components/submit-button.tsx"
    click UI "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/components/supabase-logo.tsx"
    click SupaJS "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/utils/supabase/client.ts"
    click ServerActions "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/app/protected/actions.ts"
    click ServerActions "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/app/protected/component.tsx"
    click Middleware "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/middleware.ts"
    click Middleware "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/utils/supabase/middleware.ts"
    click DrizzleFactory "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/database/db.ts"
    click DrizzleFactory "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/database/drizzle.ts"
    click JWTHelper "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/database/jwt.ts"
    click Postgres "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/database/schema.ts"
    click Postgres "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/database/migrations/20241030104544_init.sql"
    click Postgres "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/database/migrations/20241030104629_trigger.sql"
    click ConfigSeed "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/supabase/config.toml"
    click ConfigSeed "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/supabase/seed.sql"
    click SupabaseCLI "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/supabase/config.toml"
    click SupabaseCLI "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/supabase/seed.sql"
    click ConfigSeed "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/next.config.js"
    click ConfigSeed "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/tailwind.config.js"
    click ConfigSeed "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/tsconfig.json"
    click ConfigSeed "https://github.com/rphlmr/drizzle-supabase-rls/blob/main/turbo.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef db fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef supa fill:#E1D5E7,stroke:#333,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#333,stroke-width:1px
```
