Scaffold backend gateway and integration docs

2026-02-14 20:10:16 +01:00
commit 577c4b33b7
166 changed files with 13382 additions and 0 deletions
@@ -0,0 +1,45 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.build/
+.buildlog/
+.history
+.svn/
+.swiftpm/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+/coverage/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release
@@ -0,0 +1,45 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536"
+  channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+      base_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+    - platform: android
+      create_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+      base_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+    - platform: ios
+      create_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+      base_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+    - platform: linux
+      create_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+      base_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+    - platform: macos
+      create_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+      base_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+    - platform: web
+      create_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+      base_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+    - platform: windows
+      create_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+      base_revision: 582a0e7c5581dc0ca5f7bfd8662bb8db6f59d536
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'
@@ -0,0 +1,17 @@
+# relationship_saver
+
+A new Flutter project.
+
+## Getting Started
+
+This project is a starting point for a Flutter application.
+
+A few resources to get you started if this is your first Flutter project:
+
+- [Learn Flutter](https://docs.flutter.dev/get-started/learn-flutter)
+- [Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
+- [Flutter learning resources](https://docs.flutter.dev/reference/learning-resources)
+
+For help getting started with Flutter development, view the
+[online documentation](https://docs.flutter.dev/), which offers tutorials,
+samples, guidance on mobile development, and a full API reference.
@@ -0,0 +1,19 @@
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+
+linter:
+  rules:
+    always_declare_return_types: true
+    always_use_package_imports: true
+    avoid_dynamic_calls: true
+    avoid_print: true
+    directives_ordering: true
+    prefer_final_fields: true
+    prefer_final_locals: true
+    sort_constructors_first: true
+    unawaited_futures: true
@@ -0,0 +1,14 @@
+gradle-wrapper.jar
+/.gradle
+/captures/
+/gradlew
+/gradlew.bat
+/local.properties
+GeneratedPluginRegistrant.java
+.cxx/
+
+# Remember to never publicly share your keystore.
+# See https://flutter.dev/to/reference-keystore
+key.properties
+**/*.keystore
+**/*.jks
@@ -0,0 +1,44 @@
+plugins {
+    id("com.android.application")
+    id("kotlin-android")
+    // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins.
+    id("dev.flutter.flutter-gradle-plugin")
+}
+
+android {
+    namespace = "com.example.relationship_saver"
+    compileSdk = flutter.compileSdkVersion
+    ndkVersion = flutter.ndkVersion
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = JavaVersion.VERSION_17.toString()
+    }
+
+    defaultConfig {
+        // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
+        applicationId = "com.example.relationship_saver"
+        // You can update the following values to match your application needs.
+        // For more information, see: https://flutter.dev/to/review-gradle-config.
+        minSdk = flutter.minSdkVersion
+        targetSdk = flutter.targetSdkVersion
+        versionCode = flutter.versionCode
+        versionName = flutter.versionName
+    }
+
+    buildTypes {
+        release {
+            // TODO: Add your own signing config for the release build.
+            // Signing with the debug keys for now, so `flutter run --release` works.
+            signingConfig = signingConfigs.getByName("debug")
+        }
+    }
+}
+
+flutter {
+    source = "../.."
+}
@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- The INTERNET permission is required for development. Specifically,
+         the Flutter tool needs it to communicate with the running application
+         to allow setting breakpoints, to provide hot reload, etc.
+    -->
+    <uses-permission android:name="android.permission.INTERNET"/>
+</manifest>
@@ -0,0 +1,45 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application
+        android:label="relationship_saver"
+        android:name="${applicationName}"
+        android:icon="@mipmap/ic_launcher">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:launchMode="singleTop"
+            android:taskAffinity=""
+            android:theme="@style/LaunchTheme"
+            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
+            android:hardwareAccelerated="true"
+            android:windowSoftInputMode="adjustResize">
+            <!-- Specifies an Android theme to apply to this Activity as soon as
+                 the Android process has started. This theme is visible to the user
+                 while the Flutter UI initializes. After that, this theme continues
+                 to determine the Window background behind the Flutter UI. -->
+            <meta-data
+              android:name="io.flutter.embedding.android.NormalTheme"
+              android:resource="@style/NormalTheme"
+              />
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN"/>
+                <category android:name="android.intent.category.LAUNCHER"/>
+            </intent-filter>
+        </activity>
+        <!-- Don't delete the meta-data below.
+             This is used by the Flutter tool to generate GeneratedPluginRegistrant.java -->
+        <meta-data
+            android:name="flutterEmbedding"
+            android:value="2" />
+    </application>
+    <!-- Required to query activities that can process text, see:
+         https://developer.android.com/training/package-visibility and
+         https://developer.android.com/reference/android/content/Intent#ACTION_PROCESS_TEXT.
+
+         In particular, this is used by the Flutter engine in io.flutter.plugin.text.ProcessTextPlugin. -->
+    <queries>
+        <intent>
+            <action android:name="android.intent.action.PROCESS_TEXT"/>
+            <data android:mimeType="text/plain"/>
+        </intent>
+    </queries>
+</manifest>
@@ -0,0 +1,5 @@
+package com.example.relationship_saver
+
+import io.flutter.embedding.android.FlutterActivity
+
+class MainActivity : FlutterActivity()
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Modify this file to customize your launch splash screen -->
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:drawable="?android:colorBackground" />
+
+    <!-- You can insert your own image assets here -->
+    <!-- <item>
+        <bitmap
+            android:gravity="center"
+            android:src="@mipmap/launch_image" />
+    </item> -->
+</layer-list>
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Modify this file to customize your launch splash screen -->
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:drawable="@android:color/white" />
+
+    <!-- You can insert your own image assets here -->
+    <!-- <item>
+        <bitmap
+            android:gravity="center"
+            android:src="@mipmap/launch_image" />
+    </item> -->
+</layer-list>
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Theme applied to the Android Window while the process is starting when the OS's Dark Mode setting is on -->
+    <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar">
+        <!-- Show a splash screen on the activity. Automatically removed when
+             the Flutter engine draws its first frame -->
+        <item name="android:windowBackground">@drawable/launch_background</item>
+    </style>
+    <!-- Theme applied to the Android Window as soon as the process has started.
+         This theme determines the color of the Android Window while your
+         Flutter UI initializes, as well as behind your Flutter UI while its
+         running.
+
+         This Theme is only used starting with V2 of Flutter's Android embedding. -->
+    <style name="NormalTheme" parent="@android:style/Theme.Black.NoTitleBar">
+        <item name="android:windowBackground">?android:colorBackground</item>
+    </style>
+</resources>
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Theme applied to the Android Window while the process is starting when the OS's Dark Mode setting is off -->
+    <style name="LaunchTheme" parent="@android:style/Theme.Light.NoTitleBar">
+        <!-- Show a splash screen on the activity. Automatically removed when
+             the Flutter engine draws its first frame -->
+        <item name="android:windowBackground">@drawable/launch_background</item>
+    </style>
+    <!-- Theme applied to the Android Window as soon as the process has started.
+         This theme determines the color of the Android Window while your
+         Flutter UI initializes, as well as behind your Flutter UI while its
+         running.
+
+         This Theme is only used starting with V2 of Flutter's Android embedding. -->
+    <style name="NormalTheme" parent="@android:style/Theme.Light.NoTitleBar">
+        <item name="android:windowBackground">?android:colorBackground</item>
+    </style>
+</resources>
@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- The INTERNET permission is required for development. Specifically,
+         the Flutter tool needs it to communicate with the running application
+         to allow setting breakpoints, to provide hot reload, etc.
+    -->
+    <uses-permission android:name="android.permission.INTERNET"/>
+</manifest>
@@ -0,0 +1,24 @@
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+val newBuildDir: Directory =
+    rootProject.layout.buildDirectory
+        .dir("../../build")
+        .get()
+rootProject.layout.buildDirectory.value(newBuildDir)
+
+subprojects {
+    val newSubprojectBuildDir: Directory = newBuildDir.dir(project.name)
+    project.layout.buildDirectory.value(newSubprojectBuildDir)
+}
+subprojects {
+    project.evaluationDependsOn(":app")
+}
+
+tasks.register<Delete>("clean") {
+    delete(rootProject.layout.buildDirectory)
+}
@@ -0,0 +1,2 @@
+org.gradle.jvmargs=-Xmx8G -XX:MaxMetaspaceSize=4G -XX:ReservedCodeCacheSize=512m -XX:+HeapDumpOnOutOfMemoryError
+android.useAndroidX=true
@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-all.zip
@@ -0,0 +1,26 @@
+pluginManagement {
+    val flutterSdkPath =
+        run {
+            val properties = java.util.Properties()
+            file("local.properties").inputStream().use { properties.load(it) }
+            val flutterSdkPath = properties.getProperty("flutter.sdk")
+            require(flutterSdkPath != null) { "flutter.sdk not set in local.properties" }
+            flutterSdkPath
+        }
+
+    includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")
+
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+plugins {
+    id("dev.flutter.flutter-plugin-loader") version "1.0.0"
+    id("com.android.application") version "8.11.1" apply false
+    id("org.jetbrains.kotlin.android") version "2.2.20" apply false
+}
+
+include(":app")
@@ -0,0 +1,57 @@
+# ADR 0002: Backend Protocol = HTTPS REST + JSON (OpenAPI-First)
+
+- Status: Accepted
+- Date: 2026-02-14
+
+## Context
+
+`relationship_saver` is offline-first for MVP. Local DB remains the source of truth for core usage. Backend responsibilities are incremental:
+
+1. account/session management
+2. sync transport for local mutations and remote updates
+3. recommendation/signals feed
+4. future upload/download URL broker
+
+We need a transport that is cross-platform, testable in Flutter, easy to stub for local development, and contract-driven across mobile/backend teams.
+
+## Decision
+
+Use HTTPS REST + JSON with an OpenAPI-first contract.
+
+- Client HTTP stack: `dio`
+- Typed models: `freezed` + `json_serializable`
+- Gateway boundary: `BackendGateway` (transport-agnostic interface)
+- Runtime implementation: `BackendGatewayRest`
+- Local development implementation: `BackendGatewayFake`
+- Auth/session support: access + refresh token with secure storage
+- Retry policy: only transient failures; non-idempotent retries require idempotency key
+- Error surface: typed `BackendException` taxonomy
+
+## Consequences
+
+### Positive
+
+- Strong, versioned contract artifact in `docs/api/openapi.yaml`
+- Fast local iteration with fake gateway, no backend dependency for core UX
+- Explicit behavior for refresh/retry/failure classes
+- Good compatibility across Android/iOS/macOS/Windows/Linux/Web
+
+### Tradeoffs
+
+- REST polling for feed/sync may be less real-time than socket-based push
+- Some envelope sizes may require tuning and pagination strategy
+- Requires careful idempotency handling for mutation endpoints
+
+## Evolution Plan
+
+Realtime is deferred for now but planned:
+
+1. Keep REST as source of truth for command/query semantics.
+2. Add optional SSE or WebSocket channel for push notifications/signals invalidation.
+3. Continue using same DTO schema envelopes from OpenAPI where possible.
+4. Add explicit capability negotiation (`/v1/capabilities`) when realtime ships.
+
+## Rejected Alternatives
+
+- gRPC-only for MVP: stronger streaming story, but higher setup and broader tooling burden for immediate scope.
+- GraphQL-first: flexible querying, but sync/mutation idempotency patterns are clearer with explicit REST resources now.
@@ -0,0 +1,203 @@
+# Relationship Saver Progress Log
+
+Updated: 2026-02-14
+
+## Current Status
+
+The Flutter app now includes a production-grade backend integration scaffold with an offline-first posture:
+
+- Local/offline UX remains primary; backend is optional for core usage.
+- A transport-agnostic gateway interface is in place.
+- REST implementation with auth refresh/retry/error mapping is implemented.
+- Deterministic fake gateway is available for local/dev without backend.
+- OpenAPI contract + ADR + setup docs + unit tests are in place.
+- `flutter analyze` and `flutter test` are passing.
+
+## What Was Implemented
+
+### 1. Core Config + Theme Shell
+
+- Added backend config with build-time + runtime override:
+  - `lib/core/config/app_config.dart`
+- Added lightweight app theme aligned with reference style direction:
+  - `lib/core/config/app_theme.dart`
+- Updated app entry shell and Riverpod root:
+  - `lib/main.dart`
+
+### 2. Network Foundation
+
+Implemented a Dio stack with request metadata, auth, refresh, retry, and error mapping:
+
+- `lib/core/network/dio_factory.dart`
+- `lib/core/network/network_constants.dart`
+- `lib/core/network/backend_exception.dart`
+- `lib/core/network/dio_error_mapper.dart`
+- Interceptors:
+  - `lib/core/network/interceptors/request_metadata_interceptor.dart`
+  - `lib/core/network/interceptors/auth_interceptor.dart`
+  - `lib/core/network/interceptors/refresh_token_interceptor.dart`
+  - `lib/core/network/interceptors/retry_interceptor.dart`
+
+Behavior implemented:
+
+- Adds per-request `X-Request-Id`.
+- Adds `Authorization: Bearer <token>` when session exists.
+- On `401`, attempts one refresh (`/v1/auth/refresh`) then retries original request.
+- If refresh fails, session is cleared and `AuthExpiredException` surfaced.
+- Retry policy (max 2 retries, exponential backoff):
+  - Retry transient failures (`timeouts`, `connection`, `5xx`).
+  - Safe methods (`GET/HEAD/OPTIONS`) retry automatically.
+  - Non-idempotent endpoints only retry when `Idempotency-Key` exists.
+- Maps Dio failures into typed backend exceptions with metadata.
+
+### 3. Auth Token Storage
+
+- Interface:
+  - `lib/core/auth/token_store.dart`
+- Production implementation:
+  - `lib/core/auth/secure_token_store.dart`
+- Test/dev implementation:
+  - `lib/core/auth/in_memory_token_store.dart`
+
+### 4. Backend Integration Layer
+
+Domain boundary and implementations:
+
+- Interface:
+  - `lib/integrations/backend/backend_gateway.dart`
+- REST:
+  - `lib/integrations/backend/backend_gateway_rest.dart`
+- Fake:
+  - `lib/integrations/backend/backend_gateway_fake.dart`
+- Optional Riverpod providers:
+  - `lib/integrations/backend/backend_gateway_provider.dart`
+- Sync validation:
+  - `lib/integrations/backend/sync_envelope_validator.dart`
+
+Implemented methods:
+
+- sign-in/out + me
+- sync pull/push (with idempotency key on push)
+- signals feed + ack
+- upload init + download URL scaffold
+
+Offline-first hardening:
+
+- `signOut()` clears local token store in `finally`, even when network call fails.
+
+### 5. Typed Models (Freezed + JSON)
+
+- `lib/integrations/backend/models/backend_models.dart`
+- Generated files:
+  - `backend_models.freezed.dart`
+  - `backend_models.g.dart`
+
+Includes DTOs/enums for:
+
+- Auth (`SignInRequest`, `AuthSession`, refresh request/response, `UserProfile`)
+- Sync (`ChangeEnvelope`, push/pull requests/results, ack/rejection)
+- Signals (`SignalsFeed`, `SignalItem`, ack request/action)
+- Uploads (`UploadInitRequest/Result`, `DownloadUrl`)
+
+### 6. Contract + Architecture Docs
+
+- OpenAPI spec:
+  - `docs/api/openapi.yaml`
+- ADR:
+  - `docs/ADR/0002-backend-protocol-rest-openapi.md`
+- Setup instructions:
+  - `docs/SETUP.md`
+- Previous concise checklist log:
+  - `docs/PROGRESS.md`
+
+### 7. Tooling + Quality
+
+- Strict analyzer/lints:
+  - `analysis_options.yaml`
+- Dependencies added in `pubspec.yaml`:
+  - runtime: `dio`, `freezed_annotation`, `json_annotation`, `flutter_secure_storage`, `uuid`, `clock`, `flutter_riverpod`
+  - dev: `freezed`, `json_serializable`, `build_runner`, `mocktail`
+
+### 8. Test Coverage Added
+
+Core network and model tests:
+
+- `test/core/network/token_refresh_interceptor_test.dart`
+- `test/core/network/dio_error_mapper_test.dart`
+- `test/core/network/retry_interceptor_test.dart`
+- `test/integrations/backend/backend_models_serialization_test.dart`
+- `test/integrations/backend/sync_envelope_validator_test.dart`
+- helper adapter: `test/helpers/queue_http_client_adapter.dart`
+- updated smoke widget test: `test/widget_test.dart`
+
+## Verification Snapshot
+
+Most recent local checks:
+
+- `flutter analyze` -> pass
+- `flutter test` -> pass
+
+## Known Gaps / Intentional Scope Limits
+
+- No realtime transport yet (SSE/WebSocket intentionally deferred).
+- No backend-generated client code from OpenAPI yet.
+- No persistence layer wiring to local DB yet (gateway is ready to plug in).
+- No UI features using backend gateway yet beyond app shell readiness.
+- Fake gateway data is deterministic sample content, not scenario-configurable yet.
+
+## Handoff Plan For Next Agent Sessions
+
+### Priority 1: Repository Hygiene + CI
+
+1. Add CI workflow for `flutter analyze` + `flutter test`.
+2. Add branch protections / PR template if desired.
+3. Keep generated files committed policy explicit in README.
+
+### Priority 2: Local DB Integration (Offline-First Core)
+
+1. Define local domain entities and repositories for `person`, `capture`, `giftIdea`, `eventIdea`, `tag`, `reminderRule`.
+2. Map local mutations to `ChangeEnvelope` and enqueue for sync.
+3. Create sync orchestrator service that:
+   - pushes pending local mutations,
+   - applies pull changes with conflict policy,
+   - stores/advances cursor.
+4. Add tests for conflict handling and cursor progression.
+
+### Priority 3: App Wiring + UX
+
+1. Wire `BackendGateway` into app services/use cases (not UI widgets directly).
+2. Add session state provider (signed in / expired / signed out).
+3. Add explicit offline indicators and non-blocking sync status UI.
+4. Start consuming fake gateway in feature screens before live backend.
+
+### Priority 4: Security + Hardening
+
+1. Add central log redaction helper for headers/bodies.
+2. Add token-expiry pre-check strategy (optional proactive refresh).
+3. Evaluate secure storage behavior on web target and fallback policy.
+4. Add tests for concurrent 401 refresh race conditions.
+
+### Priority 5: API Evolution
+
+1. Version strategy in OpenAPI (`/v1` already set).
+2. Define backend error payload schema formally in OpenAPI.
+3. Add capabilities endpoint for future realtime negotiation.
+4. Add SSE/WebSocket design ADR when backend is ready.
+
+## How To Continue Quickly
+
+1. Run: `flutter pub get`
+2. If models change: `dart run build_runner build --delete-conflicting-outputs`
+3. Validate: `flutter analyze && flutter test`
+4. Start from:
+   - gateway surface: `lib/integrations/backend/backend_gateway.dart`
+   - sync transport: `lib/integrations/backend/backend_gateway_rest.dart`
+   - contract: `docs/api/openapi.yaml`
+
+## Important Notes
+
+- Current default base URL is placeholder (`https://api.example.com`).
+- Use fake mode for local iteration:
+  - `flutter run --dart-define=USE_FAKE_BACKEND=true`
+- Build-time URL override:
+  - `flutter run --dart-define=BACKEND_BASE_URL=<your-url>`
@@ -0,0 +1,35 @@
+# Setup
+
+## Backend Base URL
+
+Build-time (recommended):
+
+```bash
+flutter run --dart-define=BACKEND_BASE_URL=https://api.example.com
+```
+
+Runtime override (for future settings screens):
+
+```dart
+AppConfig.overrideBackendBaseUrl('https://staging.example.com');
+```
+
+## Run With Fake Gateway
+
+Use fake gateway for local/offline development:
+
+```bash
+flutter run --dart-define=USE_FAKE_BACKEND=true
+```
+
+## Run Tests
+
+```bash
+flutter test
+```
+
+## Generate Code
+
+```bash
+dart run build_runner build --delete-conflicting-outputs
+```
@@ -0,0 +1,344 @@
+openapi: 3.0.3
+info:
+  title: Relationship Saver API
+  version: 0.1.0
+  description: |
+    Backend contract for auth, sync, signals, and upload scaffolding.
+servers:
+  - url: https://api.example.com
+paths:
+  /v1/auth/sign-in:
+    post:
+      summary: Sign in
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SignInRequest'
+      responses:
+        '200':
+          description: Signed-in session
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AuthSession'
+  /v1/auth/refresh:
+    post:
+      summary: Refresh session
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AuthRefreshRequest'
+      responses:
+        '200':
+          description: Refreshed token bundle
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AuthRefreshResponse'
+  /v1/auth/sign-out:
+    post:
+      summary: Sign out
+      responses:
+        '204':
+          description: Signed out
+  /v1/me:
+    get:
+      summary: Current user profile
+      responses:
+        '200':
+          description: Profile
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserProfile'
+  /v1/sync/push:
+    post:
+      summary: Push local changes
+      parameters:
+        - in: header
+          name: Idempotency-Key
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SyncPushRequest'
+      responses:
+        '200':
+          description: Push result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SyncPushResult'
+  /v1/sync/pull:
+    get:
+      summary: Pull remote changes
+      parameters:
+        - in: query
+          name: cursor
+          schema:
+            type: string
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            default: 200
+      responses:
+        '200':
+          description: Pull result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SyncPullResult'
+  /v1/signals:
+    get:
+      summary: Fetch signals feed
+      parameters:
+        - in: query
+          name: cursor
+          schema:
+            type: string
+        - in: query
+          name: since
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            default: 50
+        - in: query
+          name: personId
+          schema:
+            type: array
+            items:
+              type: string
+      responses:
+        '200':
+          description: Signals page
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SignalsFeed'
+  /v1/signals/{id}/ack:
+    post:
+      summary: Acknowledge signal
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SignalAckRequest'
+      responses:
+        '204':
+          description: Acknowledged
+  /v1/uploads:
+    post:
+      summary: Initialize upload
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UploadInitRequest'
+      responses:
+        '200':
+          description: Upload URL
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UploadInitResult'
+  /v1/files/{fileId}:
+    get:
+      summary: Resolve file download URL
+      parameters:
+        - in: path
+          name: fileId
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Download URL
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DownloadUrl'
+components:
+  schemas:
+    SignInRequest:
+      type: object
+      properties:
+        method:
+          type: string
+          enum: [email_magic_link, password, oidc]
+        email:
+          type: string
+          format: email
+        password:
+          type: string
+        idToken:
+          type: string
+      required: [method]
+    UserProfile:
+      type: object
+      properties:
+        id: { type: string }
+        email: { type: string, format: email }
+        displayName: { type: string }
+        avatarFileId: { type: string }
+      required: [id]
+    AuthSession:
+      type: object
+      properties:
+        accessToken: { type: string }
+        refreshToken: { type: string }
+        expiresAt: { type: string, format: date-time }
+        user:
+          $ref: '#/components/schemas/UserProfile'
+      required: [accessToken, refreshToken, expiresAt, user]
+    AuthRefreshRequest:
+      type: object
+      properties:
+        refreshToken: { type: string }
+      required: [refreshToken]
+    AuthRefreshResponse:
+      type: object
+      properties:
+        accessToken: { type: string }
+        refreshToken: { type: string }
+        expiresAt: { type: string, format: date-time }
+      required: [accessToken, expiresAt]
+    ChangeEnvelope:
+      type: object
+      properties:
+        schemaVersion: { type: integer }
+        entityType: { type: string }
+        entityId: { type: string }
+        op:
+          type: string
+          enum: [upsert, delete]
+        modifiedAt:
+          type: string
+          format: date-time
+        clientMutationId: { type: string }
+        payload:
+          type: object
+          nullable: true
+          additionalProperties: true
+      required:
+        [schemaVersion, entityType, entityId, op, modifiedAt, clientMutationId]
+    SyncPushRequest:
+      type: object
+      properties:
+        deviceId: { type: string }
+        cursor: { type: string }
+        changes:
+          type: array
+          items:
+            $ref: '#/components/schemas/ChangeEnvelope'
+        idempotencyKey: { type: string }
+      required: [deviceId, changes, idempotencyKey]
+    MutationAck:
+      type: object
+      properties:
+        clientMutationId: { type: string }
+        serverMutationId: { type: string }
+        acceptedAt: { type: string, format: date-time }
+      required: [clientMutationId]
+    MutationRejection:
+      type: object
+      properties:
+        clientMutationId: { type: string }
+        code: { type: string }
+        message: { type: string }
+      required: [clientMutationId, code, message]
+    SyncPushResult:
+      type: object
+      properties:
+        cursor: { type: string }
+        accepted:
+          type: array
+          items:
+            $ref: '#/components/schemas/MutationAck'
+        rejected:
+          type: array
+          items:
+            $ref: '#/components/schemas/MutationRejection'
+      required: [cursor, accepted, rejected]
+    SyncPullResult:
+      type: object
+      properties:
+        cursor: { type: string }
+        changes:
+          type: array
+          items:
+            $ref: '#/components/schemas/ChangeEnvelope'
+      required: [cursor, changes]
+    SignalItem:
+      type: object
+      properties:
+        id: { type: string }
+        type: { type: string }
+        title: { type: string }
+        description: { type: string }
+        personId: { type: string }
+        createdAt: { type: string, format: date-time }
+        metadata:
+          type: object
+          additionalProperties: true
+      required: [id, type, title, createdAt]
+    SignalsFeed:
+      type: object
+      properties:
+        cursor: { type: string }
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/SignalItem'
+      required: [items]
+    SignalAckRequest:
+      type: object
+      properties:
+        action:
+          type: string
+          enum: [viewed, dismissed, saved, purchased]
+        at:
+          type: string
+          format: date-time
+      required: [action, at]
+    UploadInitRequest:
+      type: object
+      properties:
+        purpose:
+          type: string
+          enum: [avatar, attachment]
+        contentType: { type: string }
+        sizeBytes: { type: integer }
+      required: [purpose, contentType, sizeBytes]
+    UploadInitResult:
+      type: object
+      properties:
+        uploadUrl: { type: string }
+        fileId: { type: string }
+        expiresAt: { type: string, format: date-time }
+      required: [uploadUrl, fileId, expiresAt]
+    DownloadUrl:
+      type: object
+      properties:
+        downloadUrl: { type: string }
+        expiresAt: { type: string, format: date-time }
+      required: [downloadUrl, expiresAt]
@@ -0,0 +1,34 @@
+**/dgph
+*.mode1v3
+*.mode2v3
+*.moved-aside
+*.pbxuser
+*.perspectivev3
+**/*sync/
+.sconsign.dblite
+.tags*
+**/.vagrant/
+**/DerivedData/
+Icon?
+**/Pods/
+**/.symlinks/
+profile
+xcuserdata
+**/.generated/
+Flutter/App.framework
+Flutter/Flutter.framework
+Flutter/Flutter.podspec
+Flutter/Generated.xcconfig
+Flutter/ephemeral/
+Flutter/app.flx
+Flutter/app.zip
+Flutter/flutter_assets/
+Flutter/flutter_export_environment.sh
+ServiceDefinitions.json
+Runner/GeneratedPluginRegistrant.*
+
+# Exceptions to above rules.
+!default.mode1v3
+!default.mode2v3
+!default.pbxuser
+!default.perspectivev3
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleExecutable</key>
+  <string>App</string>
+  <key>CFBundleIdentifier</key>
+  <string>io.flutter.flutter.app</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>App</string>
+  <key>CFBundlePackageType</key>
+  <string>FMWK</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0</string>
+  <key>CFBundleSignature</key>
+  <string>????</string>
+  <key>CFBundleVersion</key>
+  <string>1.0</string>
+</dict>
+</plist>
@@ -0,0 +1,2 @@
+#include? "Pods/Target Support Files/Pods-Runner/Pods-Runner.debug.xcconfig"
+#include "Generated.xcconfig"
@@ -0,0 +1,2 @@
+#include? "Pods/Target Support Files/Pods-Runner/Pods-Runner.release.xcconfig"
+#include "Generated.xcconfig"
@@ -0,0 +1,43 @@
+# Uncomment this line to define a global platform for your project
+# platform :ios, '13.0'
+
+# CocoaPods analytics sends network stats synchronously affecting flutter build latency.
+ENV['COCOAPODS_DISABLE_STATS'] = 'true'
+
+project 'Runner', {
+  'Debug' => :debug,
+  'Profile' => :release,
+  'Release' => :release,
+}
+
+def flutter_root
+  generated_xcode_build_settings_path = File.expand_path(File.join('..', 'Flutter', 'Generated.xcconfig'), __FILE__)
+  unless File.exist?(generated_xcode_build_settings_path)
+    raise "#{generated_xcode_build_settings_path} must exist. If you're running pod install manually, make sure flutter pub get is executed first"
+  end
+
+  File.foreach(generated_xcode_build_settings_path) do |line|
+    matches = line.match(/FLUTTER_ROOT\=(.*)/)
+    return matches[1].strip if matches
+  end
+  raise "FLUTTER_ROOT not found in #{generated_xcode_build_settings_path}. Try deleting Generated.xcconfig, then run flutter pub get"
+end
+
+require File.expand_path(File.join('packages', 'flutter_tools', 'bin', 'podhelper'), flutter_root)
+
+flutter_ios_podfile_setup
+
+target 'Runner' do
+  use_frameworks!
+
+  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
+  target 'RunnerTests' do
+    inherit! :search_paths
+  end
+end
+
+post_install do |installer|
+  installer.pods_project.targets.each do |target|
+    flutter_additional_ios_build_settings(target)
+  end
+end
@@ -0,0 +1,623 @@
+// !$*UTF8*$!
+{
+	archiveVersion = 1;
+	classes = {
+	};
+	objectVersion = 54;
+	objects = {
+
+/* Begin PBXBuildFile section */
+		1498D2341E8E89220040F4C2 /* GeneratedPluginRegistrant.m in Sources */ = {isa = PBXBuildFile; fileRef = 1498D2331E8E89220040F4C2 /* GeneratedPluginRegistrant.m */; };
+		331C808B294A63AB00263BE5 /* RunnerTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 331C807B294A618700263BE5 /* RunnerTests.swift */; };
+		3B3967161E833CAA004F5970 /* AppFrameworkInfo.plist in Resources */ = {isa = PBXBuildFile; fileRef = 3B3967151E833CAA004F5970 /* AppFrameworkInfo.plist */; };
+		74858FAF1ED2DC5600515810 /* AppDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 74858FAE1ED2DC5600515810 /* AppDelegate.swift */; };
+		7884E8682EC3CC0700C636F2 /* SceneDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7884E8672EC3CC0400C636F2 /* SceneDelegate.swift */; };
+		97C146FC1CF9000F007C117D /* Main.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 97C146FA1CF9000F007C117D /* Main.storyboard */; };
+		97C146FE1CF9000F007C117D /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 97C146FD1CF9000F007C117D /* Assets.xcassets */; };
+		97C147011CF9000F007C117D /* LaunchScreen.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 97C146FF1CF9000F007C117D /* LaunchScreen.storyboard */; };
+/* End PBXBuildFile section */
+
+/* Begin PBXContainerItemProxy section */
+		331C8085294A63A400263BE5 /* PBXContainerItemProxy */ = {
+			isa = PBXContainerItemProxy;
+			containerPortal = 97C146E61CF9000F007C117D /* Project object */;
+			proxyType = 1;
+			remoteGlobalIDString = 97C146ED1CF9000F007C117D;
+			remoteInfo = Runner;
+		};
+/* End PBXContainerItemProxy section */
+
+/* Begin PBXCopyFilesBuildPhase section */
+		9705A1C41CF9048500538489 /* Embed Frameworks */ = {
+			isa = PBXCopyFilesBuildPhase;
+			buildActionMask = 2147483647;
+			dstPath = "";
+			dstSubfolderSpec = 10;
+			files = (
+			);
+			name = "Embed Frameworks";
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXCopyFilesBuildPhase section */
+
+/* Begin PBXFileReference section */
+		1498D2321E8E86230040F4C2 /* GeneratedPluginRegistrant.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = GeneratedPluginRegistrant.h; sourceTree = "<group>"; };
+		1498D2331E8E89220040F4C2 /* GeneratedPluginRegistrant.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = GeneratedPluginRegistrant.m; sourceTree = "<group>"; };
+		331C807B294A618700263BE5 /* RunnerTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = RunnerTests.swift; sourceTree = "<group>"; };
+		331C8081294A63A400263BE5 /* RunnerTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = RunnerTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
+		3B3967151E833CAA004F5970 /* AppFrameworkInfo.plist */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.plist.xml; name = AppFrameworkInfo.plist; path = Flutter/AppFrameworkInfo.plist; sourceTree = "<group>"; };
+		74858FAD1ED2DC5600515810 /* Runner-Bridging-Header.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = "Runner-Bridging-Header.h"; sourceTree = "<group>"; };
+		74858FAE1ED2DC5600515810 /* AppDelegate.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = AppDelegate.swift; sourceTree = "<group>"; };
+		7884E8672EC3CC0400C636F2 /* SceneDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SceneDelegate.swift; sourceTree = "<group>"; };
+		7AFA3C8E1D35360C0083082E /* Release.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; name = Release.xcconfig; path = Flutter/Release.xcconfig; sourceTree = "<group>"; };
+		9740EEB21CF90195004384FC /* Debug.xcconfig */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.xcconfig; name = Debug.xcconfig; path = Flutter/Debug.xcconfig; sourceTree = "<group>"; };
+		9740EEB31CF90195004384FC /* Generated.xcconfig */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.xcconfig; name = Generated.xcconfig; path = Flutter/Generated.xcconfig; sourceTree = "<group>"; };
+		97C146EE1CF9000F007C117D /* Runner.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = Runner.app; sourceTree = BUILT_PRODUCTS_DIR; };
+		97C146FB1CF9000F007C117D /* Base */ = {isa = PBXFileReference; lastKnownFileType = file.storyboard; name = Base; path = Base.lproj/Main.storyboard; sourceTree = "<group>"; };
+		97C146FD1CF9000F007C117D /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = "<group>"; };
+		97C147001CF9000F007C117D /* Base */ = {isa = PBXFileReference; lastKnownFileType = file.storyboard; name = Base; path = Base.lproj/LaunchScreen.storyboard; sourceTree = "<group>"; };
+		97C147021CF9000F007C117D /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
+/* End PBXFileReference section */
+
+/* Begin PBXFrameworksBuildPhase section */
+		97C146EB1CF9000F007C117D /* Frameworks */ = {
+			isa = PBXFrameworksBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXFrameworksBuildPhase section */
+
+/* Begin PBXGroup section */
+		331C8082294A63A400263BE5 /* RunnerTests */ = {
+			isa = PBXGroup;
+			children = (
+				331C807B294A618700263BE5 /* RunnerTests.swift */,
+			);
+			path = RunnerTests;
+			sourceTree = "<group>";
+		};
+		9740EEB11CF90186004384FC /* Flutter */ = {
+			isa = PBXGroup;
+			children = (
+				3B3967151E833CAA004F5970 /* AppFrameworkInfo.plist */,
+				9740EEB21CF90195004384FC /* Debug.xcconfig */,
+				7AFA3C8E1D35360C0083082E /* Release.xcconfig */,
+				9740EEB31CF90195004384FC /* Generated.xcconfig */,
+			);
+			name = Flutter;
+			sourceTree = "<group>";
+		};
+		97C146E51CF9000F007C117D = {
+			isa = PBXGroup;
+			children = (
+				9740EEB11CF90186004384FC /* Flutter */,
+				97C146F01CF9000F007C117D /* Runner */,
+				97C146EF1CF9000F007C117D /* Products */,
+				331C8082294A63A400263BE5 /* RunnerTests */,
+			);
+			sourceTree = "<group>";
+		};
+		97C146EF1CF9000F007C117D /* Products */ = {
+			isa = PBXGroup;
+			children = (
+				97C146EE1CF9000F007C117D /* Runner.app */,
+				331C8081294A63A400263BE5 /* RunnerTests.xctest */,
+			);
+			name = Products;
+			sourceTree = "<group>";
+		};
+		97C146F01CF9000F007C117D /* Runner */ = {
+			isa = PBXGroup;
+			children = (
+				97C146FA1CF9000F007C117D /* Main.storyboard */,
+				97C146FD1CF9000F007C117D /* Assets.xcassets */,
+				97C146FF1CF9000F007C117D /* LaunchScreen.storyboard */,
+				97C147021CF9000F007C117D /* Info.plist */,
+				1498D2321E8E86230040F4C2 /* GeneratedPluginRegistrant.h */,
+				1498D2331E8E89220040F4C2 /* GeneratedPluginRegistrant.m */,
+				74858FAE1ED2DC5600515810 /* AppDelegate.swift */,
+				7884E8672EC3CC0400C636F2 /* SceneDelegate.swift */,
+				74858FAD1ED2DC5600515810 /* Runner-Bridging-Header.h */,
+			);
+			path = Runner;
+			sourceTree = "<group>";
+		};
+/* End PBXGroup section */
+
+/* Begin PBXNativeTarget section */
+		331C8080294A63A400263BE5 /* RunnerTests */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = 331C8087294A63A400263BE5 /* Build configuration list for PBXNativeTarget "RunnerTests" */;
+			buildPhases = (
+				331C807D294A63A400263BE5 /* Sources */,
+				331C807F294A63A400263BE5 /* Resources */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+				331C8086294A63A400263BE5 /* PBXTargetDependency */,
+			);
+			name = RunnerTests;
+			productName = RunnerTests;
+			productReference = 331C8081294A63A400263BE5 /* RunnerTests.xctest */;
+			productType = "com.apple.product-type.bundle.unit-test";
+		};
+		97C146ED1CF9000F007C117D /* Runner */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = 97C147051CF9000F007C117D /* Build configuration list for PBXNativeTarget "Runner" */;
+			buildPhases = (
+				9740EEB61CF901F6004384FC /* Run Script */,
+				97C146EA1CF9000F007C117D /* Sources */,
+				97C146EB1CF9000F007C117D /* Frameworks */,
+				97C146EC1CF9000F007C117D /* Resources */,
+				9705A1C41CF9048500538489 /* Embed Frameworks */,
+				3B06AD1E1E4923F5004D2608 /* Thin Binary */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+			);
+			name = Runner;
+			productName = Runner;
+			productReference = 97C146EE1CF9000F007C117D /* Runner.app */;
+			productType = "com.apple.product-type.application";
+		};
+/* End PBXNativeTarget section */
+
+/* Begin PBXProject section */
+		97C146E61CF9000F007C117D /* Project object */ = {
+			isa = PBXProject;
+			attributes = {
+				BuildIndependentTargetsInParallel = YES;
+				LastUpgradeCheck = 1510;
+				ORGANIZATIONNAME = "";
+				TargetAttributes = {
+					331C8080294A63A400263BE5 = {
+						CreatedOnToolsVersion = 14.0;
+						TestTargetID = 97C146ED1CF9000F007C117D;
+					};
+					97C146ED1CF9000F007C117D = {
+						CreatedOnToolsVersion = 7.3.1;
+						LastSwiftMigration = 1100;
+					};
+				};
+			};
+			buildConfigurationList = 97C146E91CF9000F007C117D /* Build configuration list for PBXProject "Runner" */;
+			compatibilityVersion = "Xcode 9.3";
+			developmentRegion = en;
+			hasScannedForEncodings = 0;
+			knownRegions = (
+				en,
+				Base,
+			);
+			mainGroup = 97C146E51CF9000F007C117D;
+			productRefGroup = 97C146EF1CF9000F007C117D /* Products */;
+			projectDirPath = "";
+			projectRoot = "";
+			targets = (
+				97C146ED1CF9000F007C117D /* Runner */,
+				331C8080294A63A400263BE5 /* RunnerTests */,
+			);
+		};
+/* End PBXProject section */
+
+/* Begin PBXResourcesBuildPhase section */
+		331C807F294A63A400263BE5 /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+		97C146EC1CF9000F007C117D /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				97C147011CF9000F007C117D /* LaunchScreen.storyboard in Resources */,
+				3B3967161E833CAA004F5970 /* AppFrameworkInfo.plist in Resources */,
+				97C146FE1CF9000F007C117D /* Assets.xcassets in Resources */,
+				97C146FC1CF9000F007C117D /* Main.storyboard in Resources */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXResourcesBuildPhase section */
+
+/* Begin PBXShellScriptBuildPhase section */
+		3B06AD1E1E4923F5004D2608 /* Thin Binary */ = {
+			isa = PBXShellScriptBuildPhase;
+			alwaysOutOfDate = 1;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			inputPaths = (
+				"${TARGET_BUILD_DIR}/${INFOPLIST_PATH}",
+			);
+			name = "Thin Binary";
+			outputPaths = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+			shellPath = /bin/sh;
+			shellScript = "/bin/sh \"$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh\" embed_and_thin";
+		};
+		9740EEB61CF901F6004384FC /* Run Script */ = {
+			isa = PBXShellScriptBuildPhase;
+			alwaysOutOfDate = 1;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			inputPaths = (
+			);
+			name = "Run Script";
+			outputPaths = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+			shellPath = /bin/sh;
+			shellScript = "/bin/sh \"$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh\" build";
+		};
+/* End PBXShellScriptBuildPhase section */
+
+/* Begin PBXSourcesBuildPhase section */
+		331C807D294A63A400263BE5 /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				331C808B294A63AB00263BE5 /* RunnerTests.swift in Sources */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+		97C146EA1CF9000F007C117D /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				74858FAF1ED2DC5600515810 /* AppDelegate.swift in Sources */,
+				1498D2341E8E89220040F4C2 /* GeneratedPluginRegistrant.m in Sources */,
+				7884E8682EC3CC0700C636F2 /* SceneDelegate.swift in Sources */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXSourcesBuildPhase section */
+
+/* Begin PBXTargetDependency section */
+		331C8086294A63A400263BE5 /* PBXTargetDependency */ = {
+			isa = PBXTargetDependency;
+			target = 97C146ED1CF9000F007C117D /* Runner */;
+			targetProxy = 331C8085294A63A400263BE5 /* PBXContainerItemProxy */;
+		};
+/* End PBXTargetDependency section */
+
+/* Begin PBXVariantGroup section */
+		97C146FA1CF9000F007C117D /* Main.storyboard */ = {
+			isa = PBXVariantGroup;
+			children = (
+				97C146FB1CF9000F007C117D /* Base */,
+			);
+			name = Main.storyboard;
+			sourceTree = "<group>";
+		};
+		97C146FF1CF9000F007C117D /* LaunchScreen.storyboard */ = {
+			isa = PBXVariantGroup;
+			children = (
+				97C147001CF9000F007C117D /* Base */,
+			);
+			name = LaunchScreen.storyboard;
+			sourceTree = "<group>";
+		};
+/* End PBXVariantGroup section */
+
+/* Begin XCBuildConfiguration section */
+		249021D3217E4FDB00AE95B9 /* Profile */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ALWAYS_SEARCH_USER_PATHS = NO;
+				ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES;
+				CLANG_ANALYZER_NONNULL = YES;
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++0x";
+				CLANG_CXX_LIBRARY = "libc++";
+				CLANG_ENABLE_MODULES = YES;
+				CLANG_ENABLE_OBJC_ARC = YES;
+				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+				CLANG_WARN_BOOL_CONVERSION = YES;
+				CLANG_WARN_COMMA = YES;
+				CLANG_WARN_CONSTANT_CONVERSION = YES;
+				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+				CLANG_WARN_EMPTY_BODY = YES;
+				CLANG_WARN_ENUM_CONVERSION = YES;
+				CLANG_WARN_INFINITE_RECURSION = YES;
+				CLANG_WARN_INT_CONVERSION = YES;
+				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+				CLANG_WARN_STRICT_PROTOTYPES = YES;
+				CLANG_WARN_SUSPICIOUS_MOVE = YES;
+				CLANG_WARN_UNREACHABLE_CODE = YES;
+				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+				"CODE_SIGN_IDENTITY[sdk=iphoneos*]" = "iPhone Developer";
+				COPY_PHASE_STRIP = NO;
+				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
+				ENABLE_NS_ASSERTIONS = NO;
+				ENABLE_STRICT_OBJC_MSGSEND = YES;
+				ENABLE_USER_SCRIPT_SANDBOXING = NO;
+				GCC_C_LANGUAGE_STANDARD = gnu99;
+				GCC_NO_COMMON_BLOCKS = YES;
+				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+				GCC_WARN_UNDECLARED_SELECTOR = YES;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+				GCC_WARN_UNUSED_FUNCTION = YES;
+				GCC_WARN_UNUSED_VARIABLE = YES;
+				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
+				MTL_ENABLE_DEBUG_INFO = NO;
+				SDKROOT = iphoneos;
+				SUPPORTED_PLATFORMS = iphoneos;
+				TARGETED_DEVICE_FAMILY = "1,2";
+				VALIDATE_PRODUCT = YES;
+			};
+			name = Profile;
+		};
+		249021D4217E4FDB00AE95B9 /* Profile */ = {
+			isa = XCBuildConfiguration;
+			baseConfigurationReference = 7AFA3C8E1D35360C0083082E /* Release.xcconfig */;
+			buildSettings = {
+				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				CLANG_ENABLE_MODULES = YES;
+				CURRENT_PROJECT_VERSION = "$(FLUTTER_BUILD_NUMBER)";
+				DEVELOPMENT_TEAM = Y98YFL3B2W;
+				ENABLE_BITCODE = NO;
+				INFOPLIST_FILE = Runner/Info.plist;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+				);
+				PRODUCT_BUNDLE_IDENTIFIER = com.example.relationshipSaver;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SWIFT_OBJC_BRIDGING_HEADER = "Runner/Runner-Bridging-Header.h";
+				SWIFT_VERSION = 5.0;
+				VERSIONING_SYSTEM = "apple-generic";
+			};
+			name = Profile;
+		};
+		331C8088294A63A400263BE5 /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				BUNDLE_LOADER = "$(TEST_HOST)";
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				GENERATE_INFOPLIST_FILE = YES;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = com.example.relationshipSaver.RunnerTests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
+				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
+				SWIFT_VERSION = 5.0;
+				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/Runner.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/Runner";
+			};
+			name = Debug;
+		};
+		331C8089294A63A400263BE5 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				BUNDLE_LOADER = "$(TEST_HOST)";
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				GENERATE_INFOPLIST_FILE = YES;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = com.example.relationshipSaver.RunnerTests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SWIFT_VERSION = 5.0;
+				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/Runner.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/Runner";
+			};
+			name = Release;
+		};
+		331C808A294A63A400263BE5 /* Profile */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				BUNDLE_LOADER = "$(TEST_HOST)";
+				CODE_SIGN_STYLE = Automatic;
+				CURRENT_PROJECT_VERSION = 1;
+				GENERATE_INFOPLIST_FILE = YES;
+				MARKETING_VERSION = 1.0;
+				PRODUCT_BUNDLE_IDENTIFIER = com.example.relationshipSaver.RunnerTests;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SWIFT_VERSION = 5.0;
+				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/Runner.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/Runner";
+			};
+			name = Profile;
+		};
+		97C147031CF9000F007C117D /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ALWAYS_SEARCH_USER_PATHS = NO;
+				ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES;
+				CLANG_ANALYZER_NONNULL = YES;
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++0x";
+				CLANG_CXX_LIBRARY = "libc++";
+				CLANG_ENABLE_MODULES = YES;
+				CLANG_ENABLE_OBJC_ARC = YES;
+				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+				CLANG_WARN_BOOL_CONVERSION = YES;
+				CLANG_WARN_COMMA = YES;
+				CLANG_WARN_CONSTANT_CONVERSION = YES;
+				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+				CLANG_WARN_EMPTY_BODY = YES;
+				CLANG_WARN_ENUM_CONVERSION = YES;
+				CLANG_WARN_INFINITE_RECURSION = YES;
+				CLANG_WARN_INT_CONVERSION = YES;
+				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+				CLANG_WARN_STRICT_PROTOTYPES = YES;
+				CLANG_WARN_SUSPICIOUS_MOVE = YES;
+				CLANG_WARN_UNREACHABLE_CODE = YES;
+				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+				"CODE_SIGN_IDENTITY[sdk=iphoneos*]" = "iPhone Developer";
+				COPY_PHASE_STRIP = NO;
+				DEBUG_INFORMATION_FORMAT = dwarf;
+				ENABLE_STRICT_OBJC_MSGSEND = YES;
+				ENABLE_TESTABILITY = YES;
+				ENABLE_USER_SCRIPT_SANDBOXING = NO;
+				GCC_C_LANGUAGE_STANDARD = gnu99;
+				GCC_DYNAMIC_NO_PIC = NO;
+				GCC_NO_COMMON_BLOCKS = YES;
+				GCC_OPTIMIZATION_LEVEL = 0;
+				GCC_PREPROCESSOR_DEFINITIONS = (
+					"DEBUG=1",
+					"$(inherited)",
+				);
+				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+				GCC_WARN_UNDECLARED_SELECTOR = YES;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+				GCC_WARN_UNUSED_FUNCTION = YES;
+				GCC_WARN_UNUSED_VARIABLE = YES;
+				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
+				MTL_ENABLE_DEBUG_INFO = YES;
+				ONLY_ACTIVE_ARCH = YES;
+				SDKROOT = iphoneos;
+				TARGETED_DEVICE_FAMILY = "1,2";
+			};
+			name = Debug;
+		};
+		97C147041CF9000F007C117D /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ALWAYS_SEARCH_USER_PATHS = NO;
+				ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES;
+				CLANG_ANALYZER_NONNULL = YES;
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++0x";
+				CLANG_CXX_LIBRARY = "libc++";
+				CLANG_ENABLE_MODULES = YES;
+				CLANG_ENABLE_OBJC_ARC = YES;
+				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+				CLANG_WARN_BOOL_CONVERSION = YES;
+				CLANG_WARN_COMMA = YES;
+				CLANG_WARN_CONSTANT_CONVERSION = YES;
+				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+				CLANG_WARN_EMPTY_BODY = YES;
+				CLANG_WARN_ENUM_CONVERSION = YES;
+				CLANG_WARN_INFINITE_RECURSION = YES;
+				CLANG_WARN_INT_CONVERSION = YES;
+				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+				CLANG_WARN_STRICT_PROTOTYPES = YES;
+				CLANG_WARN_SUSPICIOUS_MOVE = YES;
+				CLANG_WARN_UNREACHABLE_CODE = YES;
+				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+				"CODE_SIGN_IDENTITY[sdk=iphoneos*]" = "iPhone Developer";
+				COPY_PHASE_STRIP = NO;
+				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
+				ENABLE_NS_ASSERTIONS = NO;
+				ENABLE_STRICT_OBJC_MSGSEND = YES;
+				ENABLE_USER_SCRIPT_SANDBOXING = NO;
+				GCC_C_LANGUAGE_STANDARD = gnu99;
+				GCC_NO_COMMON_BLOCKS = YES;
+				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+				GCC_WARN_UNDECLARED_SELECTOR = YES;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+				GCC_WARN_UNUSED_FUNCTION = YES;
+				GCC_WARN_UNUSED_VARIABLE = YES;
+				IPHONEOS_DEPLOYMENT_TARGET = 13.0;
+				MTL_ENABLE_DEBUG_INFO = NO;
+				SDKROOT = iphoneos;
+				SUPPORTED_PLATFORMS = iphoneos;
+				SWIFT_COMPILATION_MODE = wholemodule;
+				SWIFT_OPTIMIZATION_LEVEL = "-O";
+				TARGETED_DEVICE_FAMILY = "1,2";
+				VALIDATE_PRODUCT = YES;
+			};
+			name = Release;
+		};
+		97C147061CF9000F007C117D /* Debug */ = {
+			isa = XCBuildConfiguration;
+			baseConfigurationReference = 9740EEB21CF90195004384FC /* Debug.xcconfig */;
+			buildSettings = {
+				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				CLANG_ENABLE_MODULES = YES;
+				CURRENT_PROJECT_VERSION = "$(FLUTTER_BUILD_NUMBER)";
+				DEVELOPMENT_TEAM = Y98YFL3B2W;
+				ENABLE_BITCODE = NO;
+				INFOPLIST_FILE = Runner/Info.plist;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+				);
+				PRODUCT_BUNDLE_IDENTIFIER = com.example.relationshipSaver;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SWIFT_OBJC_BRIDGING_HEADER = "Runner/Runner-Bridging-Header.h";
+				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
+				SWIFT_VERSION = 5.0;
+				VERSIONING_SYSTEM = "apple-generic";
+			};
+			name = Debug;
+		};
+		97C147071CF9000F007C117D /* Release */ = {
+			isa = XCBuildConfiguration;
+			baseConfigurationReference = 7AFA3C8E1D35360C0083082E /* Release.xcconfig */;
+			buildSettings = {
+				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				CLANG_ENABLE_MODULES = YES;
+				CURRENT_PROJECT_VERSION = "$(FLUTTER_BUILD_NUMBER)";
+				DEVELOPMENT_TEAM = Y98YFL3B2W;
+				ENABLE_BITCODE = NO;
+				INFOPLIST_FILE = Runner/Info.plist;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+				);
+				PRODUCT_BUNDLE_IDENTIFIER = com.example.relationshipSaver;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				SWIFT_OBJC_BRIDGING_HEADER = "Runner/Runner-Bridging-Header.h";
+				SWIFT_VERSION = 5.0;
+				VERSIONING_SYSTEM = "apple-generic";
+			};
+			name = Release;
+		};
+/* End XCBuildConfiguration section */
+
+/* Begin XCConfigurationList section */
+		331C8087294A63A400263BE5 /* Build configuration list for PBXNativeTarget "RunnerTests" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				331C8088294A63A400263BE5 /* Debug */,
+				331C8089294A63A400263BE5 /* Release */,
+				331C808A294A63A400263BE5 /* Profile */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
+		97C146E91CF9000F007C117D /* Build configuration list for PBXProject "Runner" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				97C147031CF9000F007C117D /* Debug */,
+				97C147041CF9000F007C117D /* Release */,
+				249021D3217E4FDB00AE95B9 /* Profile */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
+		97C147051CF9000F007C117D /* Build configuration list for PBXNativeTarget "Runner" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				97C147061CF9000F007C117D /* Debug */,
+				97C147071CF9000F007C117D /* Release */,
+				249021D4217E4FDB00AE95B9 /* Profile */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Release;
+		};
+/* End XCConfigurationList section */
+	};
+	rootObject = 97C146E61CF9000F007C117D /* Project object */;
+}
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Workspace
+   version = "1.0">
+   <FileRef
+      location = "self:">
+   </FileRef>
+</Workspace>
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>IDEDidComputeMac32BitWarning</key>
+	<true/>
+</dict>
+</plist>
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>PreviewsEnabled</key>
+	<false/>
+</dict>
+</plist>
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1510"
+   version = "1.3">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "97C146ED1CF9000F007C117D"
+               BuildableName = "Runner.app"
+               BlueprintName = "Runner"
+               ReferencedContainer = "container:Runner.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      customLLDBInitFile = "$(SRCROOT)/Flutter/ephemeral/flutter_lldbinit"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "97C146ED1CF9000F007C117D"
+            BuildableName = "Runner.app"
+            BlueprintName = "Runner"
+            ReferencedContainer = "container:Runner.xcodeproj">
+         </BuildableReference>
+      </MacroExpansion>
+      <Testables>
+         <TestableReference
+            skipped = "NO"
+            parallelizable = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "331C8080294A63A400263BE5"
+               BuildableName = "RunnerTests.xctest"
+               BlueprintName = "RunnerTests"
+               ReferencedContainer = "container:Runner.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      customLLDBInitFile = "$(SRCROOT)/Flutter/ephemeral/flutter_lldbinit"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      enableGPUValidationMode = "1"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "97C146ED1CF9000F007C117D"
+            BuildableName = "Runner.app"
+            BlueprintName = "Runner"
+            ReferencedContainer = "container:Runner.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Profile"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "97C146ED1CF9000F007C117D"
+            BuildableName = "Runner.app"
+            BlueprintName = "Runner"
+            ReferencedContainer = "container:Runner.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Workspace
+   version = "1.0">
+   <FileRef
+      location = "group:Runner.xcodeproj">
+   </FileRef>
+</Workspace>
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>IDEDidComputeMac32BitWarning</key>
+	<true/>
+</dict>
+</plist>
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>PreviewsEnabled</key>
+	<false/>
+</dict>
+</plist>
@@ -0,0 +1,16 @@
+import Flutter
+import UIKit
+
+@main
+@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
+  override func application(
+    _ application: UIApplication,
+    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+  ) -> Bool {
+    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+  }
+
+  func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
+    GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
+  }
+}
@@ -0,0 +1,122 @@
+{
+  "images" : [
+    {
+      "size" : "20x20",
+      "idiom" : "iphone",
+      "filename" : "Icon-App-20x20@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "size" : "20x20",
+      "idiom" : "iphone",
+      "filename" : "Icon-App-20x20@3x.png",
+      "scale" : "3x"
+    },
+    {
+      "size" : "29x29",
+      "idiom" : "iphone",
+      "filename" : "Icon-App-29x29@1x.png",
+      "scale" : "1x"
+    },
+    {
+      "size" : "29x29",
+      "idiom" : "iphone",
+      "filename" : "Icon-App-29x29@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "size" : "29x29",
+      "idiom" : "iphone",
+      "filename" : "Icon-App-29x29@3x.png",
+      "scale" : "3x"
+    },
+    {
+      "size" : "40x40",
+      "idiom" : "iphone",
+      "filename" : "Icon-App-40x40@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "size" : "40x40",
+      "idiom" : "iphone",
+      "filename" : "Icon-App-40x40@3x.png",
+      "scale" : "3x"
+    },
+    {
+      "size" : "60x60",
+      "idiom" : "iphone",
+      "filename" : "Icon-App-60x60@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "size" : "60x60",
+      "idiom" : "iphone",
+      "filename" : "Icon-App-60x60@3x.png",
+      "scale" : "3x"
+    },
+    {
+      "size" : "20x20",
+      "idiom" : "ipad",
+      "filename" : "Icon-App-20x20@1x.png",
+      "scale" : "1x"
+    },
+    {
+      "size" : "20x20",
+      "idiom" : "ipad",
+      "filename" : "Icon-App-20x20@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "size" : "29x29",
+      "idiom" : "ipad",
+      "filename" : "Icon-App-29x29@1x.png",
+      "scale" : "1x"
+    },
+    {
+      "size" : "29x29",
+      "idiom" : "ipad",
+      "filename" : "Icon-App-29x29@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "size" : "40x40",
+      "idiom" : "ipad",
+      "filename" : "Icon-App-40x40@1x.png",
+      "scale" : "1x"
+    },
+    {
+      "size" : "40x40",
+      "idiom" : "ipad",
+      "filename" : "Icon-App-40x40@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "size" : "76x76",
+      "idiom" : "ipad",
+      "filename" : "Icon-App-76x76@1x.png",
+      "scale" : "1x"
+    },
+    {
+      "size" : "76x76",
+      "idiom" : "ipad",
+      "filename" : "Icon-App-76x76@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "size" : "83.5x83.5",
+      "idiom" : "ipad",
+      "filename" : "Icon-App-83.5x83.5@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "size" : "1024x1024",
+      "idiom" : "ios-marketing",
+      "filename" : "Icon-App-1024x1024@1x.png",
+      "scale" : "1x"
+    }
+  ],
+  "info" : {
+    "version" : 1,
+    "author" : "xcode"
+  }
+}
@@ -0,0 +1,23 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "filename" : "LaunchImage.png",
+      "scale" : "1x"
+    },
+    {
+      "idiom" : "universal",
+      "filename" : "LaunchImage@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "idiom" : "universal",
+      "filename" : "LaunchImage@3x.png",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "version" : 1,
+    "author" : "xcode"
+  }
+}
@@ -0,0 +1,5 @@
+# Launch Screen Assets
+
+You can customize the launch screen with your own desired assets by replacing the image files in this directory.
+
+You can also do it by opening your Flutter project's Xcode project with `open ios/Runner.xcworkspace`, selecting `Runner/Assets.xcassets` in the Project Navigator and dropping in the desired images.
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="12121" systemVersion="16G29" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" launchScreen="YES" colorMatched="YES" initialViewController="01J-lp-oVM">
+    <dependencies>
+        <deployment identifier="iOS"/>
+        <plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="12089"/>
+    </dependencies>
+    <scenes>
+        <!--View Controller-->
+        <scene sceneID="EHf-IW-A2E">
+            <objects>
+                <viewController id="01J-lp-oVM" sceneMemberID="viewController">
+                    <layoutGuides>
+                        <viewControllerLayoutGuide type="top" id="Ydg-fD-yQy"/>
+                        <viewControllerLayoutGuide type="bottom" id="xbc-2k-c8Z"/>
+                    </layoutGuides>
+                    <view key="view" contentMode="scaleToFill" id="Ze5-6b-2t3">
+                        <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>
+                        <subviews>
+                            <imageView opaque="NO" clipsSubviews="YES" multipleTouchEnabled="YES" contentMode="center" image="LaunchImage" translatesAutoresizingMaskIntoConstraints="NO" id="YRO-k0-Ey4">
+                            </imageView>
+                        </subviews>
+                        <color key="backgroundColor" red="1" green="1" blue="1" alpha="1" colorSpace="custom" customColorSpace="sRGB"/>
+                        <constraints>
+                            <constraint firstItem="YRO-k0-Ey4" firstAttribute="centerX" secondItem="Ze5-6b-2t3" secondAttribute="centerX" id="1a2-6s-vTC"/>
+                            <constraint firstItem="YRO-k0-Ey4" firstAttribute="centerY" secondItem="Ze5-6b-2t3" secondAttribute="centerY" id="4X2-HB-R7a"/>
+                        </constraints>
+                    </view>
+                </viewController>
+                <placeholder placeholderIdentifier="IBFirstResponder" id="iYj-Kq-Ea1" userLabel="First Responder" sceneMemberID="firstResponder"/>
+            </objects>
+            <point key="canvasLocation" x="53" y="375"/>
+        </scene>
+    </scenes>
+    <resources>
+        <image name="LaunchImage" width="168" height="185"/>
+    </resources>
+</document>
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="10117" systemVersion="15F34" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" useTraitCollections="YES" initialViewController="BYZ-38-t0r">
+    <dependencies>
+        <deployment identifier="iOS"/>
+        <plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="10085"/>
+    </dependencies>
+    <scenes>
+        <!--Flutter View Controller-->
+        <scene sceneID="tne-QT-ifu">
+            <objects>
+                <viewController id="BYZ-38-t0r" customClass="FlutterViewController" sceneMemberID="viewController">
+                    <layoutGuides>
+                        <viewControllerLayoutGuide type="top" id="y3c-jy-aDJ"/>
+                        <viewControllerLayoutGuide type="bottom" id="wfy-db-euE"/>
+                    </layoutGuides>
+                    <view key="view" contentMode="scaleToFill" id="8bC-Xf-vdC">
+                        <rect key="frame" x="0.0" y="0.0" width="600" height="600"/>
+                        <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>
+                        <color key="backgroundColor" white="1" alpha="1" colorSpace="custom" customColorSpace="calibratedWhite"/>
+                    </view>
+                </viewController>
+                <placeholder placeholderIdentifier="IBFirstResponder" id="dkx-z0-nzr" sceneMemberID="firstResponder"/>
+            </objects>
+        </scene>
+    </scenes>
+</document>
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CADisableMinimumFrameDurationOnPhone</key>
+	<true/>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>Relationship Saver</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>relationship_saver</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>CFBundleShortVersionString</key>
+	<string>$(FLUTTER_BUILD_NAME)</string>
+	<key>CFBundleSignature</key>
+	<string>????</string>
+	<key>CFBundleVersion</key>
+	<string>$(FLUTTER_BUILD_NUMBER)</string>
+	<key>LSRequiresIPhoneOS</key>
+	<true/>
+	<key>UIApplicationSceneManifest</key>
+	<dict>
+		<key>UIApplicationSupportsMultipleScenes</key>
+		<false/>
+		<key>UISceneConfigurations</key>
+		<dict>
+			<key>UIWindowSceneSessionRoleApplication</key>
+			<array>
+				<dict>
+					<key>UISceneClassName</key>
+					<string>UIWindowScene</string>
+					<key>UISceneConfigurationName</key>
+					<string>flutter</string>
+					<key>UISceneDelegateClassName</key>
+					<string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
+					<key>UISceneStoryboardFile</key>
+					<string>Main</string>
+				</dict>
+			</array>
+		</dict>
+	</dict>
+	<key>UIApplicationSupportsIndirectInputEvents</key>
+	<true/>
+	<key>UILaunchStoryboardName</key>
+	<string>LaunchScreen</string>
+	<key>UIMainStoryboardFile</key>
+	<string>Main</string>
+	<key>UISupportedInterfaceOrientations</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
+	</array>
+	<key>UISupportedInterfaceOrientations~ipad</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+		<string>UIInterfaceOrientationPortraitUpsideDown</string>
+		<string>UIInterfaceOrientationLandscapeLeft</string>
+		<string>UIInterfaceOrientationLandscapeRight</string>
+	</array>
+</dict>
+</plist>
@@ -0,0 +1 @@
+#import "GeneratedPluginRegistrant.h"
@@ -0,0 +1,6 @@
+import Flutter
+import UIKit
+
+class SceneDelegate: FlutterSceneDelegate {
+
+}
@@ -0,0 +1,12 @@
+import Flutter
+import UIKit
+import XCTest
+
+class RunnerTests: XCTestCase {
+
+  func testExample() {
+    // If you add code to the Runner application, consider adding tests here.
+    // See https://developer.apple.com/documentation/xctest for more information about using XCTest.
+  }
+
+}
@@ -0,0 +1,20 @@
+import 'package:relationship_saver/core/auth/token_store.dart';
+import 'package:relationship_saver/integrations/backend/models/backend_models.dart';
+
+/// Simple in-memory [TokenStore] used in tests and local fakes.
+class InMemoryTokenStore implements TokenStore {
+  AuthSession? _session;
+
+  @override
+  Future<void> clear() async {
+    _session = null;
+  }
+
+  @override
+  Future<AuthSession?> read() async => _session;
+
+  @override
+  Future<void> write(AuthSession session) async {
+    _session = session;
+  }
+}
@@ -0,0 +1,39 @@
+import 'dart:convert';
+
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import 'package:relationship_saver/core/auth/token_store.dart';
+import 'package:relationship_saver/integrations/backend/models/backend_models.dart';
+
+/// [TokenStore] backed by platform secure storage.
+class SecureTokenStore implements TokenStore {
+  SecureTokenStore({FlutterSecureStorage? storage})
+    : _storage = storage ?? const FlutterSecureStorage();
+
+  static const String _sessionKey = 'backend_auth_session_v1';
+  final FlutterSecureStorage _storage;
+
+  @override
+  Future<AuthSession?> read() async {
+    final String? raw = await _storage.read(key: _sessionKey);
+    if (raw == null || raw.isEmpty) {
+      return null;
+    }
+
+    try {
+      final Map<String, dynamic> json = jsonDecode(raw) as Map<String, dynamic>;
+      return AuthSession.fromJson(json);
+    } on FormatException {
+      await clear();
+      return null;
+    }
+  }
+
+  @override
+  Future<void> write(AuthSession session) async {
+    final String raw = jsonEncode(session.toJson());
+    await _storage.write(key: _sessionKey, value: raw);
+  }
+
+  @override
+  Future<void> clear() => _storage.delete(key: _sessionKey);
+}
@@ -0,0 +1,13 @@
+import 'package:relationship_saver/integrations/backend/models/backend_models.dart';
+
+/// Session token persistence abstraction.
+abstract interface class TokenStore {
+  /// Reads the current session, if any.
+  Future<AuthSession?> read();
+
+  /// Persists a full auth session.
+  Future<void> write(AuthSession session);
+
+  /// Clears all stored auth state.
+  Future<void> clear();
+}
@@ -0,0 +1,29 @@
+/// Application-level runtime configuration.
+class AppConfig {
+  AppConfig._();
+
+  static const String _defaultBaseUrl = String.fromEnvironment(
+    'BACKEND_BASE_URL',
+    defaultValue: 'https://api.example.com',
+  );
+
+  static String? _baseUrlOverride;
+
+  /// Returns the configured backend base URL.
+  static String get backendBaseUrl {
+    final String? override = _baseUrlOverride;
+    if (override != null && override.trim().isNotEmpty) {
+      return override.trim();
+    }
+    return _defaultBaseUrl;
+  }
+
+  /// Enables fake backend implementation for local/offline development.
+  static bool get useFakeBackend =>
+      const bool.fromEnvironment('USE_FAKE_BACKEND', defaultValue: false);
+
+  /// Runtime override for backend URL (e.g. local settings screen).
+  static void overrideBackendBaseUrl(String? baseUrl) {
+    _baseUrlOverride = baseUrl;
+  }
+}
@@ -0,0 +1,34 @@
+import 'package:flutter/material.dart';
+
+/// Shared app theme, aligned with the visual tone of the reference templates.
+class AppTheme {
+  AppTheme._();
+
+  static const Color background = Color(0xFFEDF0F2);
+  static const Color surface = Color(0xFFFFFFFF);
+  static const Color primary = Color(0xFF253840);
+  static const Color accent = Color(0xFF00B6F0);
+
+  /// Builds the Material [ThemeData].
+  static ThemeData light() {
+    final ColorScheme colorScheme = ColorScheme.fromSeed(
+      seedColor: primary,
+      primary: primary,
+      secondary: accent,
+      surface: surface,
+      brightness: Brightness.light,
+    );
+
+    return ThemeData(
+      useMaterial3: true,
+      colorScheme: colorScheme,
+      scaffoldBackgroundColor: background,
+      appBarTheme: const AppBarTheme(
+        centerTitle: false,
+        backgroundColor: surface,
+        foregroundColor: primary,
+        elevation: 0,
+      ),
+    );
+  }
+}
@@ -0,0 +1,127 @@
+/// Base exception type for backend-facing failures.
+sealed class BackendException implements Exception {
+  const BackendException(
+    this.message, {
+    this.statusCode,
+    this.requestId,
+    this.backendCode,
+  });
+
+  /// Human-readable message suitable for diagnostics.
+  final String message;
+
+  /// HTTP status code if available.
+  final int? statusCode;
+
+  /// Correlation/request identifier emitted by backend or gateway.
+  final String? requestId;
+
+  /// Structured backend error code if provided by server.
+  final String? backendCode;
+
+  @override
+  String toString() {
+    return 'BackendException(message: $message, statusCode: $statusCode, '
+        'requestId: $requestId, backendCode: $backendCode)';
+  }
+}
+
+/// No HTTP response was received due to connectivity issues.
+final class NetworkException extends BackendException {
+  const NetworkException(
+    super.message, {
+    super.statusCode,
+    super.requestId,
+    super.backendCode,
+  });
+}
+
+/// Request timed out at connect/send/receive stage.
+final class TimeoutException extends BackendException {
+  const TimeoutException(
+    super.message, {
+    super.statusCode,
+    super.requestId,
+    super.backendCode,
+  });
+}
+
+/// Backend rejected request due to missing/invalid auth.
+class UnauthorizedException extends BackendException {
+  const UnauthorizedException(
+    super.message, {
+    super.statusCode,
+    super.requestId,
+    super.backendCode,
+  });
+}
+
+/// Session is no longer valid and refresh failed.
+final class AuthExpiredException extends UnauthorizedException {
+  const AuthExpiredException(
+    super.message, {
+    super.statusCode,
+    super.requestId,
+    super.backendCode,
+  });
+}
+
+/// Caller is authenticated but lacks permissions.
+final class ForbiddenException extends BackendException {
+  const ForbiddenException(
+    super.message, {
+    super.statusCode,
+    super.requestId,
+    super.backendCode,
+  });
+}
+
+/// Resource was not found.
+final class NotFoundException extends BackendException {
+  const NotFoundException(
+    super.message, {
+    super.statusCode,
+    super.requestId,
+    super.backendCode,
+  });
+}
+
+/// Backend rate-limited the request.
+final class RateLimitedException extends BackendException {
+  const RateLimitedException(
+    super.message, {
+    super.statusCode,
+    super.requestId,
+    super.backendCode,
+  });
+}
+
+/// 5xx backend failure.
+final class ServerException extends BackendException {
+  const ServerException(
+    super.message, {
+    super.statusCode,
+    super.requestId,
+    super.backendCode,
+  });
+}
+
+/// Request was syntactically valid but semantically invalid.
+final class ValidationException extends BackendException {
+  const ValidationException(
+    super.message, {
+    super.statusCode,
+    super.requestId,
+    super.backendCode,
+  });
+}
+
+/// Fallback for failures that do not map to a known category.
+final class UnknownBackendException extends BackendException {
+  const UnknownBackendException(
+    super.message, {
+    super.statusCode,
+    super.requestId,
+    super.backendCode,
+  });
+}
@@ -0,0 +1,171 @@
+import 'package:dio/dio.dart';
+
+import 'package:relationship_saver/core/network/backend_exception.dart';
+import 'package:relationship_saver/core/network/network_constants.dart';
+
+/// Maps Dio transport errors into typed [BackendException] failures.
+BackendException mapDioException(DioException error) {
+  final Object? embeddedError = error.error;
+  if (embeddedError is BackendException) {
+    return embeddedError;
+  }
+
+  final Response<dynamic>? response = error.response;
+  final int? statusCode = response?.statusCode;
+  final Map<String, dynamic>? responseMap = _asMapOrNull(response?.data);
+  final String? requestId = _extractRequestId(response, responseMap);
+  final String? backendCode = _extractBackendCode(responseMap);
+  final String message = _extractMessage(responseMap, error.message);
+
+  switch (error.type) {
+    case DioExceptionType.connectionTimeout:
+    case DioExceptionType.sendTimeout:
+    case DioExceptionType.receiveTimeout:
+      return TimeoutException(
+        message,
+        statusCode: statusCode,
+        requestId: requestId,
+        backendCode: backendCode,
+      );
+    case DioExceptionType.connectionError:
+      return NetworkException(
+        message,
+        statusCode: statusCode,
+        requestId: requestId,
+        backendCode: backendCode,
+      );
+    case DioExceptionType.badResponse:
+      if (statusCode == null) {
+        return UnknownBackendException(
+          message,
+          requestId: requestId,
+          backendCode: backendCode,
+        );
+      }
+      if (statusCode == 400 || statusCode == 422) {
+        return ValidationException(
+          message,
+          statusCode: statusCode,
+          requestId: requestId,
+          backendCode: backendCode,
+        );
+      }
+      if (statusCode == 401) {
+        return UnauthorizedException(
+          message,
+          statusCode: statusCode,
+          requestId: requestId,
+          backendCode: backendCode,
+        );
+      }
+      if (statusCode == 403) {
+        return ForbiddenException(
+          message,
+          statusCode: statusCode,
+          requestId: requestId,
+          backendCode: backendCode,
+        );
+      }
+      if (statusCode == 404) {
+        return NotFoundException(
+          message,
+          statusCode: statusCode,
+          requestId: requestId,
+          backendCode: backendCode,
+        );
+      }
+      if (statusCode == 429) {
+        return RateLimitedException(
+          message,
+          statusCode: statusCode,
+          requestId: requestId,
+          backendCode: backendCode,
+        );
+      }
+      if (statusCode >= 500 && statusCode < 600) {
+        return ServerException(
+          message,
+          statusCode: statusCode,
+          requestId: requestId,
+          backendCode: backendCode,
+        );
+      }
+      return UnknownBackendException(
+        message,
+        statusCode: statusCode,
+        requestId: requestId,
+        backendCode: backendCode,
+      );
+    case DioExceptionType.cancel:
+    case DioExceptionType.badCertificate:
+    case DioExceptionType.unknown:
+      return UnknownBackendException(
+        message,
+        statusCode: statusCode,
+        requestId: requestId,
+        backendCode: backendCode,
+      );
+  }
+}
+
+Map<String, dynamic>? _asMapOrNull(Object? value) {
+  if (value is Map<String, dynamic>) {
+    return value;
+  }
+  if (value is Map<Object?, Object?>) {
+    return value.map<String, dynamic>(
+      (Object? key, Object? val) => MapEntry(key.toString(), val),
+    );
+  }
+  return null;
+}
+
+String? _extractRequestId(
+  Response<dynamic>? response,
+  Map<String, dynamic>? responseMap,
+) {
+  final List<String>? fromHeader =
+      response?.headers.map[NetworkConstants.requestIdHeader.toLowerCase()] ??
+      response?.headers.map[NetworkConstants.requestIdHeader];
+  if (fromHeader != null && fromHeader.isNotEmpty) {
+    return fromHeader.first;
+  }
+
+  final Object? requestId =
+      responseMap?['requestId'] ?? responseMap?['request_id'];
+  if (requestId is String && requestId.trim().isNotEmpty) {
+    return requestId;
+  }
+  return null;
+}
+
+String? _extractBackendCode(Map<String, dynamic>? responseMap) {
+  final Object? directCode = responseMap?['code'];
+  if (directCode is String) {
+    return directCode;
+  }
+
+  final Map<String, dynamic>? error = _asMapOrNull(responseMap?['error']);
+  final Object? nestedCode = error?['code'];
+  if (nestedCode is String) {
+    return nestedCode;
+  }
+  return null;
+}
+
+String _extractMessage(Map<String, dynamic>? responseMap, String? fallback) {
+  final Object? direct = responseMap?['message'];
+  if (direct is String && direct.trim().isNotEmpty) {
+    return direct;
+  }
+
+  final Map<String, dynamic>? error = _asMapOrNull(responseMap?['error']);
+  final Object? nested = error?['message'];
+  if (nested is String && nested.trim().isNotEmpty) {
+    return nested;
+  }
+
+  return fallback?.trim().isNotEmpty == true
+      ? fallback!.trim()
+      : 'Backend request failed';
+}
@@ -0,0 +1,55 @@
+import 'package:clock/clock.dart';
+import 'package:dio/dio.dart';
+import 'package:relationship_saver/core/auth/token_store.dart';
+import 'package:relationship_saver/core/network/interceptors/auth_interceptor.dart';
+import 'package:relationship_saver/core/network/interceptors/refresh_token_interceptor.dart';
+import 'package:relationship_saver/core/network/interceptors/request_metadata_interceptor.dart';
+import 'package:relationship_saver/core/network/interceptors/retry_interceptor.dart';
+import 'package:uuid/uuid.dart';
+
+/// Builds configured Dio clients for backend integration.
+class DioFactory {
+  DioFactory._();
+
+  /// Creates Dio client with auth, retry, and refresh handling.
+  static Dio create({
+    required String baseUrl,
+    required TokenStore tokenStore,
+    Uuid? uuid,
+    Clock? clock,
+    HttpClientAdapter? httpClientAdapter,
+  }) {
+    final BaseOptions options = BaseOptions(
+      baseUrl: baseUrl,
+      connectTimeout: const Duration(seconds: 10),
+      sendTimeout: const Duration(seconds: 10),
+      receiveTimeout: const Duration(seconds: 15),
+      headers: const <String, String>{
+        'Accept': 'application/json',
+        'Content-Type': 'application/json',
+      },
+    );
+
+    final Dio dio = Dio(options);
+    final Dio refreshDio = Dio(options);
+
+    if (httpClientAdapter != null) {
+      dio.httpClientAdapter = httpClientAdapter;
+      refreshDio.httpClientAdapter = httpClientAdapter;
+    }
+
+    dio.interceptors.addAll(<Interceptor>[
+      RequestMetadataInterceptor(uuid: uuid),
+      AuthInterceptor(tokenStore: tokenStore),
+      RefreshTokenInterceptor(
+        dio: dio,
+        refreshDio: refreshDio,
+        tokenStore: tokenStore,
+        clock: clock,
+      ),
+      RetryInterceptor(dio: dio, clock: clock),
+    ]);
+
+    return dio;
+  }
+}
@@ -0,0 +1,30 @@
+import 'package:dio/dio.dart';
+import 'package:relationship_saver/core/auth/token_store.dart';
+import 'package:relationship_saver/core/network/network_constants.dart';
+
+/// Adds bearer access token to outgoing requests.
+class AuthInterceptor extends Interceptor {
+  AuthInterceptor({required TokenStore tokenStore}) : _tokenStore = tokenStore;
+
+  final TokenStore _tokenStore;
+
+  @override
+  Future<void> onRequest(
+    RequestOptions options,
+    RequestInterceptorHandler handler,
+  ) async {
+    if (options.extra[NetworkConstants.extraSkipAuth] == true) {
+      handler.next(options);
+      return;
+    }
+
+    final session = await _tokenStore.read();
+    if (session?.accessToken case final String accessToken
+        when accessToken.isNotEmpty) {
+      options.headers[NetworkConstants.authorizationHeader] =
+          'Bearer $accessToken';
+    }
+
+    handler.next(options);
+  }
+}
@@ -0,0 +1,154 @@
+import 'package:clock/clock.dart';
+import 'package:dio/dio.dart';
+import 'package:relationship_saver/core/auth/token_store.dart';
+import 'package:relationship_saver/core/network/backend_exception.dart';
+import 'package:relationship_saver/core/network/network_constants.dart';
+import 'package:relationship_saver/integrations/backend/models/backend_models.dart';
+
+/// Handles access-token refresh on 401 responses and retries the original call.
+class RefreshTokenInterceptor extends Interceptor {
+  RefreshTokenInterceptor({
+    required Dio dio,
+    required Dio refreshDio,
+    required TokenStore tokenStore,
+    Clock? clock,
+  }) : _dio = dio,
+       _refreshDio = refreshDio,
+       _tokenStore = tokenStore,
+       _clock = clock ?? const Clock();
+
+  final Dio _dio;
+  final Dio _refreshDio;
+  final TokenStore _tokenStore;
+  final Clock _clock;
+  Future<AuthRefreshResponse?>? _ongoingRefresh;
+
+  @override
+  Future<void> onError(
+    DioException err,
+    ErrorInterceptorHandler handler,
+  ) async {
+    if (!_shouldHandle(err.requestOptions, err.response?.statusCode)) {
+      handler.next(err);
+      return;
+    }
+
+    try {
+      final AuthRefreshResponse? refreshed = await _refreshOnce();
+      if (refreshed == null) {
+        await _tokenStore.clear();
+        handler.reject(_asAuthExpired(err));
+        return;
+      }
+
+      final RequestOptions retried = err.requestOptions.copyWith(
+        headers: <String, dynamic>{
+          ...err.requestOptions.headers,
+          NetworkConstants.authorizationHeader:
+              'Bearer ${refreshed.accessToken}',
+        },
+        extra: <String, dynamic>{
+          ...err.requestOptions.extra,
+          NetworkConstants.extraDidRefresh: true,
+        },
+      );
+
+      final Response<dynamic> response = await _dio.fetch<dynamic>(retried);
+      handler.resolve(response);
+    } on DioException catch (refreshFailure) {
+      await _tokenStore.clear();
+      handler.reject(
+        DioException(
+          requestOptions: err.requestOptions,
+          response: refreshFailure.response,
+          error: const AuthExpiredException('Authentication expired'),
+          type: DioExceptionType.badResponse,
+        ),
+      );
+    } catch (_) {
+      await _tokenStore.clear();
+      handler.reject(_asAuthExpired(err));
+    }
+  }
+
+  bool _shouldHandle(RequestOptions options, int? statusCode) {
+    if (statusCode != 401) {
+      return false;
+    }
+    if (options.extra[NetworkConstants.extraSkipRefresh] == true ||
+        options.extra[NetworkConstants.extraDidRefresh] == true) {
+      return false;
+    }
+    return !options.path.endsWith('/v1/auth/refresh');
+  }
+
+  Future<AuthRefreshResponse?> _refreshOnce() async {
+    final Future<AuthRefreshResponse?>? inflight = _ongoingRefresh;
+    if (inflight != null) {
+      return inflight;
+    }
+
+    final Future<AuthRefreshResponse?> future = _refreshInternal();
+    _ongoingRefresh = future;
+    try {
+      return await future;
+    } finally {
+      _ongoingRefresh = null;
+    }
+  }
+
+  Future<AuthRefreshResponse?> _refreshInternal() async {
+    final AuthSession? current = await _tokenStore.read();
+    if (current == null || current.refreshToken.isEmpty) {
+      return null;
+    }
+
+    final Response<dynamic> response = await _refreshDio.post<dynamic>(
+      '/v1/auth/refresh',
+      data: AuthRefreshRequest(refreshToken: current.refreshToken).toJson(),
+      options: Options(
+        headers: <String, dynamic>{
+          NetworkConstants.requestIdHeader:
+              'refresh-${_clock.now().microsecondsSinceEpoch}',
+        },
+        extra: <String, dynamic>{
+          NetworkConstants.extraSkipAuth: true,
+          NetworkConstants.extraSkipRefresh: true,
+        },
+      ),
+    );
+
+    final AuthRefreshResponse refreshed = AuthRefreshResponse.fromJson(
+      _asJsonMap(response.data),
+    );
+    final AuthSession updated = current.copyWith(
+      accessToken: refreshed.accessToken,
+      refreshToken: refreshed.refreshToken ?? current.refreshToken,
+      expiresAt: refreshed.expiresAt,
+    );
+
+    await _tokenStore.write(updated);
+    return refreshed;
+  }
+
+  Map<String, dynamic> _asJsonMap(dynamic value) {
+    if (value is Map<String, dynamic>) {
+      return value;
+    }
+    if (value is Map<Object?, Object?>) {
+      return value.map<String, dynamic>(
+        (Object? key, Object? val) => MapEntry(key.toString(), val),
+      );
+    }
+    throw const FormatException('Expected JSON object');
+  }
+
+  DioException _asAuthExpired(DioException source) {
+    return DioException(
+      requestOptions: source.requestOptions,
+      response: source.response,
+      type: DioExceptionType.badResponse,
+      error: const AuthExpiredException('Authentication expired'),
+    );
+  }
+}
@@ -0,0 +1,19 @@
+import 'package:dio/dio.dart';
+import 'package:relationship_saver/core/network/network_constants.dart';
+import 'package:uuid/uuid.dart';
+
+/// Adds per-request metadata headers such as request ID.
+class RequestMetadataInterceptor extends Interceptor {
+  RequestMetadataInterceptor({Uuid? uuid}) : _uuid = uuid ?? const Uuid();
+
+  final Uuid _uuid;
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    options.headers.putIfAbsent(
+      NetworkConstants.requestIdHeader,
+      () => _uuid.v4(),
+    );
+    handler.next(options);
+  }
+}
@@ -0,0 +1,91 @@
+import 'dart:math' as math;
+
+import 'package:clock/clock.dart';
+import 'package:dio/dio.dart';
+import 'package:relationship_saver/core/network/network_constants.dart';
+
+/// Retries transient failures with exponential backoff.
+class RetryInterceptor extends Interceptor {
+  RetryInterceptor({
+    required Dio dio,
+    this.maxRetries = 2,
+    this.baseDelay = const Duration(milliseconds: 200),
+    Clock? clock,
+  }) : _dio = dio,
+       _clock = clock ?? const Clock();
+
+  final Dio _dio;
+  final int maxRetries;
+  final Duration baseDelay;
+  final Clock _clock;
+
+  @override
+  Future<void> onError(
+    DioException err,
+    ErrorInterceptorHandler handler,
+  ) async {
+    final RequestOptions request = err.requestOptions;
+    final int attempt =
+        (request.extra[NetworkConstants.extraRetryAttempt] as int?) ?? 0;
+
+    if (!_shouldRetry(err, request) || attempt >= maxRetries) {
+      handler.next(err);
+      return;
+    }
+
+    final int multiplier = math.pow(2, attempt).toInt();
+    final Duration delay = Duration(
+      milliseconds: baseDelay.inMilliseconds * multiplier,
+    );
+
+    final DateTime wakeAt = _clock.now().add(delay);
+    final Duration sleepFor = wakeAt.difference(_clock.now());
+    await Future<void>.delayed(sleepFor.isNegative ? Duration.zero : sleepFor);
+
+    final RequestOptions retried = request.copyWith(
+      extra: <String, dynamic>{
+        ...request.extra,
+        NetworkConstants.extraRetryAttempt: attempt + 1,
+      },
+    );
+
+    try {
+      final Response<dynamic> response = await _dio.fetch<dynamic>(retried);
+      handler.resolve(response);
+    } on DioException catch (retryError) {
+      handler.next(retryError);
+    }
+  }
+
+  bool _shouldRetry(DioException error, RequestOptions request) {
+    if (!_isTransient(error)) {
+      return false;
+    }
+
+    final String method = request.method.toUpperCase();
+    if (method == 'GET' || method == 'HEAD' || method == 'OPTIONS') {
+      return true;
+    }
+
+    final Object? idempotency =
+        request.headers[NetworkConstants.idempotencyKeyHeader];
+    return idempotency is String && idempotency.trim().isNotEmpty;
+  }
+
+  bool _isTransient(DioException error) {
+    switch (error.type) {
+      case DioExceptionType.connectionTimeout:
+      case DioExceptionType.sendTimeout:
+      case DioExceptionType.receiveTimeout:
+      case DioExceptionType.connectionError:
+        return true;
+      case DioExceptionType.badResponse:
+        final int? status = error.response?.statusCode;
+        return status != null && status >= 500 && status < 600;
+      case DioExceptionType.badCertificate:
+      case DioExceptionType.cancel:
+      case DioExceptionType.unknown:
+        return false;
+    }
+  }
+}
@@ -0,0 +1,13 @@
+/// HTTP header keys and Dio `extra` keys used by network interceptors.
+class NetworkConstants {
+  NetworkConstants._();
+
+  static const String authorizationHeader = 'Authorization';
+  static const String requestIdHeader = 'X-Request-Id';
+  static const String idempotencyKeyHeader = 'Idempotency-Key';
+
+  static const String extraSkipAuth = 'skipAuth';
+  static const String extraSkipRefresh = 'skipRefresh';
+  static const String extraDidRefresh = 'didRefresh';
+  static const String extraRetryAttempt = 'retryAttempt';
+}
@@ -0,0 +1,9 @@
+import 'package:clock/clock.dart';
+
+/// Shared clock helper for deterministic testing.
+class TimeProvider {
+  TimeProvider._();
+
+  /// Current wall-clock time.
+  static DateTime now() => clock.now();
+}
@@ -0,0 +1,47 @@
+import 'package:relationship_saver/integrations/backend/models/backend_models.dart';
+
+/// Domain-level backend boundary independent of HTTP transport.
+abstract interface class BackendGateway {
+  /// Authenticates user and returns active session.
+  Future<AuthSession> signIn(SignInRequest request);
+
+  /// Signs out current user.
+  Future<void> signOut();
+
+  /// Returns current user profile.
+  Future<UserProfile> me();
+
+  /// Pulls remote changes since optional cursor.
+  Future<SyncPullResult> pullChanges({String? cursor, int limit = 200});
+
+  /// Pushes local changes to backend.
+  Future<SyncPushResult> pushChanges({
+    required List<ChangeEnvelope> changes,
+    String? cursor,
+  });
+
+  /// Fetches recommendation signals feed.
+  Future<SignalsFeed> getSignalsFeed({
+    String? cursor,
+    DateTime? since,
+    int limit = 50,
+    Set<String>? personIds,
+  });
+
+  /// Acknowledges a signal action.
+  Future<void> acknowledgeSignal({
+    required String signalId,
+    required SignalAction action,
+    DateTime? at,
+  });
+
+  /// Initializes upload metadata and pre-signed URL.
+  Future<UploadInitResult> initUpload({
+    required UploadPurpose purpose,
+    required String contentType,
+    required int sizeBytes,
+  });
+
+  /// Resolves a temporary download URL.
+  Future<DownloadUrl> getDownloadUrl({required String fileId});
+}
@@ -0,0 +1,160 @@
+import 'package:clock/clock.dart';
+import 'package:relationship_saver/integrations/backend/backend_gateway.dart';
+import 'package:relationship_saver/integrations/backend/models/backend_models.dart';
+import 'package:uuid/uuid.dart';
+
+/// Deterministic fake backend for local development and tests.
+class BackendGatewayFake implements BackendGateway {
+  BackendGatewayFake({Clock? clock, Uuid? uuid})
+    : _clock = clock ?? const Clock(),
+      _uuid = uuid ?? const Uuid();
+
+  final Clock _clock;
+  final Uuid _uuid;
+
+  static final DateTime _seedTime = DateTime.utc(2026, 1, 1, 8);
+
+  @override
+  Future<void> acknowledgeSignal({
+    required String signalId,
+    required SignalAction action,
+    DateTime? at,
+  }) async {
+    return;
+  }
+
+  @override
+  Future<DownloadUrl> getDownloadUrl({required String fileId}) async {
+    return DownloadUrl(
+      downloadUrl: 'https://files.example.com/download/$fileId',
+      expiresAt: _seedTime.add(const Duration(hours: 1)),
+    );
+  }
+
+  @override
+  Future<SignalsFeed> getSignalsFeed({
+    String? cursor,
+    DateTime? since,
+    int limit = 50,
+    Set<String>? personIds,
+  }) async {
+    final List<SignalItem> seeded = <SignalItem>[
+      SignalItem(
+        id: 'sig-1',
+        type: 'deal',
+        title: 'Weekend coffee promo nearby',
+        description: 'Save this for your next date idea.',
+        personId: personIds?.isNotEmpty == true ? personIds!.first : 'person-1',
+        createdAt: _seedTime,
+        metadata: const <String, dynamic>{'merchant': 'Cafe Bloom'},
+      ),
+      SignalItem(
+        id: 'sig-2',
+        type: 'trend',
+        title: 'Books are trending in gift ideas',
+        description: 'Reading-themed gifts up 24% this week.',
+        personId: personIds?.isNotEmpty == true ? personIds!.first : 'person-1',
+        createdAt: _seedTime.add(const Duration(hours: 3)),
+      ),
+      SignalItem(
+        id: 'sig-3',
+        type: 'recommendation',
+        title: 'Try a sunset walk reminder',
+        description: 'Low-effort ritual with high emotional impact.',
+        personId: personIds?.isNotEmpty == true ? personIds!.first : 'person-2',
+        createdAt: _seedTime.add(const Duration(hours: 6)),
+      ),
+    ];
+
+    return SignalsFeed(
+      cursor: 'fake-cursor-1',
+      items: seeded.take(limit).toList(),
+    );
+  }
+
+  @override
+  Future<UploadInitResult> initUpload({
+    required UploadPurpose purpose,
+    required String contentType,
+    required int sizeBytes,
+  }) async {
+    final String fileId = 'file-${_uuid.v4()}';
+    return UploadInitResult(
+      uploadUrl: 'https://uploads.example.com/$fileId',
+      fileId: fileId,
+      expiresAt: _seedTime.add(const Duration(minutes: 15)),
+    );
+  }
+
+  @override
+  Future<UserProfile> me() async {
+    return const UserProfile(
+      id: 'user-fake',
+      email: 'demo@example.com',
+      displayName: 'Demo User',
+    );
+  }
+
+  @override
+  Future<SyncPullResult> pullChanges({String? cursor, int limit = 200}) async {
+    final List<ChangeEnvelope> changes = <ChangeEnvelope>[
+      ChangeEnvelope(
+        schemaVersion: 1,
+        entityType: 'person',
+        entityId: 'person-1',
+        op: ChangeOperation.upsert,
+        modifiedAt: _seedTime,
+        clientMutationId: 'cm-1',
+        payload: const <String, dynamic>{'name': 'Alex', 'importance': 5},
+      ),
+    ];
+
+    return SyncPullResult(
+      cursor: 'fake-pull-cursor-1',
+      changes: changes.take(limit).toList(),
+    );
+  }
+
+  @override
+  Future<SyncPushResult> pushChanges({
+    required List<ChangeEnvelope> changes,
+    String? cursor,
+  }) async {
+    final DateTime now = _clock.now().toUtc();
+    final List<MutationAck> accepted = changes
+        .map(
+          (ChangeEnvelope change) => MutationAck(
+            clientMutationId: change.clientMutationId,
+            serverMutationId: 'srv-${change.clientMutationId}',
+            acceptedAt: now,
+          ),
+        )
+        .toList(growable: false);
+
+    return SyncPushResult(
+      cursor: 'fake-push-cursor-1',
+      accepted: accepted,
+      rejected: const <MutationRejection>[],
+    );
+  }
+
+  @override
+  Future<AuthSession> signIn(SignInRequest request) async {
+    final DateTime now = _clock.now().toUtc();
+    return AuthSession(
+      accessToken: 'fake-access-token',
+      refreshToken: 'fake-refresh-token',
+      expiresAt: now.add(const Duration(hours: 1)),
+      user: UserProfile(
+        id: 'user-fake',
+        email: request.email ?? 'demo@example.com',
+        displayName: 'Demo User',
+      ),
+    );
+  }
+
+  @override
+  Future<void> signOut() async {
+    return;
+  }
+}
@@ -0,0 +1,36 @@
+import 'package:dio/dio.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:relationship_saver/core/auth/secure_token_store.dart';
+import 'package:relationship_saver/core/auth/token_store.dart';
+import 'package:relationship_saver/core/config/app_config.dart';
+import 'package:relationship_saver/core/network/dio_factory.dart';
+import 'package:relationship_saver/integrations/backend/backend_gateway.dart';
+import 'package:relationship_saver/integrations/backend/backend_gateway_fake.dart';
+import 'package:relationship_saver/integrations/backend/backend_gateway_rest.dart';
+
+/// Provides token storage implementation.
+final Provider<TokenStore> tokenStoreProvider = Provider<TokenStore>((Ref ref) {
+  return SecureTokenStore();
+});
+
+/// Provides configured Dio client for backend transport.
+final Provider<Dio> backendDioProvider = Provider<Dio>((Ref ref) {
+  final TokenStore tokenStore = ref.watch(tokenStoreProvider);
+  return DioFactory.create(
+    baseUrl: AppConfig.backendBaseUrl,
+    tokenStore: tokenStore,
+  );
+});
+
+/// Provides backend gateway implementation.
+final Provider<BackendGateway> backendGatewayProvider =
+    Provider<BackendGateway>((Ref ref) {
+      if (AppConfig.useFakeBackend) {
+        return BackendGatewayFake();
+      }
+
+      return BackendGatewayRest(
+        dio: ref.watch(backendDioProvider),
+        tokenStore: ref.watch(tokenStoreProvider),
+      );
+    });
@@ -0,0 +1,213 @@
+import 'package:clock/clock.dart';
+import 'package:dio/dio.dart';
+import 'package:relationship_saver/core/auth/token_store.dart';
+import 'package:relationship_saver/core/network/dio_error_mapper.dart';
+import 'package:relationship_saver/core/network/network_constants.dart';
+import 'package:relationship_saver/integrations/backend/backend_gateway.dart';
+import 'package:relationship_saver/integrations/backend/models/backend_models.dart';
+import 'package:relationship_saver/integrations/backend/sync_envelope_validator.dart';
+import 'package:uuid/uuid.dart';
+
+/// REST implementation of [BackendGateway] backed by Dio.
+class BackendGatewayRest implements BackendGateway {
+  BackendGatewayRest({
+    required Dio dio,
+    required TokenStore tokenStore,
+    Uuid? uuid,
+    Clock? clock,
+    this.deviceId = 'device-local',
+  }) : _dio = dio,
+       _tokenStore = tokenStore,
+       _uuid = uuid ?? const Uuid(),
+       _clock = clock ?? const Clock();
+
+  final Dio _dio;
+  final TokenStore _tokenStore;
+  final Uuid _uuid;
+  final Clock _clock;
+  final String deviceId;
+
+  @override
+  Future<void> acknowledgeSignal({
+    required String signalId,
+    required SignalAction action,
+    DateTime? at,
+  }) {
+    return _guard(() async {
+      final SignalAckRequest body = SignalAckRequest(
+        action: action,
+        at: at ?? _clock.now(),
+      );
+
+      await _dio.post<dynamic>(
+        '/v1/signals/$signalId/ack',
+        data: body.toJson(),
+      );
+    });
+  }
+
+  @override
+  Future<DownloadUrl> getDownloadUrl({required String fileId}) {
+    return _guard(() async {
+      final Response<dynamic> response = await _dio.get<dynamic>(
+        '/v1/files/$fileId',
+      );
+      return DownloadUrl.fromJson(_asJsonMap(response.data));
+    });
+  }
+
+  @override
+  Future<SignalsFeed> getSignalsFeed({
+    String? cursor,
+    DateTime? since,
+    int limit = 50,
+    Set<String>? personIds,
+  }) {
+    return _guard(() async {
+      final Map<String, dynamic> query = <String, dynamic>{'limit': limit};
+      if (cursor != null && cursor.isNotEmpty) {
+        query['cursor'] = cursor;
+      }
+      if (since != null) {
+        query['since'] = since.toUtc().toIso8601String();
+      }
+      if (personIds != null && personIds.isNotEmpty) {
+        query['personId'] = personIds.toList(growable: false);
+      }
+
+      final Response<dynamic> response = await _dio.get<dynamic>(
+        '/v1/signals',
+        queryParameters: query,
+      );
+      return SignalsFeed.fromJson(_asJsonMap(response.data));
+    });
+  }
+
+  @override
+  Future<UploadInitResult> initUpload({
+    required UploadPurpose purpose,
+    required String contentType,
+    required int sizeBytes,
+  }) {
+    return _guard(() async {
+      final UploadInitRequest request = UploadInitRequest(
+        purpose: purpose,
+        contentType: contentType,
+        sizeBytes: sizeBytes,
+      );
+      final Response<dynamic> response = await _dio.post<dynamic>(
+        '/v1/uploads',
+        data: request.toJson(),
+      );
+      return UploadInitResult.fromJson(_asJsonMap(response.data));
+    });
+  }
+
+  @override
+  Future<UserProfile> me() {
+    return _guard(() async {
+      final Response<dynamic> response = await _dio.get<dynamic>('/v1/me');
+      return UserProfile.fromJson(_asJsonMap(response.data));
+    });
+  }
+
+  @override
+  Future<SyncPullResult> pullChanges({String? cursor, int limit = 200}) {
+    return _guard(() async {
+      final Map<String, dynamic> query = <String, dynamic>{'limit': limit};
+      if (cursor != null && cursor.isNotEmpty) {
+        query['cursor'] = cursor;
+      }
+
+      final Response<dynamic> response = await _dio.get<dynamic>(
+        '/v1/sync/pull',
+        queryParameters: query,
+      );
+      return SyncPullResult.fromJson(_asJsonMap(response.data));
+    });
+  }
+
+  @override
+  Future<SyncPushResult> pushChanges({
+    required List<ChangeEnvelope> changes,
+    String? cursor,
+  }) {
+    return _guard(() async {
+      SyncEnvelopeValidator.validateAll(changes);
+
+      final String idempotencyKey = _uuid.v4();
+      final SyncPushRequest request = SyncPushRequest(
+        deviceId: deviceId,
+        cursor: cursor,
+        changes: changes,
+        idempotencyKey: idempotencyKey,
+      );
+
+      final Response<dynamic> response = await _dio.post<dynamic>(
+        '/v1/sync/push',
+        data: request.toJson(),
+        options: Options(
+          headers: <String, dynamic>{
+            NetworkConstants.idempotencyKeyHeader: idempotencyKey,
+          },
+        ),
+      );
+      return SyncPushResult.fromJson(_asJsonMap(response.data));
+    });
+  }
+
+  @override
+  Future<AuthSession> signIn(SignInRequest request) {
+    return _guard(() async {
+      final Response<dynamic> response = await _dio.post<dynamic>(
+        '/v1/auth/sign-in',
+        data: request.toJson(),
+        options: Options(
+          extra: const <String, dynamic>{
+            NetworkConstants.extraSkipAuth: true,
+            NetworkConstants.extraSkipRefresh: true,
+          },
+        ),
+      );
+
+      final AuthSession session = AuthSession.fromJson(
+        _asJsonMap(response.data),
+      );
+      await _tokenStore.write(session);
+      return session;
+    });
+  }
+
+  @override
+  Future<void> signOut() async {
+    try {
+      await _guard(() async {
+        await _dio.post<dynamic>('/v1/auth/sign-out');
+      });
+    } finally {
+      await _tokenStore.clear();
+    }
+  }
+
+  Future<T> _guard<T>(Future<T> Function() run) async {
+    try {
+      return await run();
+    } on DioException catch (error) {
+      throw mapDioException(error);
+    }
+  }
+
+  Map<String, dynamic> _asJsonMap(dynamic value) {
+    if (value is Map<String, dynamic>) {
+      return value;
+    }
+    if (value is Map<Object?, Object?>) {
+      return value.map<String, dynamic>(
+        (Object? key, Object? val) => MapEntry(key.toString(), val),
+      );
+    }
+    throw FormatException(
+      'Expected JSON object response, got ${value.runtimeType}',
+    );
+  }
+}
@@ -0,0 +1,4 @@
+# Backend Mappers
+
+This folder is reserved for DTO <-> domain mappers as domain aggregates are introduced.
+Current MVP uses shared typed models directly to keep the gateway layer lean.
@@ -0,0 +1,290 @@
+// ignore_for_file: invalid_annotation_target
+
+import 'package:freezed_annotation/freezed_annotation.dart';
+
+part 'backend_models.freezed.dart';
+part 'backend_models.g.dart';
+
+/// Supported authentication methods.
+@JsonEnum(fieldRename: FieldRename.snake)
+enum SignInMethod {
+  /// Email link based sign-in.
+  emailMagicLink,
+
+  /// Email/password sign-in.
+  password,
+
+  /// OIDC token based sign-in.
+  oidc,
+}
+
+/// Allowed change operation types.
+@JsonEnum(alwaysCreate: true)
+enum ChangeOperation {
+  /// Create or update entity state.
+  @JsonValue('upsert')
+  upsert,
+
+  /// Remove entity state.
+  @JsonValue('delete')
+  delete,
+}
+
+/// Action taken by user against a signal item.
+@JsonEnum(alwaysCreate: true)
+enum SignalAction {
+  /// Item was viewed.
+  viewed,
+
+  /// Item was dismissed.
+  dismissed,
+
+  /// Item was saved.
+  saved,
+
+  /// Item resulted in purchase.
+  purchased,
+}
+
+/// Upload category.
+@JsonEnum(alwaysCreate: true)
+enum UploadPurpose {
+  /// Avatar upload.
+  @JsonValue('avatar')
+  avatar,
+
+  /// Generic attachment upload.
+  @JsonValue('attachment')
+  attachment,
+}
+
+/// Request body for sign-in.
+@freezed
+abstract class SignInRequest with _$SignInRequest {
+  const factory SignInRequest({
+    required SignInMethod method,
+    String? email,
+    String? password,
+    String? idToken,
+  }) = _SignInRequest;
+
+  factory SignInRequest.fromJson(Map<String, dynamic> json) =>
+      _$SignInRequestFromJson(json);
+}
+
+/// User profile returned by backend.
+@freezed
+abstract class UserProfile with _$UserProfile {
+  const factory UserProfile({
+    required String id,
+    String? email,
+    String? displayName,
+    String? avatarFileId,
+  }) = _UserProfile;
+
+  factory UserProfile.fromJson(Map<String, dynamic> json) =>
+      _$UserProfileFromJson(json);
+}
+
+/// Auth session bundle used by gateway and token storage.
+@freezed
+abstract class AuthSession with _$AuthSession {
+  @JsonSerializable(explicitToJson: true)
+  const factory AuthSession({
+    required String accessToken,
+    required String refreshToken,
+    required DateTime expiresAt,
+    required UserProfile user,
+  }) = _AuthSession;
+
+  factory AuthSession.fromJson(Map<String, dynamic> json) =>
+      _$AuthSessionFromJson(json);
+}
+
+/// Refresh token request body.
+@freezed
+abstract class AuthRefreshRequest with _$AuthRefreshRequest {
+  const factory AuthRefreshRequest({required String refreshToken}) =
+      _AuthRefreshRequest;
+
+  factory AuthRefreshRequest.fromJson(Map<String, dynamic> json) =>
+      _$AuthRefreshRequestFromJson(json);
+}
+
+/// Refresh token response body.
+@freezed
+abstract class AuthRefreshResponse with _$AuthRefreshResponse {
+  const factory AuthRefreshResponse({
+    required String accessToken,
+    String? refreshToken,
+    required DateTime expiresAt,
+  }) = _AuthRefreshResponse;
+
+  factory AuthRefreshResponse.fromJson(Map<String, dynamic> json) =>
+      _$AuthRefreshResponseFromJson(json);
+}
+
+/// Generic envelope for offline-first change operations.
+@freezed
+abstract class ChangeEnvelope with _$ChangeEnvelope {
+  const factory ChangeEnvelope({
+    required int schemaVersion,
+    required String entityType,
+    required String entityId,
+    required ChangeOperation op,
+    required DateTime modifiedAt,
+    required String clientMutationId,
+    Map<String, dynamic>? payload,
+  }) = _ChangeEnvelope;
+
+  factory ChangeEnvelope.fromJson(Map<String, dynamic> json) =>
+      _$ChangeEnvelopeFromJson(json);
+}
+
+/// Push request for batched local changes.
+@freezed
+abstract class SyncPushRequest with _$SyncPushRequest {
+  @JsonSerializable(explicitToJson: true)
+  const factory SyncPushRequest({
+    required String deviceId,
+    String? cursor,
+    required List<ChangeEnvelope> changes,
+    required String idempotencyKey,
+  }) = _SyncPushRequest;
+
+  factory SyncPushRequest.fromJson(Map<String, dynamic> json) =>
+      _$SyncPushRequestFromJson(json);
+}
+
+/// Acknowledgement for an accepted mutation.
+@freezed
+abstract class MutationAck with _$MutationAck {
+  const factory MutationAck({
+    required String clientMutationId,
+    String? serverMutationId,
+    DateTime? acceptedAt,
+  }) = _MutationAck;
+
+  factory MutationAck.fromJson(Map<String, dynamic> json) =>
+      _$MutationAckFromJson(json);
+}
+
+/// Rejection detail for a mutation.
+@freezed
+abstract class MutationRejection with _$MutationRejection {
+  const factory MutationRejection({
+    required String clientMutationId,
+    required String code,
+    required String message,
+  }) = _MutationRejection;
+
+  factory MutationRejection.fromJson(Map<String, dynamic> json) =>
+      _$MutationRejectionFromJson(json);
+}
+
+/// Result body returned by sync push.
+@freezed
+abstract class SyncPushResult with _$SyncPushResult {
+  @JsonSerializable(explicitToJson: true)
+  const factory SyncPushResult({
+    required String cursor,
+    @Default(<MutationAck>[]) List<MutationAck> accepted,
+    @Default(<MutationRejection>[]) List<MutationRejection> rejected,
+  }) = _SyncPushResult;
+
+  factory SyncPushResult.fromJson(Map<String, dynamic> json) =>
+      _$SyncPushResultFromJson(json);
+}
+
+/// Result body returned by sync pull.
+@freezed
+abstract class SyncPullResult with _$SyncPullResult {
+  @JsonSerializable(explicitToJson: true)
+  const factory SyncPullResult({
+    required String cursor,
+    @Default(<ChangeEnvelope>[]) List<ChangeEnvelope> changes,
+  }) = _SyncPullResult;
+
+  factory SyncPullResult.fromJson(Map<String, dynamic> json) =>
+      _$SyncPullResultFromJson(json);
+}
+
+/// Signals feed item.
+@freezed
+abstract class SignalItem with _$SignalItem {
+  const factory SignalItem({
+    required String id,
+    required String type,
+    required String title,
+    String? description,
+    String? personId,
+    required DateTime createdAt,
+    Map<String, dynamic>? metadata,
+  }) = _SignalItem;
+
+  factory SignalItem.fromJson(Map<String, dynamic> json) =>
+      _$SignalItemFromJson(json);
+}
+
+/// Cursor-based signals response.
+@freezed
+abstract class SignalsFeed with _$SignalsFeed {
+  @JsonSerializable(explicitToJson: true)
+  const factory SignalsFeed({
+    String? cursor,
+    @Default(<SignalItem>[]) List<SignalItem> items,
+  }) = _SignalsFeed;
+
+  factory SignalsFeed.fromJson(Map<String, dynamic> json) =>
+      _$SignalsFeedFromJson(json);
+}
+
+/// Signal acknowledgement request body.
+@freezed
+abstract class SignalAckRequest with _$SignalAckRequest {
+  const factory SignalAckRequest({
+    required SignalAction action,
+    required DateTime at,
+  }) = _SignalAckRequest;
+
+  factory SignalAckRequest.fromJson(Map<String, dynamic> json) =>
+      _$SignalAckRequestFromJson(json);
+}
+
+/// Upload init request.
+@freezed
+abstract class UploadInitRequest with _$UploadInitRequest {
+  const factory UploadInitRequest({
+    required UploadPurpose purpose,
+    required String contentType,
+    required int sizeBytes,
+  }) = _UploadInitRequest;
+
+  factory UploadInitRequest.fromJson(Map<String, dynamic> json) =>
+      _$UploadInitRequestFromJson(json);
+}
+
+/// Upload init response.
+@freezed
+abstract class UploadInitResult with _$UploadInitResult {
+  const factory UploadInitResult({
+    required String uploadUrl,
+    required String fileId,
+    required DateTime expiresAt,
+  }) = _UploadInitResult;
+
+  factory UploadInitResult.fromJson(Map<String, dynamic> json) =>
+      _$UploadInitResultFromJson(json);
+}
+
+/// Download URL response.
+@freezed
+abstract class DownloadUrl with _$DownloadUrl {
+  const factory DownloadUrl({
+    required String downloadUrl,
+    required DateTime expiresAt,
+  }) = _DownloadUrl;
+
+  factory DownloadUrl.fromJson(Map<String, dynamic> json) =>
+      _$DownloadUrlFromJson(json);
+}
@@ -0,0 +1,293 @@
+// GENERATED CODE - DO NOT MODIFY BY HAND
+
+part of 'backend_models.dart';
+
+// **************************************************************************
+// JsonSerializableGenerator
+// **************************************************************************
+
+_SignInRequest _$SignInRequestFromJson(Map<String, dynamic> json) =>
+    _SignInRequest(
+      method: $enumDecode(_$SignInMethodEnumMap, json['method']),
+      email: json['email'] as String?,
+      password: json['password'] as String?,
+      idToken: json['idToken'] as String?,
+    );
+
+Map<String, dynamic> _$SignInRequestToJson(_SignInRequest instance) =>
+    <String, dynamic>{
+      'method': _$SignInMethodEnumMap[instance.method]!,
+      'email': instance.email,
+      'password': instance.password,
+      'idToken': instance.idToken,
+    };
+
+const _$SignInMethodEnumMap = {
+  SignInMethod.emailMagicLink: 'email_magic_link',
+  SignInMethod.password: 'password',
+  SignInMethod.oidc: 'oidc',
+};
+
+_UserProfile _$UserProfileFromJson(Map<String, dynamic> json) => _UserProfile(
+  id: json['id'] as String,
+  email: json['email'] as String?,
+  displayName: json['displayName'] as String?,
+  avatarFileId: json['avatarFileId'] as String?,
+);
+
+Map<String, dynamic> _$UserProfileToJson(_UserProfile instance) =>
+    <String, dynamic>{
+      'id': instance.id,
+      'email': instance.email,
+      'displayName': instance.displayName,
+      'avatarFileId': instance.avatarFileId,
+    };
+
+_AuthSession _$AuthSessionFromJson(Map<String, dynamic> json) => _AuthSession(
+  accessToken: json['accessToken'] as String,
+  refreshToken: json['refreshToken'] as String,
+  expiresAt: DateTime.parse(json['expiresAt'] as String),
+  user: UserProfile.fromJson(json['user'] as Map<String, dynamic>),
+);
+
+Map<String, dynamic> _$AuthSessionToJson(_AuthSession instance) =>
+    <String, dynamic>{
+      'accessToken': instance.accessToken,
+      'refreshToken': instance.refreshToken,
+      'expiresAt': instance.expiresAt.toIso8601String(),
+      'user': instance.user.toJson(),
+    };
+
+_AuthRefreshRequest _$AuthRefreshRequestFromJson(Map<String, dynamic> json) =>
+    _AuthRefreshRequest(refreshToken: json['refreshToken'] as String);
+
+Map<String, dynamic> _$AuthRefreshRequestToJson(_AuthRefreshRequest instance) =>
+    <String, dynamic>{'refreshToken': instance.refreshToken};
+
+_AuthRefreshResponse _$AuthRefreshResponseFromJson(Map<String, dynamic> json) =>
+    _AuthRefreshResponse(
+      accessToken: json['accessToken'] as String,
+      refreshToken: json['refreshToken'] as String?,
+      expiresAt: DateTime.parse(json['expiresAt'] as String),
+    );
+
+Map<String, dynamic> _$AuthRefreshResponseToJson(
+  _AuthRefreshResponse instance,
+) => <String, dynamic>{
+  'accessToken': instance.accessToken,
+  'refreshToken': instance.refreshToken,
+  'expiresAt': instance.expiresAt.toIso8601String(),
+};
+
+_ChangeEnvelope _$ChangeEnvelopeFromJson(Map<String, dynamic> json) =>
+    _ChangeEnvelope(
+      schemaVersion: (json['schemaVersion'] as num).toInt(),
+      entityType: json['entityType'] as String,
+      entityId: json['entityId'] as String,
+      op: $enumDecode(_$ChangeOperationEnumMap, json['op']),
+      modifiedAt: DateTime.parse(json['modifiedAt'] as String),
+      clientMutationId: json['clientMutationId'] as String,
+      payload: json['payload'] as Map<String, dynamic>?,
+    );
+
+Map<String, dynamic> _$ChangeEnvelopeToJson(_ChangeEnvelope instance) =>
+    <String, dynamic>{
+      'schemaVersion': instance.schemaVersion,
+      'entityType': instance.entityType,
+      'entityId': instance.entityId,
+      'op': _$ChangeOperationEnumMap[instance.op]!,
+      'modifiedAt': instance.modifiedAt.toIso8601String(),
+      'clientMutationId': instance.clientMutationId,
+      'payload': instance.payload,
+    };
+
+const _$ChangeOperationEnumMap = {
+  ChangeOperation.upsert: 'upsert',
+  ChangeOperation.delete: 'delete',
+};
+
+_SyncPushRequest _$SyncPushRequestFromJson(Map<String, dynamic> json) =>
+    _SyncPushRequest(
+      deviceId: json['deviceId'] as String,
+      cursor: json['cursor'] as String?,
+      changes: (json['changes'] as List<dynamic>)
+          .map((e) => ChangeEnvelope.fromJson(e as Map<String, dynamic>))
+          .toList(),
+      idempotencyKey: json['idempotencyKey'] as String,
+    );
+
+Map<String, dynamic> _$SyncPushRequestToJson(_SyncPushRequest instance) =>
+    <String, dynamic>{
+      'deviceId': instance.deviceId,
+      'cursor': instance.cursor,
+      'changes': instance.changes.map((e) => e.toJson()).toList(),
+      'idempotencyKey': instance.idempotencyKey,
+    };
+
+_MutationAck _$MutationAckFromJson(Map<String, dynamic> json) => _MutationAck(
+  clientMutationId: json['clientMutationId'] as String,
+  serverMutationId: json['serverMutationId'] as String?,
+  acceptedAt: json['acceptedAt'] == null
+      ? null
+      : DateTime.parse(json['acceptedAt'] as String),
+);
+
+Map<String, dynamic> _$MutationAckToJson(_MutationAck instance) =>
+    <String, dynamic>{
+      'clientMutationId': instance.clientMutationId,
+      'serverMutationId': instance.serverMutationId,
+      'acceptedAt': instance.acceptedAt?.toIso8601String(),
+    };
+
+_MutationRejection _$MutationRejectionFromJson(Map<String, dynamic> json) =>
+    _MutationRejection(
+      clientMutationId: json['clientMutationId'] as String,
+      code: json['code'] as String,
+      message: json['message'] as String,
+    );
+
+Map<String, dynamic> _$MutationRejectionToJson(_MutationRejection instance) =>
+    <String, dynamic>{
+      'clientMutationId': instance.clientMutationId,
+      'code': instance.code,
+      'message': instance.message,
+    };
+
+_SyncPushResult _$SyncPushResultFromJson(Map<String, dynamic> json) =>
+    _SyncPushResult(
+      cursor: json['cursor'] as String,
+      accepted:
+          (json['accepted'] as List<dynamic>?)
+              ?.map((e) => MutationAck.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          const <MutationAck>[],
+      rejected:
+          (json['rejected'] as List<dynamic>?)
+              ?.map(
+                (e) => MutationRejection.fromJson(e as Map<String, dynamic>),
+              )
+              .toList() ??
+          const <MutationRejection>[],
+    );
+
+Map<String, dynamic> _$SyncPushResultToJson(_SyncPushResult instance) =>
+    <String, dynamic>{
+      'cursor': instance.cursor,
+      'accepted': instance.accepted.map((e) => e.toJson()).toList(),
+      'rejected': instance.rejected.map((e) => e.toJson()).toList(),
+    };
+
+_SyncPullResult _$SyncPullResultFromJson(Map<String, dynamic> json) =>
+    _SyncPullResult(
+      cursor: json['cursor'] as String,
+      changes:
+          (json['changes'] as List<dynamic>?)
+              ?.map((e) => ChangeEnvelope.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          const <ChangeEnvelope>[],
+    );
+
+Map<String, dynamic> _$SyncPullResultToJson(_SyncPullResult instance) =>
+    <String, dynamic>{
+      'cursor': instance.cursor,
+      'changes': instance.changes.map((e) => e.toJson()).toList(),
+    };
+
+_SignalItem _$SignalItemFromJson(Map<String, dynamic> json) => _SignalItem(
+  id: json['id'] as String,
+  type: json['type'] as String,
+  title: json['title'] as String,
+  description: json['description'] as String?,
+  personId: json['personId'] as String?,
+  createdAt: DateTime.parse(json['createdAt'] as String),
+  metadata: json['metadata'] as Map<String, dynamic>?,
+);
+
+Map<String, dynamic> _$SignalItemToJson(_SignalItem instance) =>
+    <String, dynamic>{
+      'id': instance.id,
+      'type': instance.type,
+      'title': instance.title,
+      'description': instance.description,
+      'personId': instance.personId,
+      'createdAt': instance.createdAt.toIso8601String(),
+      'metadata': instance.metadata,
+    };
+
+_SignalsFeed _$SignalsFeedFromJson(Map<String, dynamic> json) => _SignalsFeed(
+  cursor: json['cursor'] as String?,
+  items:
+      (json['items'] as List<dynamic>?)
+          ?.map((e) => SignalItem.fromJson(e as Map<String, dynamic>))
+          .toList() ??
+      const <SignalItem>[],
+);
+
+Map<String, dynamic> _$SignalsFeedToJson(_SignalsFeed instance) =>
+    <String, dynamic>{
+      'cursor': instance.cursor,
+      'items': instance.items.map((e) => e.toJson()).toList(),
+    };
+
+_SignalAckRequest _$SignalAckRequestFromJson(Map<String, dynamic> json) =>
+    _SignalAckRequest(
+      action: $enumDecode(_$SignalActionEnumMap, json['action']),
+      at: DateTime.parse(json['at'] as String),
+    );
+
+Map<String, dynamic> _$SignalAckRequestToJson(_SignalAckRequest instance) =>
+    <String, dynamic>{
+      'action': _$SignalActionEnumMap[instance.action]!,
+      'at': instance.at.toIso8601String(),
+    };
+
+const _$SignalActionEnumMap = {
+  SignalAction.viewed: 'viewed',
+  SignalAction.dismissed: 'dismissed',
+  SignalAction.saved: 'saved',
+  SignalAction.purchased: 'purchased',
+};
+
+_UploadInitRequest _$UploadInitRequestFromJson(Map<String, dynamic> json) =>
+    _UploadInitRequest(
+      purpose: $enumDecode(_$UploadPurposeEnumMap, json['purpose']),
+      contentType: json['contentType'] as String,
+      sizeBytes: (json['sizeBytes'] as num).toInt(),
+    );
+
+Map<String, dynamic> _$UploadInitRequestToJson(_UploadInitRequest instance) =>
+    <String, dynamic>{
+      'purpose': _$UploadPurposeEnumMap[instance.purpose]!,
+      'contentType': instance.contentType,
+      'sizeBytes': instance.sizeBytes,
+    };
+
+const _$UploadPurposeEnumMap = {
+  UploadPurpose.avatar: 'avatar',
+  UploadPurpose.attachment: 'attachment',
+};
+
+_UploadInitResult _$UploadInitResultFromJson(Map<String, dynamic> json) =>
+    _UploadInitResult(
+      uploadUrl: json['uploadUrl'] as String,
+      fileId: json['fileId'] as String,
+      expiresAt: DateTime.parse(json['expiresAt'] as String),
+    );
+
+Map<String, dynamic> _$UploadInitResultToJson(_UploadInitResult instance) =>
+    <String, dynamic>{
+      'uploadUrl': instance.uploadUrl,
+      'fileId': instance.fileId,
+      'expiresAt': instance.expiresAt.toIso8601String(),
+    };
+
+_DownloadUrl _$DownloadUrlFromJson(Map<String, dynamic> json) => _DownloadUrl(
+  downloadUrl: json['downloadUrl'] as String,
+  expiresAt: DateTime.parse(json['expiresAt'] as String),
+);
+
+Map<String, dynamic> _$DownloadUrlToJson(_DownloadUrl instance) =>
+    <String, dynamic>{
+      'downloadUrl': instance.downloadUrl,
+      'expiresAt': instance.expiresAt.toIso8601String(),
+    };
@@ -0,0 +1,35 @@
+import 'package:relationship_saver/core/network/backend_exception.dart';
+import 'package:relationship_saver/integrations/backend/models/backend_models.dart';
+
+/// Validation rules for outgoing sync envelopes.
+class SyncEnvelopeValidator {
+  SyncEnvelopeValidator._();
+
+  /// Validates a list of changes before a push call.
+  static void validateAll(List<ChangeEnvelope> changes) {
+    for (final ChangeEnvelope change in changes) {
+      validate(change);
+    }
+  }
+
+  /// Validates one change envelope.
+  static void validate(ChangeEnvelope change) {
+    if (change.schemaVersion <= 0) {
+      throw ValidationException(
+        'schemaVersion must be > 0 for ${change.clientMutationId}',
+      );
+    }
+
+    if (change.op == ChangeOperation.delete && change.payload != null) {
+      throw ValidationException(
+        'payload must be null for delete operation (${change.clientMutationId})',
+      );
+    }
+
+    if (change.op == ChangeOperation.upsert && change.payload == null) {
+      throw ValidationException(
+        'payload is required for upsert operation (${change.clientMutationId})',
+      );
+    }
+  }
+}
@@ -0,0 +1,55 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:relationship_saver/core/config/app_config.dart';
+import 'package:relationship_saver/core/config/app_theme.dart';
+
+void main() {
+  runApp(const ProviderScope(child: RelationshipSaverApp()));
+}
+
+class RelationshipSaverApp extends StatelessWidget {
+  const RelationshipSaverApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: 'Relationship Saver',
+      debugShowCheckedModeBanner: false,
+      theme: AppTheme.light(),
+      home: const _LandingScreen(),
+    );
+  }
+}
+
+class _LandingScreen extends StatelessWidget {
+  const _LandingScreen();
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('Relationship Saver')),
+      body: Padding(
+        padding: const EdgeInsets.all(24),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: <Widget>[
+            Text(
+              'Backend gateway scaffold is ready.',
+              style: Theme.of(context).textTheme.headlineSmall,
+            ),
+            const SizedBox(height: 12),
+            Text(
+              'Mode: ${AppConfig.useFakeBackend ? 'Fake gateway' : 'REST gateway'}',
+              style: Theme.of(context).textTheme.bodyLarge,
+            ),
+            const SizedBox(height: 8),
+            Text(
+              'Base URL: ${AppConfig.backendBaseUrl}',
+              style: Theme.of(context).textTheme.bodyMedium,
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
@@ -0,0 +1 @@
+flutter/ephemeral
@@ -0,0 +1,128 @@
+# Project-level configuration.
+cmake_minimum_required(VERSION 3.13)
+project(runner LANGUAGES CXX)
+
+# The name of the executable created for the application. Change this to change
+# the on-disk name of your application.
+set(BINARY_NAME "relationship_saver")
+# The unique GTK application identifier for this application. See:
+# https://wiki.gnome.org/HowDoI/ChooseApplicationID
+set(APPLICATION_ID "com.example.relationship_saver")
+
+# Explicitly opt in to modern CMake behaviors to avoid warnings with recent
+# versions of CMake.
+cmake_policy(SET CMP0063 NEW)
+
+# Load bundled libraries from the lib/ directory relative to the binary.
+set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")
+
+# Root filesystem for cross-building.
+if(FLUTTER_TARGET_PLATFORM_SYSROOT)
+  set(CMAKE_SYSROOT ${FLUTTER_TARGET_PLATFORM_SYSROOT})
+  set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})
+  set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+  set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
+  set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+  set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+endif()
+
+# Define build configuration options.
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE "Debug" CACHE
+    STRING "Flutter build mode" FORCE)
+  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
+    "Debug" "Profile" "Release")
+endif()
+
+# Compilation settings that should be applied to most targets.
+#
+# Be cautious about adding new options here, as plugins use this function by
+# default. In most cases, you should add new options to specific targets instead
+# of modifying this function.
+function(APPLY_STANDARD_SETTINGS TARGET)
+  target_compile_features(${TARGET} PUBLIC cxx_std_14)
+  target_compile_options(${TARGET} PRIVATE -Wall -Werror)
+  target_compile_options(${TARGET} PRIVATE "$<$<NOT:$<CONFIG:Debug>>:-O3>")
+  target_compile_definitions(${TARGET} PRIVATE "$<$<NOT:$<CONFIG:Debug>>:NDEBUG>")
+endfunction()
+
+# Flutter library and tool build rules.
+set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
+add_subdirectory(${FLUTTER_MANAGED_DIR})
+
+# System-level dependencies.
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
+
+# Application build; see runner/CMakeLists.txt.
+add_subdirectory("runner")
+
+# Run the Flutter tool portions of the build. This must not be removed.
+add_dependencies(${BINARY_NAME} flutter_assemble)
+
+# Only the install-generated bundle's copy of the executable will launch
+# correctly, since the resources must in the right relative locations. To avoid
+# people trying to run the unbundled copy, put it in a subdirectory instead of
+# the default top-level location.
+set_target_properties(${BINARY_NAME}
+  PROPERTIES
+  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/intermediates_do_not_run"
+)
+
+
+# Generated plugin build rules, which manage building the plugins and adding
+# them to the application.
+include(flutter/generated_plugins.cmake)
+
+
+# === Installation ===
+# By default, "installing" just makes a relocatable bundle in the build
+# directory.
+set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
+if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
+  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
+endif()
+
+# Start with a clean build bundle directory every time.
+install(CODE "
+  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
+  " COMPONENT Runtime)
+
+set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
+set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")
+
+install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
+  COMPONENT Runtime)
+
+install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
+  COMPONENT Runtime)
+
+install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
+  COMPONENT Runtime)
+
+foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
+  install(FILES "${bundled_library}"
+    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
+    COMPONENT Runtime)
+endforeach(bundled_library)
+
+# Copy the native assets provided by the build.dart from all packages.
+set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
+install(DIRECTORY "${NATIVE_ASSETS_DIR}"
+   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
+   COMPONENT Runtime)
+
+# Fully re-copy the assets directory on each build to avoid having stale files
+# from a previous install.
+set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
+install(CODE "
+  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
+  " COMPONENT Runtime)
+install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
+  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)
+
+# Install the AOT library on non-Debug builds only.
+if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
+  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
+    COMPONENT Runtime)
+endif()
@@ -0,0 +1,88 @@
+# This file controls Flutter-level build steps. It should not be edited.
+cmake_minimum_required(VERSION 3.10)
+
+set(EPHEMERAL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/ephemeral")
+
+# Configuration provided via flutter tool.
+include(${EPHEMERAL_DIR}/generated_config.cmake)
+
+# TODO: Move the rest of this into files in ephemeral. See
+# https://github.com/flutter/flutter/issues/57146.
+
+# Serves the same purpose as list(TRANSFORM ... PREPEND ...),
+# which isn't available in 3.10.
+function(list_prepend LIST_NAME PREFIX)
+    set(NEW_LIST "")
+    foreach(element ${${LIST_NAME}})
+        list(APPEND NEW_LIST "${PREFIX}${element}")
+    endforeach(element)
+    set(${LIST_NAME} "${NEW_LIST}" PARENT_SCOPE)
+endfunction()
+
+# === Flutter Library ===
+# System-level dependencies.
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
+pkg_check_modules(GLIB REQUIRED IMPORTED_TARGET glib-2.0)
+pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)
+
+set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/libflutter_linux_gtk.so")
+
+# Published to parent scope for install step.
+set(FLUTTER_LIBRARY ${FLUTTER_LIBRARY} PARENT_SCOPE)
+set(FLUTTER_ICU_DATA_FILE "${EPHEMERAL_DIR}/icudtl.dat" PARENT_SCOPE)
+set(PROJECT_BUILD_DIR "${PROJECT_DIR}/build/" PARENT_SCOPE)
+set(AOT_LIBRARY "${PROJECT_DIR}/build/lib/libapp.so" PARENT_SCOPE)
+
+list(APPEND FLUTTER_LIBRARY_HEADERS
+  "fl_basic_message_channel.h"
+  "fl_binary_codec.h"
+  "fl_binary_messenger.h"
+  "fl_dart_project.h"
+  "fl_engine.h"
+  "fl_json_message_codec.h"
+  "fl_json_method_codec.h"
+  "fl_message_codec.h"
+  "fl_method_call.h"
+  "fl_method_channel.h"
+  "fl_method_codec.h"
+  "fl_method_response.h"
+  "fl_plugin_registrar.h"
+  "fl_plugin_registry.h"
+  "fl_standard_message_codec.h"
+  "fl_standard_method_codec.h"
+  "fl_string_codec.h"
+  "fl_value.h"
+  "fl_view.h"
+  "flutter_linux.h"
+)
+list_prepend(FLUTTER_LIBRARY_HEADERS "${EPHEMERAL_DIR}/flutter_linux/")
+add_library(flutter INTERFACE)
+target_include_directories(flutter INTERFACE
+  "${EPHEMERAL_DIR}"
+)
+target_link_libraries(flutter INTERFACE "${FLUTTER_LIBRARY}")
+target_link_libraries(flutter INTERFACE
+  PkgConfig::GTK
+  PkgConfig::GLIB
+  PkgConfig::GIO
+)
+add_dependencies(flutter flutter_assemble)
+
+# === Flutter tool backend ===
+# _phony_ is a non-existent file to force this command to run every time,
+# since currently there's no way to get a full input/output list from the
+# flutter tool.
+add_custom_command(
+  OUTPUT ${FLUTTER_LIBRARY} ${FLUTTER_LIBRARY_HEADERS}
+    ${CMAKE_CURRENT_BINARY_DIR}/_phony_
+  COMMAND ${CMAKE_COMMAND} -E env
+    ${FLUTTER_TOOL_ENVIRONMENT}
+    "${FLUTTER_ROOT}/packages/flutter_tools/bin/tool_backend.sh"
+      ${FLUTTER_TARGET_PLATFORM} ${CMAKE_BUILD_TYPE}
+  VERBATIM
+)
+add_custom_target(flutter_assemble DEPENDS
+  "${FLUTTER_LIBRARY}"
+  ${FLUTTER_LIBRARY_HEADERS}
+)
@@ -0,0 +1,15 @@
+//
+//  Generated file. Do not edit.
+//
+
+// clang-format off
+
+#include "generated_plugin_registrant.h"
+
+#include <flutter_secure_storage_linux/flutter_secure_storage_linux_plugin.h>
+
+void fl_register_plugins(FlPluginRegistry* registry) {
+  g_autoptr(FlPluginRegistrar) flutter_secure_storage_linux_registrar =
+      fl_plugin_registry_get_registrar_for_plugin(registry, "FlutterSecureStorageLinuxPlugin");
+  flutter_secure_storage_linux_plugin_register_with_registrar(flutter_secure_storage_linux_registrar);
+}
@@ -0,0 +1,15 @@
+//
+//  Generated file. Do not edit.
+//
+
+// clang-format off
+
+#ifndef GENERATED_PLUGIN_REGISTRANT_
+#define GENERATED_PLUGIN_REGISTRANT_
+
+#include <flutter_linux/flutter_linux.h>
+
+// Registers Flutter plugins.
+void fl_register_plugins(FlPluginRegistry* registry);
+
+#endif  // GENERATED_PLUGIN_REGISTRANT_
@@ -0,0 +1,24 @@
+#
+# Generated file, do not edit.
+#
+
+list(APPEND FLUTTER_PLUGIN_LIST
+  flutter_secure_storage_linux
+)
+
+list(APPEND FLUTTER_FFI_PLUGIN_LIST
+)
+
+set(PLUGIN_BUNDLED_LIBRARIES)
+
+foreach(plugin ${FLUTTER_PLUGIN_LIST})
+  add_subdirectory(flutter/ephemeral/.plugin_symlinks/${plugin}/linux plugins/${plugin})
+  target_link_libraries(${BINARY_NAME} PRIVATE ${plugin}_plugin)
+  list(APPEND PLUGIN_BUNDLED_LIBRARIES $<TARGET_FILE:${plugin}_plugin>)
+  list(APPEND PLUGIN_BUNDLED_LIBRARIES ${${plugin}_bundled_libraries})
+endforeach(plugin)
+
+foreach(ffi_plugin ${FLUTTER_FFI_PLUGIN_LIST})
+  add_subdirectory(flutter/ephemeral/.plugin_symlinks/${ffi_plugin}/linux plugins/${ffi_plugin})
+  list(APPEND PLUGIN_BUNDLED_LIBRARIES ${${ffi_plugin}_bundled_libraries})
+endforeach(ffi_plugin)
@@ -0,0 +1,26 @@
+cmake_minimum_required(VERSION 3.13)
+project(runner LANGUAGES CXX)
+
+# Define the application target. To change its name, change BINARY_NAME in the
+# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
+# work.
+#
+# Any new source files that you add to the application should be added here.
+add_executable(${BINARY_NAME}
+  "main.cc"
+  "my_application.cc"
+  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
+)
+
+# Apply the standard set of build settings. This can be removed for applications
+# that need different build settings.
+apply_standard_settings(${BINARY_NAME})
+
+# Add preprocessor definitions for the application ID.
+add_definitions(-DAPPLICATION_ID="${APPLICATION_ID}")
+
+# Add dependency libraries. Add any application-specific dependencies here.
+target_link_libraries(${BINARY_NAME} PRIVATE flutter)
+target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)
+
+target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")
@@ -0,0 +1,6 @@
+#include "my_application.h"
+
+int main(int argc, char** argv) {
+  g_autoptr(MyApplication) app = my_application_new();
+  return g_application_run(G_APPLICATION(app), argc, argv);
+}
--- a/Show More
+++ b/Show More