# androidpoet/supabase-kmp architecture

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

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

## Overview

1. **Repository shape**
This is a Kotlin Multiplatform SDK monorepo for Supabase, organized as a set of publishable Gradle modules rather than a single app. The root build wires together shared Kotlin source, platform-specific implementations, tests, samples, docs, and release automation.

2. **Core foundation layer**
`supabase-core` is the lowest shared dependency. It defines the project-wide result/error model (`SupabaseResult`, `SupabaseError`), typed IDs, filter-building utilities, and common response models. Most higher-level modules depend on this layer for consistent error handling and type safety.

3. **HTTP client and transport boundary**
`supabase-client` is the transport backbone. It wraps Ktor with a `SupabaseClient` abstraction, request interceptors, logging, retry policy, and platform-specific engines for Android/JVM, Apple, Linux/Windows, and Wasm. This module is the main boundary between the SDK and Supabase’s HTTP APIs.

4. **Feature modules sit on top of the client**
`supabase-auth`, `supabase-database`, `supabase-storage`, and `supabase-functions` all build on `supabase-client` plus `supabase-core`. They expose feature-specific client interfaces, factories, path helpers, and typed models while reusing the same transport, result, and serialization conventions.

5. **Authentication and session management**
`supabase-auth` handles email/password, OAuth, MFA, PKCE, native sign-in, and session lifecycle. It includes a `SessionManager` with `StateFlow`-based state, auto-refresh, and pluggable session storage. Persistence is abstracted through `SessionStorage`, with in-memory and key-value implementations; platform apps are expected to bind key-value storage to secure stores.

6. **Platform-native identity providers**
`supabase-auth-google` and `supabase-auth-apple` are optional adapter modules that bridge platform SDKs into a common `NativeAuthProvider` flow. They are intentionally isolated so the core auth module does not depend on Google/Apple SDKs unless the app opts in.

7. **Database, storage, and functions data paths**
`supabase-database` maps to PostgREST CRUD and RPC endpoints, with typed query extensions built on the shared filter DSL. `supabase-storage` covers bucket/file APIs, signed URLs, public URLs, and resumable upload support. `supabase-functions` invokes Supabase Edge Functions over HTTP with typed request/response helpers. All three use the common client transport and report outcomes through `SupabaseResult`.

8. **Realtime subsystem**
`supabase-realtime` is the WebSocket layer. It manages Phoenix protocol channels, connection state, reconnection/backoff, presence, broadcast, typed events, and subscription filtering. It depends on the shared client for networking but is architecturally separate from the HTTP request/response modules because its lifecycle is long-lived and stateful.

9. **External systems and runtime boundaries**
The SDK talks to Supabase over three main channels: HTTP for auth/database/storage/functions, WebSocket for realtime, and platform-native sign-in SDKs for Google/Apple flows. Ktor engines provide the runtime-specific networking implementation, so the same API surface works across Android, iOS/macOS/tvOS/watchOS, JVM, Linux, Windows, and Wasm.

10. **Samples and integration examples**
`samples/chat-compose` is an Android/Compose sample that demonstrates end-to-end use of auth, database, realtime, and UI state. `samples/desktop-demo` shows a minimal desktop entry point. These are useful architecture references because they show how the modules are composed from an app’s perspective.

11. **End-to-end test boundary**
`e2e-tests` validates the SDK against a real or local Supabase backend. The presence of `supabase/` with migrations, seed data, and an example Edge Function shows that the repository includes a test backend environment, not just client code.

12. **Documentation and release pipeline**
`docs/` and `website/` are separate documentation systems, while GitHub Actions handles build, API checks, docs publishing, dependency submission, and release attestation. `buildSrc`, API dumps under each module, detekt config, and the version catalog are part of the engineering boundary that keeps the public surface stable across multiplatform targets.

Main entry points: [`supabase-auth/src/commonMain/kotlin/io/github/androidpoet/supabase/auth`](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-auth/src/commonMain/kotlin/io/github/androidpoet/supabase/auth) (Auth), [`supabase-client/src/commonMain/kotlin/io/github/androidpoet/supabase/client`](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-client/src/commonMain/kotlin/io/github/androidpoet/supabase/client) (Client), [`supabase-core/src/commonMain/kotlin/io/github/androidpoet/supabase/core`](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-core/src/commonMain/kotlin/io/github/androidpoet/supabase/core) (Core), [`supabase-database/src/commonMain/kotlin/io/github/androidpoet/supabase/database`](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-database/src/commonMain/kotlin/io/github/androidpoet/supabase/database) (Database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_core["Core SDK"]
  node_node_supabase_core[("Core<br/>multiplatform foundation")]
  node_node_supabase_client["Client<br/>transport backbone"]
  node_node_http_transport["HTTP transport<br/>ktor transport"]
  node_node_platform_engines(("Platform engines<br/>runtime engines"))
end

subgraph group_grp_features["Feature modules"]
  node_node_auth["Auth"]
  node_node_session["Sessions<br/>stateful auth"]
  node_node_database["Database<br/>postgrest client"]
  node_node_storage["Storage"]
  node_node_functions["Functions"]
  node_node_realtime["Realtime<br/>websocket client"]
end

subgraph group_grp_auth_native["Native auth adapters"]
  node_node_auth_google(("Google sign-in<br/>native adapter"))
  node_node_auth_apple(("Apple sign-in<br/>native adapter"))
end

subgraph group_grp_runtime["Runtime and examples"]
  node_node_chat_sample["Chat sample<br/>android sample"]
  node_node_desktop_sample["Desktop demo<br/>desktop sample"]
  node_node_e2e["E2E tests<br/>integration harness"]
  node_node_docs["Docs site<br/>documentation"]
end

subgraph group_grp_tooling["Tooling"]
  node_node_build{{"Build tooling<br/>gradle automation<br/>[Configuration.kt]"}}
end

node_node_supabase_client -->|"uses"| node_node_supabase_core
node_node_http_transport -->|"implements"| node_node_supabase_client
node_node_platform_engines -->|"plugs in"| node_node_http_transport
node_node_auth -->|"built on"| node_node_supabase_client
node_node_auth -->|"uses"| node_node_supabase_core
node_node_session -->|"supports"| node_node_auth
node_node_session -->|"uses"| node_node_supabase_core
node_node_database -->|"built on"| node_node_supabase_client
node_node_database -->|"uses"| node_node_supabase_core
node_node_storage -->|"built on"| node_node_supabase_client
node_node_storage -->|"uses"| node_node_supabase_core
node_node_functions -->|"built on"| node_node_supabase_client
node_node_functions -->|"uses"| node_node_supabase_core
node_node_realtime -->|"depends on"| node_node_supabase_client
node_node_realtime -->|"uses"| node_node_supabase_core
node_node_auth_google -->|"adapts"| node_node_auth
node_node_auth_apple -->|"adapts"| node_node_auth
node_node_chat_sample -->|"composes"| node_node_auth
node_node_chat_sample -->|"composes"| node_node_database
node_node_chat_sample -->|"composes"| node_node_realtime
node_node_desktop_sample -->|"demonstrates"| node_node_supabase_client
node_node_e2e -->|"validates"| node_node_auth
node_node_e2e -->|"validates"| node_node_database
node_node_docs -->|"documents"| node_node_auth
node_node_docs -->|"documents"| node_node_realtime
node_node_build -->|"governs"| node_node_supabase_core
node_node_build -->|"publishes"| node_node_docs
node_node_build -->|"orchestrates"| node_node_e2e

click node_node_supabase_core "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-core/src/commonMain/kotlin/io/github/androidpoet/supabase/core"
click node_node_supabase_client "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-client/src/commonMain/kotlin/io/github/androidpoet/supabase/client"
click node_node_http_transport "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-client/src/commonMain/kotlin/io/github/androidpoet/supabase/client/transport"
click node_node_platform_engines "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-client/src/androidMain/kotlin/io/github/androidpoet/supabase/client/transport"
click node_node_auth "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-auth/src/commonMain/kotlin/io/github/androidpoet/supabase/auth"
click node_node_session "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-auth/src/commonMain/kotlin/io/github/androidpoet/supabase/auth/session"
click node_node_database "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-database/src/commonMain/kotlin/io/github/androidpoet/supabase/database"
click node_node_storage "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-storage/src/commonMain/kotlin/io/github/androidpoet/supabase/storage"
click node_node_functions "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-functions/src/commonMain/kotlin/io/github/androidpoet/supabase/functions"
click node_node_realtime "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-realtime/src/commonMain/kotlin/io/github/androidpoet/supabase/realtime"
click node_node_auth_google "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-auth-google/src/commonMain/kotlin/io/github/androidpoet/supabase/auth/google"
click node_node_auth_apple "https://github.com/androidpoet/supabase-kmp/tree/main/supabase-auth-apple/src/commonMain/kotlin/io/github/androidpoet/supabase/auth/apple"
click node_node_chat_sample "https://github.com/androidpoet/supabase-kmp/tree/main/samples/chat-compose/src/main/java/io/github/androidpoet/supabase/sample/chat"
click node_node_desktop_sample "https://github.com/androidpoet/supabase-kmp/tree/main/samples/desktop-demo/src/main/kotlin/io/github/androidpoet/supabase/sample/desktop"
click node_node_e2e "https://github.com/androidpoet/supabase-kmp/tree/main/e2e-tests/src/test/kotlin/io/github/androidpoet/supabase/e2e"
click node_node_docs "https://github.com/androidpoet/supabase-kmp/tree/main/docs"
click node_node_build "https://github.com/androidpoet/supabase-kmp/blob/main/buildSrc/src/main/kotlin/io/github/androidpoet/supabase/Configuration.kt"

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_node_supabase_core,node_node_supabase_client,node_node_http_transport,node_node_platform_engines toneBlue
class node_node_auth,node_node_session,node_node_database,node_node_storage,node_node_functions,node_node_realtime toneAmber
class node_node_auth_google,node_node_auth_apple toneMint
class node_node_chat_sample,node_node_desktop_sample,node_node_e2e,node_node_docs toneRose
class node_node_build toneIndigo
```

## Components

### Core SDK

Shared foundation and client transport

- [Core](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-core/src/commonMain/kotlin/io/github/androidpoet/supabase/core): multiplatform foundation · Shared result, error, filter, ID, and response model layer used across the SDK. · `supabase-core/src/commonMain/kotlin/io/github/androidpoet/supabase/core`
- [Client](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-client/src/commonMain/kotlin/io/github/androidpoet/supabase/client): transport backbone · Ktor-backed Supabase client abstraction with interceptors, logging, retry, and platform engines. · `supabase-client/src/commonMain/kotlin/io/github/androidpoet/supabase/client`
- [HTTP transport](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-client/src/commonMain/kotlin/io/github/androidpoet/supabase/client/transport): ktor transport · Shared request pipeline and transport boundary for Supabase HTTP APIs. · `supabase-client/src/commonMain/kotlin/io/github/androidpoet/supabase/client/transport`
- [Platform engines](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-client/src/androidMain/kotlin/io/github/androidpoet/supabase/client/transport): runtime engines · Platform-specific Ktor engine implementations for Android, Apple, JVM, Linux, Windows, and Wasm. · `supabase-client/src/androidMain/kotlin/io/github/androidpoet/supabase/client/transport`

### Feature modules

HTTP-facing Supabase features built on the shared client

- [Auth](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-auth/src/commonMain/kotlin/io/github/androidpoet/supabase/auth): user auth · Email/password, OAuth, MFA, PKCE, native sign-in hooks, and session lifecycle management. · `supabase-auth/src/commonMain/kotlin/io/github/androidpoet/supabase/auth`
- [Sessions](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-auth/src/commonMain/kotlin/io/github/androidpoet/supabase/auth/session): stateful auth · Session manager, storage abstraction, in-memory and key-value persistence, and auto-refresh state flow. · `supabase-auth/src/commonMain/kotlin/io/github/androidpoet/supabase/auth/session`
- [Database](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-database/src/commonMain/kotlin/io/github/androidpoet/supabase/database): postgrest client · CRUD and RPC access for Supabase/PostgREST, built on shared filters and result handling. · `supabase-database/src/commonMain/kotlin/io/github/androidpoet/supabase/database`
- [Storage](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-storage/src/commonMain/kotlin/io/github/androidpoet/supabase/storage): object storage · Bucket, file, URL, and resumable upload APIs over the shared HTTP client. · `supabase-storage/src/commonMain/kotlin/io/github/androidpoet/supabase/storage`
- [Functions](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-functions/src/commonMain/kotlin/io/github/androidpoet/supabase/functions): edge functions · Supabase Edge Function invocation with typed request and response helpers. · `supabase-functions/src/commonMain/kotlin/io/github/androidpoet/supabase/functions`
- [Realtime](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-realtime/src/commonMain/kotlin/io/github/androidpoet/supabase/realtime): websocket client · Phoenix channel WebSocket layer with connection state, reconnection, presence, broadcast, and typed events. · `supabase-realtime/src/commonMain/kotlin/io/github/androidpoet/supabase/realtime`

### Native auth adapters

Optional platform-specific sign-in bridges

- [Google sign-in](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-auth-google/src/commonMain/kotlin/io/github/androidpoet/supabase/auth/google): native adapter · Optional Android Google sign-in bridge that feeds the shared native auth flow. · `supabase-auth-google/src/commonMain/kotlin/io/github/androidpoet/supabase/auth/google`
- [Apple sign-in](https://github.com/androidpoet/supabase-kmp/tree/main/supabase-auth-apple/src/commonMain/kotlin/io/github/androidpoet/supabase/auth/apple): native adapter · Optional Apple sign-in bridge for iOS, macOS, and shared Apple targets. · `supabase-auth-apple/src/commonMain/kotlin/io/github/androidpoet/supabase/auth/apple`

### Runtime and examples

Samples, docs, and backend validation

- [Chat sample](https://github.com/androidpoet/supabase-kmp/tree/main/samples/chat-compose/src/main/java/io/github/androidpoet/supabase/sample/chat): android sample · Compose sample wiring auth, database, realtime, and UI state into an end-to-end app. · `samples/chat-compose/src/main/java/io/github/androidpoet/supabase/sample/chat`
- [Desktop demo](https://github.com/androidpoet/supabase-kmp/tree/main/samples/desktop-demo/src/main/kotlin/io/github/androidpoet/supabase/sample/desktop): desktop sample · Minimal desktop entry point demonstrating SDK composition outside Android. · `samples/desktop-demo/src/main/kotlin/io/github/androidpoet/supabase/sample/desktop`
- [E2E tests](https://github.com/androidpoet/supabase-kmp/tree/main/e2e-tests/src/test/kotlin/io/github/androidpoet/supabase/e2e): integration harness · Backend-backed verification against a real or local Supabase environment, including migrations and seed data. · `e2e-tests/src/test/kotlin/io/github/androidpoet/supabase/e2e`
- [Docs site](https://github.com/androidpoet/supabase-kmp/tree/main/docs): documentation · MkDocs and website content covering architecture, guides, API docs, and tutorials. · `docs`

### Tooling

Build and release infrastructure

- [Build tooling](https://github.com/androidpoet/supabase-kmp/blob/main/buildSrc/src/main/kotlin/io/github/androidpoet/supabase/Configuration.kt): gradle automation · Root Gradle wiring, buildSrc conventions, version catalog, and CI/release workflow automation. · `buildSrc/src/main/kotlin/io/github/androidpoet/supabase/Configuration.kt`

## Connections

- Client → Core: uses · Transport reuses the shared result and error model.
- HTTP transport → Client: implements · The transport layer powers the client abstraction.
- Platform engines → HTTP transport: plugs in · Platform engines provide runtime-specific HTTP execution.
- Auth → Client: built on · Auth API calls go through the shared client.
- Auth → Core: uses · Auth returns shared result and response types.
- Sessions → Auth: supports · Session management is part of the auth subsystem.
- Sessions → Core: uses · Session state and errors align with core types.
- Database → Client: built on · Database requests flow through the shared HTTP client.
- Database → Core: uses · Database APIs report through the shared result model.
- Storage → Client: built on · Storage requests use the common transport.
- Storage → Core: uses · Storage APIs share response and result conventions.
- Functions → Client: built on · Functions invocation is implemented over HTTP transport.
- Functions → Core: uses · Functions responses and failures use shared core types.
- Realtime → Client: depends on · Realtime leverages the shared networking layer but remains a separate lifecycle.
- Realtime → Core: uses · Realtime events and outcomes reuse common types.
- Google sign-in → Auth: adapts · Google sign-in feeds the shared native auth flow.
- Apple sign-in → Auth: adapts · Apple sign-in feeds the shared native auth flow.
- Chat sample → Auth: composes · Sample app exercises authentication.
- Chat sample → Database: composes · Sample app reads and writes chat data.
- Chat sample → Realtime: composes · Sample app subscribes to live updates.
- Desktop demo → Client: demonstrates · Desktop demo shows basic SDK usage from a non-Android runtime.
- E2E tests → Auth: validates · End-to-end tests cover auth flows.
- E2E tests → Database: validates · End-to-end tests cover database behavior.
- Docs site → Auth: documents · Documentation includes auth guides and API references.
- Docs site → Realtime: documents · Documentation covers realtime concepts and usage.
- Build tooling → Core: governs · Build conventions and API stability apply across modules.
- Build tooling → Docs site: publishes · Docs and website are part of the release and publishing pipeline.
- Build tooling → E2E tests: orchestrates · CI runs backend validation and release checks.