androidpoet/supabase-kmp

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.