Data Layer

The data layer is how features talk to Supabase without knowing about Supabase. It has two testable seams (repository and remote data source), a no-throw result type at the boundary, and a three-state screen model. Learn this shape once and every feature reads the same way.

The repository pattern

Each feature talks to a *RepositoryProtocol, never to the network directly. Repositories own business rules (ordering, normalization, retry) and map errors; the actual Supabase calls live in a separate *RemoteDataSource. That's two injection seams:

ViewModel → *RepositoryProtocol → *RemoteDataSource → SupabaseClient
                   ↑                      ↑
            inject a fake repo     inject a fake data source
            (view-model tests)     (repository tests)

TodosRepository shows it well: add(text:userId:) trims + validates the title, fetches existing rows to compute the next sort_order, then delegates the insert to TodosRemoteDataSource. Tests swap a fake data source so no network runs.

AppResult and AppError

Repositories don't throw across their boundary — they return AppResult<T>:

enum AppResult<Value> {
    case success(Value)
    case failure(AppError)
}

AppError carries a typed code (authentication, rateLimited, network, validation, notFound, unknown), a user-facing message, and the original error. AppError.map(_:) translates raw errors into friendly copy — supabase-swift AuthError cases become messages like "The email or password is incorrect", and URLError becomes "You appear to be offline…". View models show message directly.

UiState — screen state

View models expose screen state as a single enum instead of a soup of isLoading / error / items flags:

enum UiState<Value: Sendable>: Sendable {
    case idle          // pre-load shell
    case loading       // initial fetch or reload
    case data(Value)   // success — use .data([]) for an empty result
    case error(String) // the AppError.message to show
}

idle renders a clean first shell; an empty success is .data([]) so the empty-state view can distinguish "no items" from "not loaded yet". View models are @MainActor @Observable; views own them with @State.

Models

Models are plain Codable structs with snake_case CodingKeys mapping to the Postgres columns, and are Identifiable + Sendable:

• Todo — id, userId, title, completed, sortOrder, timestamps.
• Profile — id, and optional fullName / bio / phone / location / avatarURL + timestamps (matches the profiles table; fields are nullable).

ProfileRepository writes one field at a time via a dynamic-key upsert payload (only id, updated_at, and the changed column go to Postgres), so partial edits never clobber other fields.

Row-level security expectations

Every table is RLS-protected and scoped to the signed-in user (auth.uid() = user_id, or = id for profiles). Because RLS enforces ownership server-side, the app's queries simply filter by user_id and trust the policy. The subscriptions / payments tables are SELECT-only for clients — writes happen exclusively in service-role Edge Functions. See Supabase Setup for the full policy SQL.

Offline awareness

NetworkObserver (@MainActor @Observable) wraps NWPathMonitor and publishes isOnline, mounted app-wide to drive the offline banner (see UI Components). It's behind a NetworkMonitoring protocol so tests inject a fake path status. Repositories stay network-only today — there's no local cache — so the banner is how the UI signals degraded state.

Local preferences

AppPreferences is an @Observable wrapper over UserDefaults for non-secret app state (theme, language, onboarding/consent flags). Auth tokens never go here — they live in the Keychain (see Authentication).

Adding your own feature

Follow the Todos shape end to end:

Related pages