# supabase/realtime architecture

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

- Interactive diagram: https://gitdiagram.com/supabase/realtime
- Repository: https://github.com/supabase/realtime

## Overview

##### Project type and purpose
- This is a backend “Realtime” server built in Elixir/Phoenix. It exposes:
- A REST API to manage tenants and extensions
- A WebSocket API (Phoenix Channels) for Broadcast, Presence, and Postgres-CDC events
- It also includes a “demo” Next.js front-end showing how clients consume Broadcast/Presence/CDC.

##### File structure
- Top-level: mix.exs, config/, lib/, priv/, releases (rel/), Docker, CI workflows
- lib/realtime: core OTP application (adapters, CDC, subscription management, rate counters, tenants)
- lib/extensions/postgres_cdc_rls: custom Postgres-CDC + RLS logic
- lib/realtime_web: Phoenix endpoint, controllers (HTTP API), plugs, channels (WebSocket logic), LiveView inspector, telemetry/metrics
- demo/: standalone Next.js/React/TypeScript app using @supabase/realtime-js
- priv/repo + lib/realtime/tenants: multi-tenant migrations, seeds
- deploy/, docker-compose.yml: container/deployment configs

##### README for additional insights
- Confirms the three core features: Broadcast, Presence, Postgres Changes via WAL2JSON CDC
- Describes environment variables, JWT-based tenant auth, cluster/telemetry settings
- Points to “demo” folder as example client

##### Main components and interactions
a. Clients
- WebSocket clients (browser/mobile) using JWT to authenticate
- REST clients for tenant CRUD
- Demo Next.js app (demo/)
b. API Layer (HTTP)
- Phoenix Controllers under realtime_web/controllers
- Exposes `/api/tenants` for tenant management
c. WebSocket Layer
- Phoenix Endpoint (realtime_web/endpoint.ex)
- Channels: Broadcast, Presence, RealtimeChannel (+ authorization plugs)
d. Subscription Manager & CDC Extension
- lib/extensions/postgres_cdc_rls: polls WAL, applies RLS, produces change events
- SubscriptionSupervisor spawns per-tenant pollers
e. Message Dispatcher & PubSub
- Routes inbound client messages + CDC events to channel handlers
- Phoenix.PubSub for fan-out across nodes
f. Multi-tenancy
- Global management DB (`_realtime.tenants`, `_realtime.extensions`)
- Dynamic Supervisors spawn tenant-scoped processes (connections, counters, janitors)
g. Cluster Infrastructure
- gen_rpc for inter-node RPC (metrics collection, process inspection)
- ClusterStrategy (Postgres-based) for node discovery
h. Database(s)
- Global Postgres for tenant metadata
- Tenant Postgres(s)/schemas for CDC and RLS
- Migrations under priv/repo & realtime/tenants/repo
i. Monitoring & Telemetry
- PromEx plugins for channels, gen_rpc, OS metrics, Erlang VM metrics
- Exposes `/metrics` HTTP endpoint

##### Relationships and data flow
- Client → HTTP API: create/read tenants, fetch JWT secrets
- Client → WebSocket: connect to `/socket`, authenticate via JWT
- WebSocket → join channels → subscription manager → start CDC poller
- CDC poller → WAL JSON events → subscription manager → Phoenix.PubSub → client channel
- Client events (broadcast/presence) → channel handlers → MessageDispatcher → PubSub → peers
- Node-to-node (gen_rpc) → forward cluster metrics, sync processes
- Phoenix → Ecto Repo → Postgres for metadata + RLS enforcement

##### Architectural patterns and design principles
- OTP Supervision Tree with dynamic supervisors per tenant
- Adapter pattern for supporting multiple CDC protocols
- MVC for HTTP, Channels for WebSocket
- PubSub for decoupled message broadcast
- Row-Level Security in Postgres for channel authorization
- Layered: API → Business Logic → Adapters → Database
- Multi-tenant isolation via separate DB connections/schemas

##### Final checklist
- Component labels
- Detailed enough to show API layer, WebSocket layer, CDC adapter, multi-tenant supervisors, cluster bus, databases, and monitoring

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients & Demo
    subgraph "Clients & Demo Frontend" 
        direction TB
        Demo["Demo Next.js App"]:::clients
    end

    %% API & WebSocket Layer
    subgraph "API/WebSocket Layer" 
        direction TB
        HTTP_API["HTTP API (Phoenix Controllers)"]:::web
        Endpoint["Phoenix Endpoint"]:::web
        subgraph "WebSocket Channels"
            direction TB
            UserSocket["UserSocket Definition"]:::web
            RealtimeChannel["Realtime Channel & Handlers"]:::web
            PresenceChannel["Presence Channel"]:::web
        end
        subgraph "Channel Auth Plugs"
            direction TB
            JWTPlug["JWT Verification Plug"]:::web
            AuthzPlug["Channels Authorization Plug"]:::web
        end
    end

    %% Core Business Logic & Adapters
    subgraph "Core Business Logic & Adapters" 
        direction TB
        CDC_Ext["CDC Extension Entry"]:::core
        Poller["Replication Poller"]:::core
        SubManager["Subscription Manager"]:::core
        CDCDispatcher["Message Dispatcher (CDC)"]:::core
        ChannelDispatcher["Message Dispatcher (Channel)"]:::core
    end

    %% Multi-Tenancy Supervisor
    subgraph "Multi-Tenancy Core" 
        direction TB
        TenantMgmt["Tenant Management & Processes"]:::core
        TenantConnect["Tenant Connect & Supervision"]:::core
        TenantJanitor["Tenant Janitor Tasks"]:::core
        TenantMigrations["Tenant DB Migrations"]:::core
    end

    %% Databases
    subgraph "Databases" 
        direction TB
        GlobalDB["Global Metadata DB"]:::db
        TenantDB["Tenant Postgres/Schema"]:::db
    end

    %% Cluster Infrastructure
    subgraph "Cluster Infrastructure" 
        direction TB
        GenRPC["gen_rpc & RPC Routing"]:::cluster
        ClusterStrat["Postgres-based Cluster Strategy"]:::cluster
    end

    %% Monitoring & Telemetry
    subgraph "Monitoring & Telemetry" 
        direction TB
        OSMetrics["OS & VM Metrics"]:::monitor
        PromEx["PromEx Plugins"]:::monitor
        Telemetry["Phoenix Telemetry"]:::monitor
        MetricsAPI["Metrics HTTP Endpoint"]:::monitor
    end

    %% Rate Limiting & Counters
    subgraph "Rate Limiting & Counters"
        direction TB
        GenCounter["Gen Counter Supervisor"]:::core
        RateCounter["Rate Counters"]:::core
    end

    %% Plugs & Middleware
    subgraph "Plug-based Middleware"
        direction TB
        AssignTenant["Tenant Assignment Plug"]:::web
        AuthTenant["Tenant Auth Plug"]:::web
        RateLimiter["Rate Limiter Plug"]:::web
        ReqID["Request ID Plug"]:::web
    end

    %% Flows
    Demo -->|HTTP API Calls| HTTP_API
    Demo -->|WebSocket Connect| Endpoint
    HTTP_API -->|Ecto Repo| GlobalDB
    Endpoint -->|socket upgrade| UserSocket
    UserSocket -->|join channel| RealtimeChannel
    UserSocket -->|join presence| PresenceChannel
    PresenceChannel -->|uses| ChannelDispatcher
    RealtimeChannel -->|uses| ChannelDispatcher
    RealtimeChannel -->|auth via| JWTPlug
    RealtimeChannel -->|authz via| AuthzPlug
    Endpoint -->|uses plugs| AssignTenant
    Endpoint -->|uses plugs| AuthTenant
    Endpoint -->|uses plugs| RateLimiter
    Endpoint -->|uses plugs| ReqID

    RealtimeChannel -->|subscribe| SubManager
    SubManager -->|start poller| Poller
    Poller -->|read WAL JSON| CDC_Ext
    CDC_Ext -->|emit events| CDCDispatcher
    CDCDispatcher -->|PubSub publish| PhoenixPubSub
    ChannelDispatcher -->|PubSub publish| PhoenixPubSub
    PhoenixPubSub[(Phoenix.PubSub)]:::core
    PhoenixPubSub -->|fan-out| RealtimeChannel

    GlobalDB -->|tenant meta| TenantMgmt
    TenantMgmt --> TenantConnect
    TenantConnect --> TenantJanitor
    TenantMgmt --> TenantMigrations

    TenantConnect -->|DB connections| TenantDB
    TenantDB -->|RLS enforced| Poller

    GenRPC -->|inter-node RPC| ClusterStrat
    ClusterStrat --> GenRPC

    OSMetrics -->|collect| GenRPC
    PromEx -->|plugins| OSMetrics
    Telemetry -->|expose| MetricsAPI
    MetricsAPI -->|HTTP| Demo

    GenCounter -->|track| RealtimeChannel
    RateCounter -->|throttle| RealtimeChannel

    %% Click Events
    click Demo "https://github.com/supabase/realtime/tree/main/demo/"
    click HTTP_API "https://github.com/supabase/realtime/tree/main/lib/realtime_web/controllers/"
    click Endpoint "https://github.com/supabase/realtime/blob/main/lib/realtime_web/endpoint.ex"
    click UserSocket "https://github.com/supabase/realtime/blob/main/lib/realtime_web/channels/user_socket.ex"
    click RealtimeChannel "https://github.com/supabase/realtime/tree/main/lib/realtime_web/channels/realtime_channel/"
    click PresenceChannel "https://github.com/supabase/realtime/blob/main/lib/realtime_web/channels/presence.ex"
    click JWTPlug "https://github.com/supabase/realtime/blob/main/lib/realtime_web/channels/auth/jwt_verification.ex"
    click AuthzPlug "https://github.com/supabase/realtime/blob/main/lib/realtime_web/channels/auth/channels_authorization.ex"
    click CDC_Ext "https://github.com/supabase/realtime/blob/main/lib/extensions/postgres_cdc_rls/cdc_rls.ex"
    click Poller "https://github.com/supabase/realtime/blob/main/lib/extensions/postgres_cdc_rls/replication_poller.ex"
    click SubManager "https://github.com/supabase/realtime/blob/main/lib/extensions/postgres_cdc_rls/subscription_manager.ex"
    click CDCDispatcher "https://github.com/supabase/realtime/blob/main/lib/extensions/postgres_cdc_rls/message_dispatcher.ex"
    click ChannelDispatcher "https://github.com/supabase/realtime/blob/main/lib/realtime_web/channels/realtime_channel/message_dispatcher.ex"
    click TenantMgmt "https://github.com/supabase/realtime/tree/main/lib/realtime/tenants/"
    click TenantConnect "https://github.com/supabase/realtime/tree/main/lib/realtime/tenants/connect/"
    click TenantJanitor "https://github.com/supabase/realtime/tree/main/lib/realtime/tenants/janitor/"
    click TenantMigrations "https://github.com/supabase/realtime/tree/main/lib/realtime/tenants/repo/migrations/"
    click GlobalDB "https://github.com/supabase/realtime/tree/main/priv/repo/"
    click ClusterStrat "https://github.com/supabase/realtime/blob/main/lib/realtime/cluster_strategy/postgres.ex"
    click GenRPC "https://github.com/supabase/realtime/blob/main/lib/realtime/gen_rpc.ex"
    click RateCounter "https://github.com/supabase/realtime/tree/main/lib/realtime/rate_counter/"
    click GenCounter "https://github.com/supabase/realtime/tree/main/lib/realtime/gen_counter/"
    click Telemetry "https://github.com/supabase/realtime/blob/main/lib/realtime_web/telemetry.ex"
    click MetricsAPI "https://github.com/supabase/realtime/blob/main/lib/realtime_web/controllers/metrics_controller.ex"

    %% Styles
    classDef clients fill:#D0E8FF,stroke:#4A90E2,color:#000
    classDef web fill:#E6FFDC,stroke:#4CAF50,color:#000
    classDef core fill:#FFE2B5,stroke:#F5A623,color:#000
    classDef db fill:#F2F2F2,stroke:#888,color:#000
    classDef cluster fill:#F3E5F5,stroke:#9C27B0,color:#000
    classDef monitor fill:#E8EAF6,stroke:#3F51B5,color:#000
```
