How supabase/realtime works
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