Supabase Architecture Overview

---

What Makes Supabase Different

Supabase positions itself as "The Open Source Firebase Alternative," but this description doesn't fully capture what makes it unique. While Firebase uses proprietary NoSQL databases, Supabase is built entirely on open-source technologies with PostgreSQL at its core.

---

The Supabase Philosophy

Before diving into technical details, understanding Supabase's design philosophy helps explain many architectural decisions:

1. PostgreSQL First

Everything in Supabase revolves around PostgreSQL. Authentication tables, storage metadata, realtime subscriptions—all use Postgres. This means:

• You get the full power of a mature, 35+ year old database
• Standard SQL knowledge applies directly
• No proprietary query languages to learn
• Easy data export and migration

2. Open Source Everything

Every component of Supabase is open source:

• You can inspect the code
• You can self-host the entire stack
• You're never locked in
• Community contributions improve the platform

3. Existing Tools Over New Inventions

Rather than building everything from scratch, Supabase assembles best-in-class open-source tools:

• PostgreSQL for the database
• PostgREST for automatic REST APIs
• GoTrue for authentication
• Realtime for live updates
• Storage API for file management
• pg_graphql for GraphQL

---

Architecture Diagram

Here's how Supabase components work together:

                         ┌─────────────────────┐
                         │   Your Application  │
                         │  (Frontend Client)  │
                         └──────────┬──────────┘
                                    │
                         HTTPS Requests via SDK
                                    │
                                    ▼
┌───────────────────────────────────────────────────────────────────┐
│                        Supabase API Gateway                       │
│                     (Kong / Custom Gateway)                       │
└───────────────────────────────────────────────────────────────────┘
           │              │              │              │
           ▼              ▼              ▼              ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
    │PostgREST │   │  GoTrue  │   │ Realtime │   │ Storage  │
    │(REST API)│   │  (Auth)  │   │ (WS/CDC) │   │  (S3)    │
    └────┬─────┘   └────┬─────┘   └────┬─────┘   └────┬─────┘
         │              │              │              │
         └──────────────┴──────────────┴──────────────┘
                                │
                                ▼
                    ┌───────────────────────┐
                    │      PostgreSQL       │
                    │    (Your Database)    │
                    │  ┌─────────────────┐  │
                    │  │ auth.users      │  │
                    │  │ storage.objects │  │
                    │  │ public.* (you)  │  │
                    │  └─────────────────┘  │
                    └───────────────────────┘

---

Core Components Explained

1. PostgreSQL Database

The heart of Supabase. Every project gets a dedicated Postgres instance with:

• Full Postgres Features: Joins, views, stored procedures, triggers
• Extensions: PostGIS, pg_vector, pg_cron, and 50+ more
• Multiple Schemas: public (your data), auth (authentication), storage (files)
• Direct Access: Connect with any Postgres client

2. PostgREST (REST API)

PostgREST automatically generates a REST API from your database schema:

GET    /rest/v1/posts           → SELECT * FROM posts
POST   /rest/v1/posts           → INSERT INTO posts
PATCH  /rest/v1/posts?id=eq.1   → UPDATE posts WHERE id = 1
DELETE /rest/v1/posts?id=eq.1   → DELETE FROM posts WHERE id = 1

Features:

• Automatic OpenAPI documentation
• Filtering, sorting, pagination built-in
• Respects PostgreSQL permissions
• Handles relationships and joins

3. GoTrue (Authentication)

GoTrue manages user authentication and issues JWT tokens:

• Email/password authentication
• OAuth providers (Google, GitHub, etc.)
• Magic link (passwordless) login
• Phone authentication
• Multi-factor authentication

When a user logs in, GoTrue:

1. Validates credentials
2. Creates/updates a record in auth.users
3. Issues a JWT token containing user info
4. Returns the token to your application

4. Realtime Server

Enables live data synchronization using:

• Postgres Changes: Listen to database INSERT, UPDATE, DELETE events
• Broadcast: Send messages to connected clients
• Presence: Track who's online

Built on Phoenix (Elixir) for high concurrency.

5. Storage API

S3-compatible object storage with:

• Bucket organization
• RLS policies for access control
• Image transformations
• CDN integration

---

How Components Communicate

Request Flow Example: Reading Data

1. Client calls supabase.from('posts').select('*')
2. SDK adds JWT token to request header
3. API Gateway routes request to PostgREST
4. PostgREST validates JWT, sets Postgres session variables
5. PostgreSQL executes query with RLS policies applied
6. Response flows back through the chain

Request Flow Example: User Login

1. Client calls supabase.auth.signInWithPassword()
2. API Gateway routes to GoTrue
3. GoTrue validates credentials against auth.users
4. GoTrue generates JWT token
5. Client stores token, SDK includes it in future requests

---

The Schema Architecture

Supabase organizes data into schemas:

public Schema

Your application data. This is where you create tables:

CREATE TABLE public.posts (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  title text NOT NULL,
  content text,
  user_id uuid REFERENCES auth.users(id)
);

auth Schema

Managed by GoTrue, contains:

• auth.users - User accounts
• auth.sessions - Active sessions
• auth.refresh_tokens - Token refresh data
• auth.identities - OAuth provider links

storage Schema

Managed by Storage API:

• storage.buckets - Bucket definitions
• storage.objects - File metadata

Other Schemas

• extensions - Postgres extensions
• realtime - Realtime configuration
• supabase_functions - Edge function metadata

---

API Keys and Security

Supabase provides two main API keys:

anon Key (Public)

• Safe to include in frontend code
• Limited permissions by default
• Relies on RLS for security
• Used for unauthenticated requests

service_role Key (Secret)

• Never expose in frontend code
• Bypasses RLS
• Full database access
• Used in secure server environments only

// Frontend: anon key is fine
const supabase = createClient(url, anonKey)

// Backend only: service_role for admin operations
const adminClient = createClient(url, serviceRoleKey)

---

Connection Options

You can connect to Supabase data in multiple ways:

1. REST API (via PostgREST)

Best for: CRUD operations, filtering, pagination

const { data } = await supabase.from('posts').select('*')

2. Realtime Subscriptions

Best for: Live updates, collaborative features

supabase.channel('posts').on('postgres_changes', {
  event: '*',
  schema: 'public',
  table: 'posts'
}, handleChange).subscribe()

3. Direct Postgres Connection

Best for: Migrations, complex queries, admin tools

psql postgresql://user:pass@host:5432/postgres

4. GraphQL (via pg_graphql)

Best for: Frontend frameworks preferring GraphQL

query {
  postsCollection {
    edges { node { id, title } }
  }
}

---

Self-Hosting vs Managed

Supabase can run:

Managed (supabase.com)

• Zero infrastructure management
• Automatic backups
• Managed scaling
• Support included
• Monthly pricing

Self-Hosted

• Full control over infrastructure
• Data sovereignty compliance
• Custom scaling decisions
• Requires DevOps expertise
• Docker-based deployment

---

Key Takeaways

1. Supabase is PostgreSQL-centric: Everything revolves around Postgres
2. Open source stack: No proprietary black boxes
3. Modular architecture: Each component has a specific responsibility
4. Multiple access patterns: REST, Realtime, Direct SQL, GraphQL
5. Security by design: JWT tokens, API keys, RLS integration

---

Next Steps

Understanding this architecture helps you make better decisions about:

• Where to put business logic
• How to structure your data
• When to use which API
• How to debug issues

Next, we'll compare Supabase to Firebase to understand the practical differences.

---

Knowing the architecture isn't just academic—it's the foundation for building secure, efficient applications. When you understand how the pieces fit together, debugging becomes diagnosis rather than guesswork.