> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swiftaiboilerplate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Sync Setup

> Enable cross-device conversation synchronization

<Info>
  Chat sync is **optional and off by default** — chat history stays local-only in SwiftData until you enable it. The complete setup guide lives at `docs/integrations/ChatSync.md` in your project.
</Info>

## What Is Chat Sync?

<CardGroup cols={2}>
  <Card title="Offline-First" icon="wifi-slash">
    Writes go to the local database first
  </Card>

  <Card title="Background Sync" icon="cloud-arrow-up">
    Syncs to cloud in background
  </Card>

  <Card title="Cross-Device" icon="mobile">
    Access from all devices
  </Card>

  <Card title="Optional" icon="toggle-on">
    Enable only when needed
  </Card>
</CardGroup>

## Quick Overview

<Steps>
  <Step title="Run Migration">
    Create Supabase tables:

    ```bash theme={null}
    # In Supabase Dashboard SQL Editor
    # Run: supabase/migrations/20241016000000_chat_sync.sql
    ```
  </Step>

  <Step title="Enable the Feature Flag">
    Flip the `chatSyncEnabled` flag in `SwiftAIBoilerplatePro/Composition/FeatureFlags.swift`. By default it is `false` in DEBUG and reads the `CHAT_SYNC_ENABLED` environment variable in Release:

    ```swift theme={null}
    public static var chatSyncEnabled: Bool {
        #if DEBUG
        return false // Off by default in debug — change to true to test locally
        #else
        return ProcessInfo.processInfo.environment["CHAT_SYNC_ENABLED"] == "true"
        #endif
    }
    ```
  </Step>

  <Step title="Uncomment the Supabase Implementations">
    Both Supabase repositories ship commented out until the Supabase dependency is added. Uncomment them in the Storage package:

    * `Packages/Storage/Sources/Storage/Repositories/SupabaseConversationRepository.swift`
    * `Packages/Storage/Sources/Storage/Repositories/SupabaseMessageRepository.swift`
  </Step>

  <Step title="Wire Up the Hybrid Repositories in CompositionRoot">
    In `SwiftAIBoilerplatePro/Composition/CompositionRoot.swift`, the chat-sync branch currently falls back to the local repositories (a `// TODO: wire Supabase remote repos once a signed-in user id is available` marks the spot). Replace that with the hybrid repositories once you have a signed-in user id:

    ```swift theme={null}
    self.conversationRepository = HybridConversationRepository(
        local: localConversationRepo,
        remote: remoteConversationRepo
    )
    self.messageRepository = HybridMessageRepository(
        local: localMessageRepo,
        remote: remoteMessageRepo
    )
    ```
  </Step>
</Steps>

## How It Works

```text theme={null}
Write Flow:
User sends message → Local SwiftData (instant) → Background sync to Supabase

Read Flow:
App opens → Show local data (instant) → Background pull from Supabase → Update UI
```

`HybridConversationRepository` and `HybridMessageRepository` write to the local SwiftData store first and sync to the remote Supabase repository in a background `Task`. If the remote write fails, the local save still succeeds, so the app keeps working offline.

## Prerequisites

* Supabase project configured (see [Supabase Setup](/pages/guides/supabase-setup))
* Supabase dependency added to the Storage package
* User authenticated

## What You Get

* Conversations and messages sync across devices
* Offline-first behavior preserved (local writes never block on the network)
* Background sync that degrades gracefully when the remote is unavailable

## Complete Guide

The full `docs/integrations/ChatSync.md` guide covers the database schema, Row Level Security policies, repository implementations, the hybrid sync strategy, conflict resolution, testing, and troubleshooting.

<Card title="View Complete Setup Guide" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/integrations/ChatSync.md">
  Full chat sync guide with architecture diagrams, in your project repo
</Card>

## Related Guides

<CardGroup cols={2}>
  <Card title="Storage Module" icon="database" href="/pages/modules/storage">
    Repository architecture
  </Card>

  <Card title="Profile Photos" icon="image" href="/pages/guides/profile-photos">
    Another optional sync feature
  </Card>

  <Card title="Supabase Setup" icon="server" href="/pages/guides/supabase-setup">
    Required backend
  </Card>

  <Card title="Building Your App" icon="hammer" href="/pages/guides/building-your-app">
    Customize features
  </Card>
</CardGroup>

## Need Help?

* Troubleshooting section in the full `docs/integrations/ChatSync.md` guide
* [Create an issue](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/issues)
* Check the Supabase Dashboard logs