The Supabase architecture on one page: gateway, services, Postgres
By Christophe Paka · Facts checked on 23 October 2026
A reader on r/CloudFlare could not get a stable database connection from Cloudflare Workers. Others ask which pooler to use, and which port. A log names PostgREST, a guide names GoTrue, and the Dashboard calls itself Studio on your laptop.
Behind all of these questions sits one gap: no map of the Supabase architecture. Without it, each error looks like its own mystery, and you fix the wrong part.
The figure below is that map. Follow one path, left to right: the callers, the front door, the services, then Postgres. Each box gets a plain name below. If an AI tool built your app, two things matter most: the key your browser sends, and Postgres, where your access rules live. You can skip the side lane and its ports.
How to read this figure
Start with the three callers on the left. The browser and the mobile app send the publishable key, a public key that names your project, plus the user's JWT, a signed digital pass that says who the user is. Your server sends the secret key, or speaks SQL directly. The note "apikey header" just means the key rides along on every call. Your keys sit in the Dashboard, under Settings > API Keys.
Pass through Envoy, the one front door. Envoy is the API gateway: one front door for every request. It checks the key on each request, then sends the request to the right service. A call from a browser never skips this door.
Read the services by what they do. Each box is one program with one job. GoTrue signs users in and hands out their JWT. PostgREST, the Data API, turns your tables into web addresses your app can read. Realtime pushes changes to open screens. Storage API keeps files. Edge Runtime runs your own server code. pg_graphql stays off until you turn it on, and postgres-meta only serves the Dashboard, so most apps never meet those two.
End in the Postgres box on the right. Each project gets one dedicated database. It holds your tables, plus add ons called extensions, such as pgvector for search by meaning. Every request runs as a role, the database identity it acts as: anon for a stranger, authenticated for a signed in user. A grant lets a role use a table at all. Then RLS, Row Level Security, picks which rows it sees. Both live here, not in a service.
Take the side lane at the bottom. Only servers that speak SQL use this lane; browsers never do. An app from Lovable calls from the browser, so it never takes this lane. Servers skip the gateway and go through Supavisor, the connection pooler, which lets many short visits share a few database connections. Each kind of server has its own port number: see the FAQ.
Key takeaways
- When something fails, find its box on the map first: caller, gateway, service or Postgres.
- Check access in Postgres: a grant opens each table, and an RLS policy picks its rows.
- Connect serverless code through the pooler on port 6543, and long running servers on 5432.
Worked example: one request for Ana's to dos
Crystal Desk is the small team app the book builds. Its todos table holds 7 rows: 4 for Ana and 3 for Ben. Ana opens the app in her browser.
- The browser sends
GET /rest/v1/todoswith the publishable key and Ana's JWT. - Envoy checks the key and routes the request to PostgREST, the Data API.
- PostgREST reads the JWT and switches to the role authenticated for this one request.
- Postgres checks the grant on todos, then runs the policy "each user sees their own rows" on every row.
- One SQL statement runs, and PostgREST sends the rows back to the browser as JSON.
Result: Ana gets her 4 rows, never Ben's 3. No service in the middle made that choice: Postgres did. To see the four checks one by one, read the access chain.
Questions readers ask
What is the difference between Studio and the Supabase dashboard?
They are the same thing. The Dashboard is the Supabase web page where you manage a project in the browser. Its open source name is Studio, the name you see when you run Supabase on your own machine. A self hosted stack runs Studio too, showing one project.
Is Supabase just Postgres?
Postgres is the center, one dedicated database per project. Around it run separate programs: GoTrue for sign in, PostgREST for the Data API, Realtime, Storage, the Edge Runtime and more. Each one reads and writes that same database, so your data and your access rules live in one place.
Which port should my server use, 5432 or 6543?
Serverless code, such as Cloudflare Workers, connects through the pooler in transaction mode on 6543. In that mode, turn off prepared statements in your database library. Long running servers and schema tools use session mode or a direct connection on 5432. Browsers use neither: they call the Data API.
Which services do I run if I self host Supabase?
The same ones on this map. A tool called Docker Compose starts them all from one file, and Envoy is the front door there too. The docs ask for a server with at least 2 cores and 4 GB of memory. Managed backups and branching do not come along, so a nightly backup becomes your job.
Sources: Architecture (Supabase docs); Securing your API (Supabase docs).
This figure is from Supabase Made Crystal Clear, chapter 2.
The chapter builds the idea step by step, with recipes you can follow, a Try it to check yourself, and every source.
Get the book
