How Supabase Works
Supabase is often called "the open-source Firebase," but the architecture is fundamentally different. Where Firebase is a proprietary document database, Supabase is a collection of open-source tools assembled around PostgreSQL — and Postgres does the heavy lifting.
What supabase Does
Builds and deploys a PostgreSQL-based development platform with database management, authentication, and web interfaces
Supabase is a monorepo containing the complete development stack for a PostgreSQL-based platform that competes with Firebase. It provides multiple web applications (studio dashboard, documentation site, marketing website), shared UI libraries, and supporting tools for managing PostgreSQL databases with authentication, APIs, and file storage. The system is designed as a hosted platform but can also be self-hosted.
Architecture Overview
supabase is organized into 4 layers, with 8 components and 0 connections between them.
How Data Flows Through supabase
The system operates as a multi-application platform where the studio app serves as the primary interface for database management, consuming shared UI components and PostgreSQL utilities. Marketing campaigns flow through the www app using scheduled landing pages, while documentation is served through the docs app with interactive components. The AI system in studio aggregates tools based on deployment type (cloud vs self-hosted) and user permissions, then filters them for safe database operations. Build tools process SVG assets into React components and generate type definitions from OpenAPI specifications.
1AI tool aggregation
The getTools function checks deployment type (IS_PLATFORM) and user permissions, then aggregates studio tools with platform-specific tools like MCP and schema tools for cloud deployments, or fallback tools for self-hosted instances
Config: catalog.@supabase/supabase-js
2Tool filtering
filterToolsByOptInLevel removes AI tools that require higher permission levels than the user has opted into, ensuring privacy and security boundaries are respected
3Campaign page routing
The www app uses the static pages array to serve marketing campaign pages, with each GoPageInput containing expiration dates for automatic cleanup of time-limited campaigns
4Component registry lookup
The design system and ui-library registries use lazy loading to serve component demos, mapping component names to their implementations with React.lazy for performance
5Asset compilation
Build tools read SVG files from directories, convert filenames from kebab-case to PascalCase, and generate TypeScript export files for icon components
Config: packages
6Type definition merging
The api-types package combines OpenAPI schemas from both internal API and platform services into unified TypeScript interfaces for type-safe client development
Config: catalog.@types/node, catalog.@types/react
System Dynamics
Beyond the pipeline, supabase has runtime behaviors that shape how it responds to load, failures, and configuration changes.
Data Pools
Component Registry
Maps component names to lazy-loaded React components for the design system showcase
Type: registry
Campaign Pages Store
Static array of marketing campaign configurations with scheduled expiration dates
Type: in-memory
Local Storage
Browser-based persistent storage for user preferences and learning progress
Type: cache
Functions Artifact Store
File system storage for Edge Functions artifacts in self-hosted deployments
Type: file-store
Feedback Loops
AI Permission Filtering
Trigger: User changes AI opt-in level or requests AI assistance → System re-evaluates available tools and filters out those requiring higher permissions (exits when: Filtered tool set matches user's current permission level)
Type: self-correction
Local Storage Sync
Trigger: Component state changes in learning app → useLocalStorage hook serializes new state to browser localStorage (exits when: State successfully persisted or error handled)
Type: cache-invalidation
Control Points
IS_PLATFORM
EDGE_FUNCTIONS_MANAGEMENT_FOLDER
AI Opt-in Level
Catalog Dependencies
Delays
Component Lazy Loading
Duration: Dynamic based on bundle size
Font Loading
Duration: Network dependent
Campaign Expiration
Duration: Based on removal dates in comments
Technology Choices
supabase is built with 7 key technologies. Each serves a specific role in the system.
Key Components
- getTools (orchestrator): Aggregates AI tools from multiple sources (studio, schema, MCP, incidents) and filters them based on user's AI opt-in level and platform type (self-hosted vs cloud)
- filterToolsByOptInLevel (validator): Filters available AI tools based on user's privacy and feature preferences to control which database operations AI can perform
- getFunctionsArtifactStore (factory): Creates a file system-based store for managing Edge Functions artifacts in self-hosted deployments
- generateExportsFile (generator): Processes SVG files to generate TypeScript barrel export files, converting kebab-case filenames to PascalCase component names
- Index (registry): Component registry that maps component names to their lazy-loaded implementations for the design system showcase
- useLocalStorage (adapter): React hook that synchronizes component state with browser localStorage, handling serialization and SSR compatibility
- customFont (loader): Loads and configures custom font files with multiple weights and styles for consistent typography across the platform
- pages (registry): Central registry of all marketing campaign pages with scheduled removal dates for event-driven marketing
Who Should Read This
Developers choosing a backend-as-a-service, or teams evaluating Supabase for their next project.
This analysis was generated by CodeSea from the supabase/supabase source code. For the full interactive visualization — including pipeline graph, architecture diagram, and system behavior map — see the complete analysis.
Explore Further
Full Analysis
Interactive architecture map for supabase
supabase vs appwrite
Side-by-side architecture comparison
Frequently Asked Questions
What is supabase?
Builds and deploys a PostgreSQL-based development platform with database management, authentication, and web interfaces
How does supabase's pipeline work?
supabase processes data through 6 stages: AI tool aggregation, Tool filtering, Campaign page routing, Component registry lookup, Asset compilation, and more. The system operates as a multi-application platform where the studio app serves as the primary interface for database management, consuming shared UI components and PostgreSQL utilities. Marketing campaigns flow through the www app using scheduled landing pages, while documentation is served through the docs app with interactive components. The AI system in studio aggregates tools based on deployment type (cloud vs self-hosted) and user permissions, then filters them for safe database operations. Build tools process SVG assets into React components and generate type definitions from OpenAPI specifications.
What tech stack does supabase use?
supabase is built with TypeScript (Primary language for type-safe development across all applications and libraries), React (UI framework for building all web applications and shared component libraries), Next.js (Full-stack React framework powering the studio app, marketing site, and documentation), pnpm (Package manager with workspace support for managing dependencies across the monorepo), PostgreSQL (Core database technology that the entire platform is built around managing and extending), and 2 more technologies.
How does supabase handle errors and scaling?
supabase uses 2 feedback loops, 4 control points, 4 data pools to manage its runtime behavior. These mechanisms handle error recovery, load distribution, and configuration changes.
How does supabase compare to appwrite?
CodeSea has detailed side-by-side architecture comparisons of supabase with appwrite. These cover tech stack differences, pipeline design, and system behavior.