Architecture

Supabase has two architectures that must be kept in mind when working in this repo:

1. The Supabase platform — the runtime stack that users install when they self-host or that Supabase, Inc. operates as a cloud service. Most of those services live in other repositories and only appear here as Docker images in docker/docker-compose.yml.
2. The monorepo itself — the apps and packages in this repository, which produce the Studio dashboard, the docs site, the marketing site, and supporting libraries.

The Supabase platform stack

When a project runs (whether on supabase.com or self-hosted), it is a composition of independent services running against a single Postgres database. The dashboard talks to those services through a Kong API gateway.

graph TD
    Client[Client app / SDK]
    Studio[Studio dashboard\napps/studio]
    Kong[Kong API gateway]
    PostgREST[PostgREST\nREST API]
    Auth[GoTrue / Auth\nJWT auth]
    Realtime[Realtime\nElixir WS server]
    Storage[Storage API]
    EdgeRuntime[Edge Runtime\nDeno]
    PgMeta[postgres-meta]
    Postgres[(Postgres + extensions)]
    Logflare[Logflare + Vector]

    Client -->|REST / GraphQL| Kong
    Client -->|WebSocket| Kong
    Studio -->|Mgmt API + pg-meta| Kong
    Kong --> PostgREST
    Kong --> Auth
    Kong --> Realtime
    Kong --> Storage
    Kong --> EdgeRuntime
    Kong --> PgMeta
    PostgREST --> Postgres
    Auth --> Postgres
    Realtime --> Postgres
    Storage --> Postgres
    PgMeta --> Postgres
    EdgeRuntime --> Postgres
    Postgres --> Logflare

The docker/docker-compose.yml file is the canonical, runnable definition of this topology — every box in the diagram has a service entry there. The only piece that is built from source in this repo is Studio itself; the rest are pulled as published Docker images. Image versions are tracked in docker/CHANGELOG.md and docker/versions.md.

Monorepo layout

supabase/
├── apps/
│   ├── studio/         # Next.js dashboard — the main product surface
│   ├── docs/           # Next.js docs site (App Router)
│   ├── www/            # Next.js marketing site
│   ├── design-system/  # Component documentation site
│   ├── ui-library/     # Public component registry
│   ├── learn/          # Course platform (early)
│   └── lite-studio/    # Vite + React Router stripped-down variant
├── packages/
│   ├── ui/             # Shared React component library (Radix + shadcn)
│   ├── ui-patterns/    # Higher-level patterns built on `ui`
│   ├── common/         # Auth, telemetry, feature flags, helpers
│   ├── ai-commands/    # OpenAI/Bedrock prompts and streaming commands
│   ├── pg-meta/        # SQL generators for Postgres schema CRUD
│   ├── api-types/      # OpenAPI-generated platform API types
│   ├── shared-data/    # Static data (docs, examples, navigation)
│   ├── icons/          # Icon registry
│   ├── config/         # Shared runtime config
│   ├── tsconfig/       # Shared TypeScript config
│   ├── eslint-config-supabase/
│   ├── marketing/      # Building blocks for `apps/www`
│   ├── dev-tools/, build-icons/, generator/, pg-meta-cli/...
├── blocks/             # shadcn-style block fixtures
├── docker/             # Self-host docker-compose stack
├── e2e/studio/         # Playwright e2e suite
├── examples/           # Stand-alone example apps
├── i18n/               # Localized snippets
├── scripts/, supabase/, patches/

The workspace is declared in pnpm-workspace.yaml. Cross-package builds and dev tasks are orchestrated by Turborepo via turbo.jsonc.

How Studio talks to the platform

Studio is a Next.js Pages Router app that calls two backends:

1. The Supabase platform / management API — used on the hosted product to manage organizations, projects, billing, branches, etc. Requests originate from React-Query hooks under apps/studio/data/ and use the wrapper in apps/studio/data/fetchers.ts. Generated TypeScript types come from packages/api-types.
2. Per-project Postgres — for table editing, SQL execution, role management, advisors, etc. Studio composes raw SQL with the helpers in packages/pg-meta and sends it through the platform API's "execute SQL" endpoint, or directly when running in self-hosted mode.

graph LR
    subgraph "apps/studio"
      Pages[Pages / components]
      Data[data/* React-Query hooks]
      Fetchers[data/fetchers.ts]
    end
    subgraph "Workspace packages"
      PgMeta[pg-meta\nSQL generators]
      ApiTypes[api-types\nOpenAPI types]
      Common[common\nauth, telemetry, flags]
      UI[ui / ui-patterns / icons]
    end
    Pages --> Data
    Data --> Fetchers
    Data --> PgMeta
    Fetchers --> ApiTypes
    Pages --> UI
    Pages --> Common

Where each app is hosted

App	URL	Hosting
apps/www	supabase.com	Vercel
apps/docs	supabase.com/docs	Vercel
apps/studio	supabase.com/dashboard	Vercel (hosted) and via Docker for self-host
apps/design-system	supabase.com/design-system	Vercel
apps/ui-library	Public component registry site	Vercel

The same apps/studio build is shipped to both the hosted dashboard and the supabase/studio Docker image (built via docker build -f apps/studio/Dockerfile). Auth mode is switched at build time via NEXT_PUBLIC_STUDIO_AUTH_MODE.

Build orchestration

pnpm dev, pnpm lint, pnpm typecheck, and pnpm build are all Turborepo entry points defined in turbo.jsonc. Per-app filtering uses the package name, e.g. pnpm dev:studio, pnpm build:docs. See how-to-contribute/development-workflow.md for the typical loop and how-to-contribute/tooling.md for what the tooling actually does.

Cross-references

• The Studio app: apps/studio
• Self-host docker bundle: deployment
• Shared UI: packages/ui
• Schema generation: packages/pg-meta