# supabase/supabase-swift architecture

> Architecture diagram of the GitHub repository supabase/supabase-swift, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supabase/supabase-swift
- Repository: https://github.com/supabase/supabase-swift

## Overview

Supabase Swift is a client SDK whose principal workflow is application code configuring one client, then using its service interfaces to authenticate, query Postgres, subscribe to changes, manage objects, or invoke Edge Functions. The graph preserves these separate domain operations and the shared HTTP transport layer. README establishes the full-client composition; sampled source confirms selected Auth session, Storage request, and Realtime state behavior, so unsampled wiring is not expanded beyond documented capabilities.

Main entry points: [`Sources/Helpers/HTTP/HTTPClient.swift`](https://github.com/supabase/supabase-swift/blob/main/Sources/Helpers/HTTP/HTTPClient.swift) (HTTP Client), [`Sources/Supabase/SupabaseClient.swift`](https://github.com/supabase/supabase-swift/blob/main/Sources/Supabase/SupabaseClient.swift) (Supabase Client), [`Sources/Auth/AuthClient.swift`](https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/AuthClient.swift) (Auth Client), [`Sources/PostgREST/Legacy/PostgrestClient.swift`](https://github.com/supabase/supabase-swift/blob/main/Sources/PostgREST/Legacy/PostgrestClient.swift) (PostgREST Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Entry"]
  node_supabase["Supabase Client"]
end

subgraph group_auth["Authentication"]
  node_authclient["Auth Client<br/>[AuthClient.swift]"]
  node_authapi["Auth API<br/>[APIClient.swift]"]
  node_sessionmanager["Session Manager"]
  node_sessionstorage["Session Storage"]
  node_localstorage["Local Auth Storage"]
  node_keychain["Keychain Storage"]
  node_oauth["OAuth Server"]
  node_passkeys["Passkey Auth"]
end

subgraph group_data["Database And Events"]
  node_postgrest["PostgREST Client"]
  node_querybuilder["Query Builder"]
  node_typedquery["Typed Queries"]
  node_realtime["Realtime Client"]
  node_channel["Realtime Channel"]
  node_channelstate["Channel State"]
end

subgraph group_resources["Storage And Functions"]
  node_storage["Storage Client"]
  node_fileapi["File Operations"]
  node_storageapi["Storage API<br/>[StorageApi.swift]"]
  node_vectors["Vector Storage"]
  node_functions["Functions Client"]
end

subgraph group_transport["Transport"]
  node_http["HTTP Client<br/>[HTTPClient.swift]"]
  node_transportimpl["URLSession Transport"]
end

node_app(("Application"))
node_authservice{{"Supabase Auth Service"}}
node_dbservice{{"Postgres REST Service"}}
node_realtimeservice{{"Realtime Service"}}
node_storageservice{{"Storage Service"}}
node_functionservice{{"Edge Functions"}}

node_app -->|"configures"| node_supabase
node_supabase -->|"exposes"| node_authclient
node_supabase -->|"exposes"| node_postgrest
node_supabase -->|"exposes"| node_realtime
node_supabase -->|"exposes"| node_storage
node_supabase -->|"exposes"| node_functions
node_authclient -->|"requests"| node_authapi
node_authclient -->|"updates"| node_sessionmanager
node_sessionmanager -->|"persists"| node_sessionstorage
node_sessionstorage -->|"reads and writes"| node_localstorage
node_localstorage -.->|"defaults to"| node_keychain
node_authclient -->|"supports OAuth"| node_oauth
node_authclient -->|"supports passkeys"| node_passkeys
node_authapi -->|"sends requests"| node_authservice
node_postgrest -->|"builds queries"| node_querybuilder
node_postgrest -->|"supports typed queries"| node_typedquery
node_postgrest -->|"executes requests"| node_http
node_http -->|"sends REST calls"| node_dbservice
node_realtime -->|"opens channels"| node_channel
node_channel -->|"drives lifecycle"| node_channelstate
node_realtime -->|"exchanges events"| node_realtimeservice
node_storage -->|"provides file operations"| node_fileapi
node_storage -->|"provides vector APIs"| node_vectors
node_fileapi -->|"delegates requests"| node_storageapi
node_vectors -->|"delegates requests"| node_storageapi
node_storageapi -->|"sends requests"| node_http
node_http -->|"sends storage calls"| node_storageservice
node_functions -->|"invokes transport"| node_http
node_http -->|"sends invocations"| node_functionservice
node_http -->|"uses transport"| node_transportimpl

click node_supabase "https://github.com/supabase/supabase-swift/blob/main/Sources/Supabase/SupabaseClient.swift"
click node_authclient "https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/AuthClient.swift"
click node_authapi "https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/Internal/APIClient.swift"
click node_sessionmanager "https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/Internal/SessionManager.swift"
click node_sessionstorage "https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/Internal/SessionStorage.swift"
click node_localstorage "https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/Storage/AuthLocalStorage.swift"
click node_keychain "https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/Storage/KeychainLocalStorage.swift"
click node_oauth "https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/AuthOAuthServer.swift"
click node_passkeys "https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/WebAuthn/AuthClient%2BPasskey.swift"
click node_postgrest "https://github.com/supabase/supabase-swift/blob/main/Sources/PostgREST/Legacy/PostgrestClient.swift"
click node_querybuilder "https://github.com/supabase/supabase-swift/blob/main/Sources/PostgREST/Legacy/PostgrestQueryBuilder.swift"
click node_typedquery "https://github.com/supabase/supabase-swift/blob/main/Sources/PostgREST/Query/PostgrestTypedQuery.swift"
click node_realtime "https://github.com/supabase/supabase-swift/blob/main/Sources/RealtimeV2/RealtimeClientV2.swift"
click node_channel "https://github.com/supabase/supabase-swift/blob/main/Sources/RealtimeV2/RealtimeChannelV2.swift"
click node_channelstate "https://github.com/supabase/supabase-swift/blob/main/Sources/RealtimeV2/ChannelStateManager.swift"
click node_storage "https://github.com/supabase/supabase-swift/blob/main/Sources/Storage/SupabaseStorage.swift"
click node_fileapi "https://github.com/supabase/supabase-swift/blob/main/Sources/Storage/StorageFileApi.swift"
click node_storageapi "https://github.com/supabase/supabase-swift/blob/main/Sources/Storage/StorageApi.swift"
click node_vectors "https://github.com/supabase/supabase-swift/blob/main/Sources/Storage/StorageVectorsClient.swift"
click node_functions "https://github.com/supabase/supabase-swift/blob/main/Sources/Functions/FunctionsClient.swift"
click node_http "https://github.com/supabase/supabase-swift/blob/main/Sources/Helpers/HTTP/HTTPClient.swift"
click node_transportimpl "https://github.com/supabase/supabase-swift/blob/main/Sources/Helpers/HTTP/URLSessionTransport.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_supabase toneBlue
class node_authclient,node_authapi,node_sessionmanager,node_sessionstorage,node_localstorage,node_keychain,node_oauth,node_passkeys,node_dbservice,node_storageservice toneAmber
class node_postgrest,node_querybuilder,node_typedquery,node_realtime,node_channel,node_channelstate toneMint
class node_storage,node_fileapi,node_storageapi,node_vectors,node_functions toneRose
class node_http,node_transportimpl,node_app,node_authservice,node_realtimeservice,node_functionservice toneIndigo
```

## Components

### Client Entry

- [Supabase Client](https://github.com/supabase/supabase-swift/blob/main/Sources/Supabase/SupabaseClient.swift): `Sources/Supabase/SupabaseClient.swift`

### Authentication

- [Auth Client](https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/AuthClient.swift): `Sources/Auth/AuthClient.swift`
- [Auth API](https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/Internal/APIClient.swift): `Sources/Auth/Internal/APIClient.swift`
- [Session Manager](https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/Internal/SessionManager.swift): `Sources/Auth/Internal/SessionManager.swift`
- [Session Storage](https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/Internal/SessionStorage.swift): `Sources/Auth/Internal/SessionStorage.swift`
- [Local Auth Storage](https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/Storage/AuthLocalStorage.swift): `Sources/Auth/Storage/AuthLocalStorage.swift`
- [Keychain Storage](https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/Storage/KeychainLocalStorage.swift): `Sources/Auth/Storage/KeychainLocalStorage.swift`
- [OAuth Server](https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/AuthOAuthServer.swift): `Sources/Auth/AuthOAuthServer.swift`
- [Passkey Auth](https://github.com/supabase/supabase-swift/blob/main/Sources/Auth/WebAuthn/AuthClient%2BPasskey.swift): `Sources/Auth/WebAuthn/AuthClient+Passkey.swift`

### Database And Events

- [PostgREST Client](https://github.com/supabase/supabase-swift/blob/main/Sources/PostgREST/Legacy/PostgrestClient.swift): `Sources/PostgREST/Legacy/PostgrestClient.swift`
- [Query Builder](https://github.com/supabase/supabase-swift/blob/main/Sources/PostgREST/Legacy/PostgrestQueryBuilder.swift): `Sources/PostgREST/Legacy/PostgrestQueryBuilder.swift`
- [Typed Queries](https://github.com/supabase/supabase-swift/blob/main/Sources/PostgREST/Query/PostgrestTypedQuery.swift): `Sources/PostgREST/Query/PostgrestTypedQuery.swift`
- [Realtime Client](https://github.com/supabase/supabase-swift/blob/main/Sources/RealtimeV2/RealtimeClientV2.swift): `Sources/RealtimeV2/RealtimeClientV2.swift`
- [Realtime Channel](https://github.com/supabase/supabase-swift/blob/main/Sources/RealtimeV2/RealtimeChannelV2.swift): `Sources/RealtimeV2/RealtimeChannelV2.swift`
- [Channel State](https://github.com/supabase/supabase-swift/blob/main/Sources/RealtimeV2/ChannelStateManager.swift): `Sources/RealtimeV2/ChannelStateManager.swift`

### Storage And Functions

- [Storage Client](https://github.com/supabase/supabase-swift/blob/main/Sources/Storage/SupabaseStorage.swift): `Sources/Storage/SupabaseStorage.swift`
- [File Operations](https://github.com/supabase/supabase-swift/blob/main/Sources/Storage/StorageFileApi.swift): `Sources/Storage/StorageFileApi.swift`
- [Storage API](https://github.com/supabase/supabase-swift/blob/main/Sources/Storage/StorageApi.swift): `Sources/Storage/StorageApi.swift`
- [Vector Storage](https://github.com/supabase/supabase-swift/blob/main/Sources/Storage/StorageVectorsClient.swift): `Sources/Storage/StorageVectorsClient.swift`
- [Functions Client](https://github.com/supabase/supabase-swift/blob/main/Sources/Functions/FunctionsClient.swift): `Sources/Functions/FunctionsClient.swift`

### Transport

- [HTTP Client](https://github.com/supabase/supabase-swift/blob/main/Sources/Helpers/HTTP/HTTPClient.swift): `Sources/Helpers/HTTP/HTTPClient.swift`
- [URLSession Transport](https://github.com/supabase/supabase-swift/blob/main/Sources/Helpers/HTTP/URLSessionTransport.swift): `Sources/Helpers/HTTP/URLSessionTransport.swift`

### Other components

- **Application**
- **Supabase Auth Service**
- **Postgres REST Service**
- **Realtime Service**
- **Storage Service**
- **Edge Functions**

## Connections

- Application → Supabase Client: configures
- Supabase Client → Auth Client: exposes
- Supabase Client → PostgREST Client: exposes
- Supabase Client → Realtime Client: exposes
- Supabase Client → Storage Client: exposes
- Supabase Client → Functions Client: exposes
- Auth Client → Auth API: requests
- Auth Client → Session Manager: updates
- Session Manager → Session Storage: persists
- Session Storage → Local Auth Storage: reads and writes
- Local Auth Storage → Keychain Storage: defaults to
- Auth Client → OAuth Server: supports OAuth
- Auth Client → Passkey Auth: supports passkeys
- Auth API → Supabase Auth Service: sends requests
- PostgREST Client → Query Builder: builds queries
- PostgREST Client → Typed Queries: supports typed queries
- PostgREST Client → HTTP Client: executes requests
- HTTP Client → Postgres REST Service: sends REST calls
- Realtime Client → Realtime Channel: opens channels
- Realtime Channel → Channel State: drives lifecycle
- Realtime Client → Realtime Service: exchanges events
- Storage Client → File Operations: provides file operations
- Storage Client → Vector Storage: provides vector APIs
- File Operations → Storage API: delegates requests
- Vector Storage → Storage API: delegates requests
- Storage API → HTTP Client: sends requests
- HTTP Client → Storage Service: sends storage calls
- Functions Client → HTTP Client: invokes transport
- HTTP Client → Edge Functions: sends invocations
- HTTP Client → URLSession Transport: uses transport