Architecture

Unified request path

Swift / Kotlin / Expo / Electron / Tauri
                  │
        Better Auth signed Bearer
        Soar App API /api/app/v1
                  │
                  ▼
      Next.js / Nuxt / TanStack Start
          Unified Platform Host
                  │
     ┌────────────┼─────────────┐
     ▼            ▼             ▼
Better Auth   PostgreSQL     Storage / Billing / Push

The client UI depends on backend-neutral services. Standalone adapters call Supabase; Unified adapters call Better Auth and the App API. Calls never include an ownership userId: the selected backend session determines ownership.

Stable boundaries

• /api/auth/* is the Better Auth HTTP contract for registration, sign-in, OTP, session lifecycle, and account credentials.
• /api/app/v1/* is the frozen Soar App API business contract for profile, todos, device tokens, notifications, subscription, uploads, and account deletion.
• Hosts may use different framework internals but must preserve the observable contracts.
• Unified identity, data, storage, and subscription state come from one host deployment. Mixing a Supabase session with Unified business data is unsupported.

Security boundary

Native clients store signed Bearer tokens in platform secure storage. Electron keeps them in its main process; Tauri keeps them in Rust. Tokens, presigned URLs, and authorization headers must not enter browser storage, UI state, logs, analytics, or diagnostic exports.