# Architecture
Source: https://docs.swiftaiboilerplate.com/pages/architecture

System design, patterns, and module structure of SwiftAI Boilerplate Pro

SwiftAI Boilerplate Pro uses modern iOS development patterns with clean separation of concerns.

<Info>
  **Full technical details:** See `docs/foundations/Architecture.md` in your project for complete technical coverage.
</Info>

## Core Principles

### 1. MVVM Architecture

Clean separation between UI, business logic, and data:

**Benefits:**

* ✅ Views are dumb (no business logic)
* ✅ ViewModels are testable (no UIKit dependencies)
* ✅ Business logic isolated and reusable
* ✅ Clear data flow

### 2. Dependency Injection

Centralized composition with `CompositionRoot`:

```swift theme={null}
/// Central dependency injection container
/// Builds and owns all app-wide singletons and factories
@MainActor
@available(iOS 17.0, *)
public final class CompositionRoot {
    
    // MARK: - Singletons
    
    /// SwiftData model container
    public let modelContainer: ModelContainer
    
    /// HTTP client with interceptors
    public let httpClient: any HTTPClient

    /// Keychain storage
    public let keychainStore: KeychainStore

    /// Auth client (SessionManager wrapper in production, MockAuthClient in DEBUG)
    public let sessionManager: any AuthClient

    /// LLM client (ProxyLLMClient when configured, EchoLLMClient otherwise)
    public let llmClient: any LLMClient
    // ...
}

// View-model factories live in CompositionRoot+Factories.swift:
extension CompositionRoot {
    /// Create ChatViewModel with injected dependencies
    public func makeChatViewModel(conversationID: UUID) -> ChatViewModel {
        ChatViewModel(
            conversationID: conversationID,
            messageRepository: messageRepository,
            llmClient: llmClient,
            paymentsStatusProvider: PaymentsStatusAdapter(paymentsClient: paymentsClient)
        )
    }
}
```

**Benefits:**

* ✅ No global singletons
* ✅ Easy to mock for testing
* ✅ Clear dependency graph
* ✅ Compile-time safety

### 3. Protocol-Oriented Design

All external dependencies use protocols:

```swift theme={null}
/// Main authentication client protocol
@available(iOS 17.0, *)
@preconcurrency
public protocol AuthClient: Sendable {
    /// Sign in with Apple ID
    func signInWithApple() async throws -> AuthUser
    
    /// Sign in with Google
    func signInWithGoogle() async throws -> AuthUser
    // ...
}

// Implementations:
// - SessionManager (production actor; wrapped to AuthClient via SessionManagerWrapper)
// - MockAuthClient (DEBUG-only fallback)
```

**Benefits:**

* ✅ Swappable implementations
* ✅ Easy testing with mocks
* ✅ No vendor lock-in
* ✅ Clear contracts

## Module Structure

### 11 Swift Packages

<CardGroup>
  <Card title="Core" icon="cube" href="/pages/modules/core">
    Foundation utilities, errors, logging
  </Card>

  <Card title="Networking" icon="wifi" href="/pages/modules/networking">
    HTTP client with interceptors
  </Card>

  <Card title="Storage" icon="database" href="/pages/modules/storage">
    SwiftData models, repositories
  </Card>

  <Card title="Auth" icon="shield" href="/pages/modules/auth">
    Authentication clients
  </Card>

  <Card title="Payments" icon="dollar" href="/pages/modules/payments">
    Subscription management
  </Card>

  <Card title="AI" icon="brain" href="/pages/modules/ai">
    LLM client protocol
  </Card>

  <Card title="FeatureChat" icon="comments" href="/pages/modules/feature-chat">
    Chat UI, ViewModels; owns `LLMClient`/`LLMMessage`
  </Card>

  <Card title="FeatureRating" icon="star" href="/pages/reference/features">
    Sentiment-based rating prompts
  </Card>

  <Card title="FeatureSettings" icon="gear" href="/pages/modules/feature-settings">
    Settings and paywall UI
  </Card>

  <Card title="DesignSystem" icon="swatchbook" href="/pages/modules/design-system">
    Tokens, components, Liquid Glass, accessibility
  </Card>

  <Card title="Localization" icon="globe" href="/pages/modules/localization">
    Type-safe strings, pluralization, i18n
  </Card>
</CardGroup>

<Note>
  A 12th package, **TestSupport** (`Packages/TestSupport`), ships shared test
  infrastructure (e.g. `URLProtocolStub`). It is test-only — not a reusable product
  module — so the "11 Swift Packages cleanly separated for reuse" claim still stands.
</Note>

**Dependency graph (from `template.manifest.json`):**

```text theme={null}
Core            → (no dependencies)
TestSupport     → (no dependencies, test-only)
DesignSystem    → (no dependencies)
Networking      → Core
Storage         → Core, Networking
Localization    → Core
Payments        → Core
FeatureRating   → Core, DesignSystem
Auth            → Core, Networking, Storage
FeatureChat     → Core, Storage, DesignSystem, Localization
AI              → Core, Networking, FeatureChat   (re-exports FeatureChat)
FeatureSettings → Core, Storage, Auth, Payments, DesignSystem, Localization
```

<Warning>
  **Coupling gotcha:** `LLMClient` and `LLMMessage` live in **FeatureChat**, and the
  **AI** package re-exports FeatureChat. Removing chat without first relocating those two
  types breaks `Packages/AI`. The removal order and module map are documented in
  `docs/checklists/APP_STORE_4_3_HARDENING.md`.
</Warning>

**Key principles:**

* ✅ No circular dependencies
* ✅ Core has no dependencies
* ✅ Features depend on services
* ✅ Services depend on infrastructure

## Data Flow

### Chat Message Flow

```text theme={null}
1. User types message → ChatView
2. ChatView calls → ChatViewModel.send()
3. ChatViewModel:
   - Appends message → MessageRepository
   - Streams AI response → LLMClient.streamResponse(messages:)
   - Mutates @Observable state on the main actor
4. View automatically re-renders
```

### Authentication Flow

```text theme={null}
1. User enters credentials → SignInView
2. View calls → AuthViewModel.signIn()
3. AuthViewModel calls → AuthClient.signInWithEmail(email:password:)
4. SessionManager (the AuthClient):
   - Calls Supabase API
   - Persists tokens → Keychain (via SessionStore)
   - Returns AuthUser, emits via authStates()
5. LaunchRouter observes the auth state change
6. Navigation switches to authenticated content
```

## iOS 26 Liquid Glass Layer

The DesignSystem package ships a dedicated Liquid Glass primitive.

**Primitive:** `Packages/DesignSystem/Sources/DesignSystem/Materials/SAIGlass.swift`

* **`SAIGlassStyle`**: `.regular` (default surface) and `.clear` (edge-to-edge hero surfaces).
* **`.saiGlass(...)` modifier**: one-call glass treatment for any view.
* **`SAIGlassContainer`**: merges nearby glass surfaces so adjacent cards, toolbars, and sheets sample the same background instead of stacking visually.

**Availability strategy:**

* **iOS 26+**: uses the native `Glass` material, `glassEffect`, and `GlassEffectContainer`.
* **iOS 17–25**: falls back to SwiftUI `Material` automatically. Same call sites, progressive enhancement at runtime.

The same file also exports `saiScrollEdgeGlass(_:)`, `saiSidebarAdaptable()`, `saiTabBarMinimize(_:)`, and `SAITabBarMinimizeStyle` for shell-level polish.

See [Design System Module](/pages/modules/design-system#liquid-glass) for the full API.

## Swift 6 Concurrency Model

The entire codebase builds under **strict concurrency checking** on the Swift 6 toolchain.

* **`@MainActor`-pinned storage repositories**: `MessageRepositoryImpl`, `ConversationRepositoryImpl`, and `SettingsRepositoryImpl` are all main-actor-isolated.
* **`@Observable` throughout**: view models and observable stores use the `@Observable` macro. No `ObservableObject`, no `@Published`, no `.onReceive`.
* **No `DispatchQueue.main` in app code**: all main-thread work goes through `@MainActor` or `MainActor.run`.
* **Explicit `any`**: every protocol-typed property and parameter uses the `any` keyword, as Swift 6 requires.
* **Async/await throughout**: no completion handlers, structured concurrency for cancellation, `Sendable` where crossing actor boundaries.

```swift theme={null}
@MainActor
@Observable
public final class ChatViewModel {
    private let messageRepository: any MessageRepository
    private let llmClient: any LLMClient
    ...
}
```

## Architecture Rule: ≤ 400 Lines Per File

A workspace-wide ceiling keeps every production and test Swift file ≤ 400 lines (enforced by `.swiftlint.yml` `file_length: warning: 400`). When a type grows past that, it moves into extension-split siblings in the same folder.

Examples in the codebase:

* `SessionManager.swift` → `SessionManager+SignIn`, `+Refresh`, `+Persistence`
* `L10n` strings → `L10n+<Namespace>.swift` per nested enum (Auth, Chat, Settings, …)
* `SettingsView.swift` → a 125-line composition root with sections split out
* `ChatViewModel.swift` → `ChatViewModel+Memory.swift`

Why: keeps files scannable, keeps diffs small, keeps agent context windows productive.

## Concurrency Primitives

### Async/Await Throughout

```swift theme={null}
/// Send the current input text.
public func send() async {
    // 1. Validate input (skip empty/whitespace)
    // 2. Append the user message via MessageRepository
    // 3. Stream the AI reply: llmClient.streamResponse(messages:)
    // 4. Mutate @Observable state on the main actor as tokens arrive
}
```

**Benefits:**

* ✅ No completion handlers
* ✅ Structured concurrency (cancellable stream tasks)
* ✅ MainActor for UI updates
* ✅ Sendable for thread safety

## Testing Strategy

The whole workspace runs in **one pass** via `Boilerplate.xctestplan`: **\~598 tests across 12 package test targets + the app test suites** (`SwiftAIBoilerplateProTests` unit + `SwiftAIBoilerplateProUITests`). A single `xcodebuild test` covers everything:

```bash theme={null}
xcodebuild test \
  -project SwiftAIBoilerplatePro.xcodeproj \
  -scheme SwiftAIBoilerplatePro \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2' \
  CODE_SIGNING_ALLOWED=NO
```

The 12 package test targets are: `CoreTests`, `TestSupportTests`, `NetworkingTests`, `StorageTests`, `AuthTests`, `DesignSystemTests`, `FeatureChatTests`, `FeatureRatingTests`, `FeatureSettingsTests`, `PaymentsTests`, `LocalizationTests`, `AITests`. (`TestSupportTests` exercises the shared test-infrastructure package.)

### Unit Tests

Test ViewModels and repositories in isolation, injecting fakes for external clients:

```swift theme={null}
func testSendStreamsReply() async throws {
    let viewModel = ChatViewModel(
        conversationID: UUID(),
        messageRepository: messageRepository,
        llmClient: EchoLLMClient() // dev fallback echoes the prompt
    )
    viewModel.inputText = "Hello"

    await viewModel.send()

    XCTAssertFalse(viewModel.messages.isEmpty)
}
```

### Integration Tests

Test component interaction through the composition root:

```swift theme={null}
@MainActor
func testCompositionRoot() throws {
    let authConfig = AuthConfig(
        supabaseURL: URL(string: "https://test.supabase.co")!,
        supabaseAnonKey: "test_anon_key"
    )
    let paymentsConfig = PaymentsConfig(
        apiKey: "test_api_key",
        entitlementID: "test_entitlement"
    )
    let composition = try CompositionRoot(
        authConfig: authConfig,
        paymentsConfig: paymentsConfig
    )

    // Dependencies are wired
    XCTAssertNotNil(composition.httpClient)
    XCTAssertNotNil(composition.sessionManager)

    // Factories produce view models
    let chatVM = composition.makeChatViewModel(conversationID: UUID())
    XCTAssertNotNil(chatVM)
}
```

### UI Tests

Test end-to-end flows. UI suites need the `UI_TESTING=1` launch hook so the first-launch onboarding/permission alert does not block them:

```swift theme={null}
func testChatFlow() throws {
    let app = XCUIApplication()
    app.launchEnvironment["UI_TESTING"] = "1"
    app.launch()

    app.buttons["Start Chat"].tap()

    let textField = app.textFields["messageInput"]
    textField.tap()
    textField.typeText("Hello AI")
    app.buttons["send"].tap()

    XCTAssertTrue(app.staticTexts["Hello AI"].waitForExistence(timeout: 5))
}
```

## Customization Entry Points

<Tip>
  **App Generator (coming soon, separate product).** A standalone macOS app that drives
  your own coding-agent CLI (Claude Code / Codex / Gemini / Cursor) to generate a
  differentiated, App Store Guideline 4.3(a)-safe app *from* this template — using the
  module graph and recipes documented above. It is a separate purchase, not bundled in the
  boilerplate, and ships no LLM. See [License & Updates](/pages/reference/license) for the
  pricing model (grandfathered buyers get access when it ships).
</Tip>

### Add New Feature

1. **Create package** (if needed): `Packages/FeatureX/`
2. **Create models**: Define SwiftData models in `Storage`
3. **Create repository**: Data access layer
4. **Create ViewModel**: Business logic
5. **Create View**: SwiftUI interface
6. **Wire in CompositionRoot**: Add factory method

### Replace Backend

Implement the protocol:

```swift theme={null}
// Want to use Firebase instead of Supabase? Conform to the AuthClient protocol.
final class FirebaseAuthClient: AuthClient {
    func signInWithEmail(email: String, password: String) async throws -> AuthUser {
        // Firebase implementation
    }
    // ... signInWithApple, signInWithGoogle, signOut, currentUser, authStates, etc.
}

// Then wire it in CompositionRoot:
self.sessionManager = FirebaseAuthClient(...)
```

<Note>
  This swap snippet is illustrative — there is no `FirebaseAuthClient` in the template.
  The production implementation is `SessionManager` (a Supabase-backed actor) adapted to
  `AuthClient` via `SessionManagerWrapper`.
</Note>

### Add UI Components

1. Create component in `DesignSystem/Components/`
2. Use design tokens (DSColors, DSSpacing, etc.)
3. Add preview
4. Add snapshot test
5. Use in features

## Best Practices Applied

<AccordionGroup>
  <Accordion title="Code Organization">
    * Files ≤ 400 lines (extension-split when larger)
    * One type per file
    * MARK comments for navigation
    * Grouped by responsibility
  </Accordion>

  <Accordion title="Error Handling">
    * All errors mapped to `AppError`
    * User-friendly messages
    * Technical details logged
    * Never swallow errors silently
  </Accordion>

  <Accordion title="Naming">
    * Clear, explicit names
    * No abbreviations in public API
    * Consistent conventions
    * Self-documenting code
  </Accordion>

  <Accordion title="Performance">
    * Lazy loading (messages, images)
    * Cursor-based pagination
    * Image compression
    * Offline-first data access
    * Background sync
  </Accordion>

  <Accordion title="Security">
    * Tokens in Keychain (never UserDefaults)
    * API keys server-side only
    * PII redacted in logs
    * Row Level Security (Supabase)
  </Accordion>
</AccordionGroup>

## Key Files

| Purpose                  | File Location                                             |
| ------------------------ | --------------------------------------------------------- |
| **Dependency Injection** | `SwiftAIBoilerplatePro/Composition/CompositionRoot.swift` |
| **Feature Flags**        | `SwiftAIBoilerplatePro/Composition/FeatureFlags.swift`    |
| **App Entry**            | `SwiftAIBoilerplatePro/SwiftAIBoilerplatePro.swift`       |
| **Navigation**           | `SwiftAIBoilerplatePro/AppShell/MainTabView.swift`        |
| **Auth Router**          | `SwiftAIBoilerplatePro/AppShell/LaunchRouter.swift`       |

## Learn More

<CardGroup>
  <Card title="Core Module" icon="cube" href="/pages/modules/core">
    Error handling, logging, utilities
  </Card>

  <Card title="Networking" icon="wifi" href="/pages/modules/networking">
    HTTP client architecture
  </Card>

  <Card title="Storage" icon="database" href="/pages/modules/storage">
    SwiftData and repositories
  </Card>

  <Card title="docs/CLAUDE.md" icon="robot" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/CLAUDE.md">
    Guidelines for AI-assisted development
  </Card>
</CardGroup>

<Info>
  **Find full technical documentation in your project:** [Architecture.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/foundations/Architecture.md)
</Info>


# AI-Assisted Development
Source: https://docs.swiftaiboilerplate.com/pages/guides/ai-assisted-development

Build faster with Claude Code, Xcode Coding Intelligence, Cursor AI, and Bolt AI. Pre-configured CLAUDE.md, .cursor rules, and .bolt chat modes included.

SwiftAI Boilerplate Pro ships with configurations for Claude-powered iOS development across **Claude Code**, **Xcode Coding Intelligence**, **Cursor AI**, and **Bolt AI**. Each setup points the assistant at the same project architecture so generated code fits the boilerplate instead of guessing.

No setup required. Open the project and start building.

<Note>
  Building a separate app from this template? The **App Generator** is a standalone macOS product (coming soon) that drives your own coding-agent CLI to scaffold a differentiated, App Store Guideline 4.3-safe app from the boilerplate. See [Pricing & License](/pages/reference/license) for details and the waitlist.
</Note>

***

## Recommended Setup

For most SwiftAI Boilerplate Pro projects, start here:

<Steps>
  <Step title="Open the repository root">
    Open the folder that contains `AGENTS.md`, `SwiftAIBoilerplatePro.xcodeproj`, `Packages/`, and `docs/`. The root `AGENTS.md` is the shared entry point that points every agent at `docs/CLAUDE.md` and `docs/INDEX.md`.
  </Step>

  <Step title="Use Xcode Coding Intelligence for build-aware work">
    Xcode Coding Intelligence with Claude Agent is a strong fit for Swift apps because it can stay close to Xcode's project, build, simulator, and diagnostics workflow.
  </Step>

  <Step title="Use Claude Code for larger agentic changes">
    Claude Code is best when you want the agent to inspect many files, implement a full feature, run commands, and iterate until the project builds.
  </Step>

  <Step title="Use Cursor for focused editing">
    Cursor is useful for inline edits, local refactors, and reviewing generated code while you are already working in the editor.
  </Step>
</Steps>

<Tip>
  If Claude says it does not see the project instructions, ask it to summarize `docs/CLAUDE.md`. If it cannot, restart the agent from the repository root rather than from a subdirectory or a single file.
</Tip>

## Tool Comparison

| Tool                          | Best For                                                             | Project Context                                                              |
| ----------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Xcode Coding Intelligence** | Swift app work inside Xcode, build issues, simulator-aware iteration | Reads root `AGENTS.md` → `docs/CLAUDE.md` when started from the project root |
| **Claude Code**               | Larger autonomous coding tasks and verification loops                | Reads root `AGENTS.md`, which points to `docs/CLAUDE.md`                     |
| **Cursor AI**                 | Inline edits, refactors, and code review while editing               | Reads `.cursor/rules/*.mdc` (plus `AGENTS.md`)                               |
| **Bolt AI chat modes**        | Specialized chat personas and prompt-driven workflows                | Uses `.bolt/chat-modes.json` and project files you provide as context        |

***

## Claude Code and Claude Agent (`CLAUDE.md`)

The boilerplate includes a production-tested `docs/CLAUDE.md` that gives [Claude Code](https://claude.ai/code) full project context. A root `AGENTS.md` is the shared entry point all agents read first; it points Claude Code, Cursor, Codex, and others at `docs/CLAUDE.md` and `docs/INDEX.md`, so generated code fits the boilerplate from the first message.

### What CLAUDE.md Covers

* **Architecture:** MVVM patterns, module boundaries, which abstractions to use
* **Build commands:** Environment-aware instructions for Xcode MCP vs Claude Code CLI
* **Anti-patterns:** No UIKit, no ObservableObject, no raw URLSession
* **File conventions:** Naming patterns, organization, where new code belongs
* **Integration specifics:** Supabase, RevenueCat, OpenRouter configuration

### How Agentic Development Works

1. Open Claude Code in your project directory
2. Describe the feature you want
3. Claude reads your codebase, generates code following your patterns, builds it, and iterates until it works

Claude understands the module boundaries, uses the right abstractions, and writes code that looks like the rest of your project.

### Example Workflow

```text theme={null}
You: "Add a favorites feature. Users should be able to bookmark conversations
     and see them in a dedicated tab."

Claude Code:
  - Reads AGENTS.md / docs/CLAUDE.md and the existing module structure
  - Creates SwiftData model in Storage package
  - Adds FavoritesRepository with protocol
  - Builds FavoritesViewModel (@Observable) following MVVM pattern
  - Creates FavoritesView using DesignSystem tokens
  - Wires dependencies through CompositionRoot
  - Runs build to verify compilation
```

### Community Skills

You can extend Claude's iOS knowledge with community skills. These teach Claude about platform conventions, Xcode tooling, and SwiftUI best practices.

<CardGroup>
  <Card title="Apple Platform Skills" icon="apple">
    Apple platform conventions, Xcode project structure, SwiftUI, and App Store review awareness.

    ```bash theme={null}
    git clone https://github.com/rshankras/claude-code-apple-skills.git
    mkdir -p .claude/skills
    cp -R claude-code-apple-skills/skills/* .claude/skills/
    ```

    Source: [rshankras/claude-code-apple-skills](https://github.com/rshankras/claude-code-apple-skills)
  </Card>

  <Card title="iOS Simulator" icon="mobile">
    Lets Claude boot, build, install, and interact with the iOS Simulator directly.

    ```text theme={null}
    /plugin marketplace add conorluddy/ios-simulator-skill
    /plugin install ios-simulator-skill@conorluddy
    ```

    Source: [conorluddy/ios-simulator-skill](https://github.com/conorluddy/ios-simulator-skill)
  </Card>
</CardGroup>

Run `/plugin ...` commands inside Claude Code or Claude Agent chat. Run `git`, `cp`, and `npx` commands in your terminal. For the full list of recommended skills and module mappings, see the [Agentic Development Setup guide](/pages/guides/skills-setup).

***

## Cursor AI Rules (`.cursor/rules/`)

[Cursor AI](https://cursor.sh) reads `.mdc` (Markdown Code) files from your project to understand patterns and constraints. Six rule files are included.

### Included Rule Files

<CardGroup>
  <Card title="core.mdc" icon="cube">
    **Applied to:** All Swift files

    File size limits (max 400 lines), MVVM patterns, dependency injection, error handling, Swift Concurrency, testing requirements.
  </Card>

  <Card title="swiftui-views.mdc" icon="mobile">
    **Applied to:** View files (`*View.swift`)

    View composition, state management, list optimization, navigation, form handling, accessibility.
  </Card>

  <Card title="architecture.mdc" icon="sitemap">
    **Applied to:** Repositories, Clients, Packages

    Modular package boundaries, protocol-based APIs, repository pattern, CompositionRoot, structured logging, test doubles.
  </Card>

  <Card title="design-system.mdc" icon="palette">
    **Applied to:** DesignSystem, AppShell

    DSColors tokens, DSTypography type scale, DSSpacing tokens, component library usage, theme consistency.
  </Card>

  <Card title="app-store-differentiation.mdc" icon="shield">
    **Applied to:** Swift, config, and Markdown files

    Guideline 4.3(a) differentiation (binary, metadata, concept), the `APP_STORE_4_3_HARDENING.md` checklist, and the FeatureChat to AI coupling when removing chat.
  </Card>

  <Card title="ios-platform-safety.mdc" icon="lock">
    **Applied to:** Swift, `Info.plist`, `PrivacyInfo.xcprivacy`

    Public APIs only, Swift 6 concurrency, permission strings and privacy manifests, StoreKit/IAP for digital goods, accessibility baselines, and secrets via the existing `HTTPClient` + xcconfig.
  </Card>
</CardGroup>

### How It Works

Open the project in Cursor. The rules load automatically. Ask Cursor to build something, and it follows your architecture.

```text theme={null}
You: "Create a new chat settings view"

Cursor generates code with:
  - DSColors, DSTypography, DSSpacing (DesignSystem tokens)   ✅
  - Protocol-based dependencies (testable)                    ✅
  - Under 400 lines (properly composed)                       ✅
  - Loading and error states                                  ✅
  - Accessibility labels                                       ✅
```

### Example Prompts

<AccordionGroup>
  <Accordion title="Creating Views">
    ```text theme={null}
    "Create a new settings view using DesignSystem components"
    "Add a profile page with avatar, name, email, and sign-out"
    "Build a subscription paywall with three tiers"
    ```

    Cursor will use DSColors for colors, DSTypography for type, DSSpacing for layout, and create a proper `@Observable` ViewModel with loading and error states.
  </Accordion>

  <Accordion title="Creating ViewModels">
    ```text theme={null}
    "Add a ProfileViewModel with user info and sign-out"
    "Create SettingsViewModel with theme switching"
    "Build ChatViewModel with message streaming"
    ```

    Cursor will mark ViewModels as `@MainActor @Observable`, inject dependencies via initializer, use protocol types, and add structured logging.
  </Accordion>

  <Accordion title="Creating Feature Packages">
    ```text theme={null}
    "Create a new feature package for Notifications"
    "Add a feature package for User Profile"
    ```

    Cursor will create proper Package.swift, define protocol-based public APIs, keep implementation internal, and add tests.
  </Accordion>

  <Accordion title="Refactoring">
    ```text theme={null}
    "Refactor this to use repository pattern"
    "Extract this logic to a separate package"
    "Convert this to use DesignSystem components"
    ```
  </Accordion>
</AccordionGroup>

***

## Bolt AI Chat Modes (`.bolt/`)

[Bolt AI](https://bolt.new) provides **12 specialized AI assistants** for different development tasks. Each mode loads relevant context and uses a domain-specific system prompt.

### Available Chat Modes

<CardGroup>
  <Card title="iOS Developer" icon="code">
    `/dev` (default). General iOS/SwiftUI development with MVVM and async/await.
  </Card>

  <Card title="Architecture Advisor" icon="sitemap">
    `/arch`. Package boundaries, protocol-based APIs, clean architecture.
  </Card>

  <Card title="SwiftUI" icon="mobile">
    `/ui`. View composition, DesignSystem usage, state management, accessibility.
  </Card>

  <Card title="Feature Dev" icon="puzzle">
    `/feature`. Self-contained feature modules with protocol APIs and tests.
  </Card>

  <Card title="Integration" icon="plug">
    `/integration`. Supabase, RevenueCat, Firebase setup and troubleshooting.
  </Card>

  <Card title="Testing" icon="flask">
    `/test`. Unit tests, mock protocols, test doubles, async testing.
  </Card>

  <Card title="Debug" icon="bug">
    `/debug`. Bug diagnosis, crash analysis, memory leaks, performance.
  </Card>

  <Card title="Performance" icon="gauge">
    `/perf`. Memory management, lazy loading, rendering optimization.
  </Card>

  <Card title="Package Dev" icon="box">
    `/package`. Swift Package Manager, API design, dependencies.
  </Card>

  <Card title="Deploy" icon="rocket">
    `/deploy`. App Store submission, TestFlight, provisioning, CI/CD.
  </Card>

  <Card title="Accessibility" icon="universal-access">
    `/a11y`. VoiceOver, Dynamic Type, inclusive design, WCAG compliance.
  </Card>

  <Card title="Documentation" icon="book">
    `/doc`. Technical writing, API docs, integration guides.
  </Card>
</CardGroup>

***

## Before and After

Without configurations, AI generates code with hardcoded colors, no ViewModel, direct singleton dependencies, and no error handling. With configurations, the same prompt produces code that follows your architecture.

### Without Configurations

**Prompt:** "Create a user profile view with avatar and sign-out"

```swift theme={null}
struct ProfileView: View {
  @State var user: User?

  var body: some View {
    VStack {
      Image(systemName: "person.circle")
        .font(.system(size: 80))
        .foregroundColor(.blue)  // ❌ Hardcoded color

      Text(user?.name ?? "")
        .font(.title)  // ❌ Not from DesignSystem

      Button("Sign Out") {  // ❌ No error handling
        AuthManager.shared.signOut()  // ❌ Direct dependency
      }
      .padding()
      .background(Color.red)  // ❌ Hardcoded color
    }
  }
}
```

### With Configurations

**Same prompt**, same AI tool:

```swift theme={null}
import SwiftUI
import DesignSystem
import Auth
import Core

struct ProfileView: View {
  @State private var viewModel: ProfileViewModel

  var body: some View {
    ScrollView {
      VStack(spacing: DSSpacing.lg) {
        Circle()
          .fill(DSColors.primary)
          .frame(width: 80, height: 80)
          .overlay {
            Text(viewModel.user?.name?.prefix(1).uppercased() ?? "")
              .font(DSTypography.titleL)
              .foregroundStyle(.white)
          }

        VStack(spacing: DSSpacing.sm) {
          Text(viewModel.user?.name ?? "Loading...")
            .font(DSTypography.titleM)

          if let email = viewModel.user?.email {
            Text(email)
              .font(DSTypography.body)
              .foregroundStyle(DSColors.textSecondary)
          }
        }

        SAIButton("Sign Out", style: .secondary, layout: .block) {
          Task { await viewModel.signOut() }
        }
        .padding(.top, DSSpacing.lg)
      }
      .padding(DSSpacing.lg)
    }
    .navigationTitle("Profile")
    .alert("Error", isPresented: Binding(
      get: { viewModel.errorMessage != nil },
      set: { if !$0 { viewModel.errorMessage = nil } }
    )) {
      Button("OK") { viewModel.errorMessage = nil }
    } message: {
      Text(viewModel.errorMessage ?? "")
    }
    .task { await viewModel.load() }
  }
}

@MainActor
@Observable
final class ProfileViewModel {
  var user: AuthUser?
  var isLoading = false
  var errorMessage: String?

  private let authClient: any AuthClient

  init(authClient: any AuthClient) {
    self.authClient = authClient
  }

  func load() async {
    isLoading = true
    defer { isLoading = false }
    user = await authClient.currentUser()
  }

  func signOut() async {
    isLoading = true
    errorMessage = nil
    defer { isLoading = false }

    do {
      try await authClient.signOut()
      AppLogger.info("User signed out", category: AppLogger.auth)
    } catch {
      errorMessage = AppError.from(error).localizedUserMessage
      AppLogger.error("Sign out failed: \(error)", category: AppLogger.auth)
    }
  }
}
```

DesignSystem tokens, protocol-based dependencies, proper MVVM with `@Observable`, localized error handling, loading state, structured logging, `@MainActor`, async/await. All from the same one-line prompt.

***

## Customization

### Modifying Cursor Rules

Edit `.mdc` files in `.cursor/rules/`. Each file has YAML frontmatter (`description`, `globs`, `alwaysApply`) followed by markdown sections with good/bad code examples. Changes take effect when you save.

### Modifying CLAUDE.md

Edit `docs/CLAUDE.md` (or the root `AGENTS.md` entry point). Add your own patterns, anti-patterns, or module-specific instructions. Claude picks up changes on the next conversation.

### Adding Bolt Chat Modes

Edit `.bolt/chat-modes.json` to add custom modes:

```json theme={null}
{
  "chatModes": {
    "my-mode": {
      "name": "My Mode",
      "description": "What this mode does",
      "systemPrompt": "Instructions for AI",
      "context": ["paths/to/focus/on"],
      "tools": ["codeGeneration", "fileManagement"]
    }
  }
}
```

***

## Documentation

<CardGroup>
  <Card title="Agentic Development Setup" icon="wand-magic-sparkles" href="/pages/guides/skills-setup">
    CLAUDE.md details and community skills
  </Card>

  <Card title="Cursor Rules README" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/.cursor/README.md">
    Detailed guide on Cursor AI rules
  </Card>

  <Card title="Architecture Guide" icon="sitemap" href="/pages/architecture">
    The patterns AI follows
  </Card>

  <Card title="DesignSystem Guide" icon="palette" href="/pages/modules/design-system">
    Design tokens reference
  </Card>
</CardGroup>

***

## Questions

<AccordionGroup>
  <Accordion title="Do I need Claude Code, Xcode Coding Intelligence, Cursor, or Bolt?">
    None of them are required. All are supported. **Xcode Coding Intelligence** is a great default for Swift work inside Xcode. **Claude Code** works best for agentic development, such as building full features from a description. **Cursor** works best for inline code generation while you edit. **Bolt** works best for chat-based task switching. Use whichever fits your workflow, or combine them.
  </Accordion>

  <Accordion title="Can I use other AI assistants?">
    Yes. The root `AGENTS.md` is read by most coding agents, and the patterns in `docs/CLAUDE.md` and the `.mdc` files work as reference for any AI tool. You can paste relevant sections into ChatGPT, Copilot, or any assistant that accepts context.
  </Accordion>

  <Accordion title="Will this slow down my development?">
    The opposite. AI configurations make code generation faster and more accurate because the AI gets it right the first time. Less time fixing, more time shipping.
  </Accordion>

  <Accordion title="Can I modify the configurations?">
    Yes. Edit `docs/CLAUDE.md` (or root `AGENTS.md`), `.cursor/rules/*.mdc`, or `.bolt/chat-modes.json` to match your preferences. Changes take effect immediately (Cursor, Bolt) or on the next conversation (Claude Code).
  </Accordion>

  <Accordion title="Do the rules apply to my manually-written code?">
    No. These configurations only guide AI code generation. They don't lint or enforce anything on code you write by hand.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Build Your First Feature" icon="hammer" href="/pages/guides/building-your-app">
    Use AI to build a feature with your project's patterns
  </Card>

  <Card title="Architecture Overview" icon="sitemap" href="/pages/architecture">
    Understand the patterns AI follows
  </Card>

  <Card title="Testing Guide" icon="flask" href="/pages/guides/testing">
    Let AI write tests for your features
  </Card>
</CardGroup>


# Before you submit: App Store Guideline 4.3 hardening
Source: https://docs.swiftaiboilerplate.com/pages/guides/app-store-4-3-hardening

How to ship an app built on SwiftAI Boilerplate Pro without getting flagged for spam or template similarity under App Store Review Guideline 4.3. Binary string audits, branding maps, metadata, and an LLM cleanup prompt.

<Warning>
  Apple reviews change. This page reduces the patterns reviewers cite most under [Guideline 4.3](https://developer.apple.com/app-store/review/guidelines/#4.3); it does not guarantee approval. Treat it as a checklist, not a legal opinion.
</Warning>

## What 4.3 actually says

Apple's [Guideline 4.3 (Spam)](https://developer.apple.com/app-store/review/guidelines/#4.3) has two parts. **4.3(a)** says don't ship multiple Bundle IDs of the same app. **4.3(b)** says don't pile into a saturated category without a unique, high-quality experience. There's a related rule, **4.2.6**, about apps "created from a commercialized template or app generation service."

Reviewers don't always cite the sub-letter. When they say "4.3," they usually mean one of three things they noticed:

1. Your binary, listing, and screenshots look too similar to another app already on the store.
2. Your product is functionally identical to a known template (same screens, same flows, same strings).
3. The category is saturated and your app doesn't show a clear reason to exist.

## Shared architecture is fine. Undifferentiated product is not.

Thousands of apps share SwiftUI, RevenueCat, Supabase, and OpenRouter. Apple knows this. What gets flagged is when the **product, listing, and binary fingerprint** all look like a copy of something else. Shared architecture alone does **not** guarantee approval — differentiation is **product + listing + binary**.

Your job before submitting:

* Keep the architecture (it's yours now anyway).
* Replace every user-visible string, asset, and flow that screams "boilerplate."
* Lead your App Store listing with **your** hero feature, not a generic chat screen.
* Strip dead code that ships in the binary and exposes the boilerplate's name.

## What v2.2.0 ships to help you

v2.2.0 makes 4.3(a) hardening a first-class, automatable workflow instead of a manual grep:

<CardGroup>
  <Card title="scripts/appstore-43-audit.sh" icon="terminal-square">
    Builds a **Release** binary, scans the main executable, every app-owned bundle file, and bundled legal/demo markdown for starter fingerprints, then exits non-zero on blocking app-owned hits (and until you replace the starter `BrandConfig.appDisplayName`, set production legal URLs, and rename the upstream bundle ID).
  </Card>

  <Card title="template.manifest.json" icon="braces">
    Machine-readable single source of truth at the repo root: identity surface, module graph (removable + couplings), config schema, the canonical fingerprint list, differentiation rules, recipes, and verification commands. The audit script reads its fingerprint list from here so the script, CI, and agent prompts never diverge.
  </Card>

  <Card title="docs/checklists/APP_STORE_4_3_HARDENING.md" icon="list-checks">
    The full playbook: binary audit, branding/identity map, metadata, App Review Notes template, and per-module removal notes (including coupling rules).
  </Card>

  <Card title="docs/prompts/AppStore4_3Hardening.prompts.md" icon="sparkles">
    Prompt packs for your coding agent, including the must-run starter-fingerprint cleanup (`SwiftAI`, `Boilerplate`, `DesignSystem/SAI`).
  </Card>
</CardGroup>

<Note>
  The **App Generator** ([a separate, standalone macOS product, coming soon](/pages/reference/license)) automates this entire pass — it drives your own coding-agent CLI to generate a differentiated, 4.3-safe app from the template. It ships no LLM and is not bundled in the boilerplate. The steps below are the manual workflow you can run today on any copy of the source.
</Note>

## The steps to take before you hit "Submit"

<Steps>
  <Step title="Run the automated Release audit first">
    Before anything manual, run the bundled audit. It builds a Release configuration, scans the binary and app bundle, and fails on blocking app-owned fingerprints.

    ```bash theme={null}
    # From your distribution repo root
    bash scripts/appstore-43-audit.sh
    ```

    The upstream starter is **expected to fail** until you configure app-specific branding, legal URLs, backend URLs, and bundle identity. The script reports four buckets: main-executable risky strings, app-owned bundle risky strings, bundled legal/demo markdown, and configuration readiness. Third-party SDK noise is reported separately and is non-blocking. Re-run it until every app-owned hit is gone or intentionally documented.
  </Step>

  <Step title="Run a Release `strings` audit on the .ipa">
    The audit script does this for you, but if you want to inspect the binary by hand, reviewers' automated checks compare binary fingerprints. Anything that ships in your Release `.ipa` can match boilerplate fingerprints.

    ```bash theme={null}
    # Build a Release archive in Xcode, then export the .ipa
    unzip -o YourApp.ipa -d /tmp/yourapp
    strings -a /tmp/yourapp/Payload/YourApp.app/YourApp \
      | grep -i -E "swiftai|boilerplate|designsystem/sai|echollm|mockauth" \
      | sort -u
    ```

    The canonical fingerprint list lives in `template.manifest.json` under `fingerprints.patterns`. If the output contains the boilerplate's product name, the `SAI` design-system prefix, dev-only client names, or stub strings, fix the source and rebuild. Don't ship an `.ipa` whose strings give away its origin.
  </Step>

  <Step title="Remove dead Swift files from the app target">
    Files that aren't referenced by your app's UI but are still in the **app target** still compile into the binary. That includes example views, sample data, and demo flows you replaced.

    Open Xcode → Project navigator → check Target Membership for every file in `Features/`, `Examples/`, and any `*Sample*.swift`. Anything you don't use, remove from the app target (you can keep the file on disk if you want it for reference).

    See the per-module removal notes in `docs/checklists/APP_STORE_4_3_HARDENING.md` in your distribution repo. Removing a module without pruning its couplings leaves orphaned code paths in the binary — see the module-coupling step below before deleting FeatureChat, AI, or Payments.
  </Step>

  <Step title="Rebrand every user-visible string">
    Search the codebase for the boilerplate's product name and replace it everywhere a user can see it: launch screen, onboarding, settings, paywall, push copy, error toasts, support email, About screen, legal pages.

    ```bash theme={null}
    # In your project root
    rg -i "swiftai|boilerplate" \
      --type swift --type plist \
      --glob '*.strings' \
      --glob '!**/Tests/**' --glob '!**/.build/**'
    ```

    Build your **branding map** before you start: old name → new name, old bundle ID → new bundle ID, old support URL → new support URL. Apply it once. Don't leave half-renamed files.

    The boilerplate's design-system types use an `SAI` prefix (for example `SAIGlass`), which surfaces in the binary as `DesignSystem/SAI`. Rebrand the prefix with the bundled script — dry-run first, then apply after committing your work:

    ```bash theme={null}
    bash scripts/rebrand-design-system-prefix.sh SAI YourAppPrefix --dry-run
    bash scripts/rebrand-design-system-prefix.sh SAI YourAppPrefix --apply
    ```
  </Step>

  <Step title="Pick a hero archetype and lead with it, not the chat tab">
    The boilerplate ships a chat-first home. If your app is a parking helper, a meal planner, or a study tool, **chat is not your hero**. Reviewers see five other AI-chat apps a day; if your first screenshot is "AI chat with bubbles," you're invisible.

    Differentiation here is enforced by **mandatory archetype selection, not randomness**. `template.manifest.json` flags `differentiation.archetypeRequired`, and the repo ships hero recipes in `docs/recipes/hero/` to rebuild the home screen around a distinct primary experience:

    * `DashboardGrid.md` — metrics/cards home
    * `FeedTimeline.md` — scrolling feed
    * `MapCanvas.md` — map-centric UI
    * `GuidedTaskFlow.md` — step-by-step flow
    * `ConversationalHome.md` — chat-first (only if chat genuinely is your product)

    First screenshot: the screen that shows what your app actually does (parking spot map, meal of the day, flashcard review). Second screenshot: the differentiated outcome. Chat, if it appears at all, comes after.
  </Step>

  <Step title="Read the module removal notes before you delete anything">
    Removing a module without its couplings leaves dangling symbols in the binary, which reviewers' tooling can fingerprint. The biggest gotcha:

    <Warning>
      `LLMClient` and `LLMMessage` live in **FeatureChat**, and the **AI** package re-exports FeatureChat (`@_exported import FeatureChat` in `Packages/AI/Sources/AI/AI.swift`). You **cannot delete FeatureChat alone** without first moving `LLMClient` / `LLMMessage` into `AI` (or `Core`) and dropping the `FeatureChat` dependency from `Packages/AI/Package.swift`. Otherwise `Packages/AI` stops compiling.
    </Warning>

    If you remove **Payments**, you also need to remove paywall presentation hooks from **FeatureSettings** (which depends on Payments). The full per-module table, including which symbols to grep for and what to delete, is in `docs/checklists/APP_STORE_4_3_HARDENING.md`. Pair it with the buyer-facing prompts in `docs/prompts/AppStore4_3Hardening.prompts.md`.
  </Step>
</Steps>

## Pre-submit checklist

<AccordionGroup>
  <Accordion title="Binary fingerprint">
    * [ ] `bash scripts/appstore-43-audit.sh` reports **PASS** (no blocking app-owned hits)
    * [ ] `strings` on the Release `.ipa` returns no `swiftai`, `boilerplate`, `designsystem/sai`, or stub matches
    * [ ] Bundle ID is yours, not the boilerplate's `com.berkin.SwiftAIBoilerplatePro`
    * [ ] No demo or sample files are in the app target's Compile Sources
    * [ ] Removed modules have their couplings pruned (see module table)
  </Accordion>

  <Accordion title="Branding and copy">
    * [ ] Branding map applied: name, support email, URLs, paywall copy
    * [ ] Onboarding pages reflect your product, not generic AI-chat copy
    * [ ] Settings → About shows your company, your URLs, your version
    * [ ] Push notifications and email templates use your wording
  </Accordion>

  <Accordion title="App Store listing">
    * [ ] First screenshot leads with your hero, not the chat screen
    * [ ] App name and subtitle describe your product, not "AI chat"
    * [ ] Description's first line answers "what does this app do for me"
    * [ ] Privacy policy and terms hosted at your domain (not boilerplate's)
  </Accordion>

  <Accordion title="Review notes (App Store Connect → App Review Information)">
    * [ ] You explain in plain language what the app does and who it's for
    * [ ] You credit the architecture honestly if asked, while making clear the product, content, and listing are yours
    * [ ] Demo account credentials work and have realistic data
  </Accordion>
</AccordionGroup>

## Example LLM cleanup prompt

### Must-run starter fingerprint prompt

If the Release audit reports `SwiftAI`, `Boilerplate`, or `DesignSystem/SAI`, run this first. These are starter fingerprints and should not remain in app-owned Release output.

```markdown theme={null}
I am preparing an iOS app derived from SwiftAI Boilerplate Pro for App Store submission. The Release audit still reports these blocking app-owned fingerprints:

- SwiftAI
- Boilerplate
- DesignSystem/SAI

My app details:
- App name: [FILL IN]
- Bundle identifier: [FILL IN]
- Design-system prefix to use instead of SAI: [FILL IN, e.g. MYA]
- Primary app purpose: [FILL IN]

Tasks:
1. Search the production app target, linked local packages, app extension targets, generated configuration, launch storyboard, asset names, Info.plist values, xcodeproj settings, and package resources for exact matches of `SwiftAI`, `Boilerplate`, and `DesignSystem/SAI`.
2. Replace app-owned product identity strings with my app-specific name and bundle identifier. Do not rename upstream docs, changelog entries, or comments unless they are bundled into the app or compiled into Release.
3. Rename the design-system source prefix/path references that cause `DesignSystem/SAI` to appear in Release. Use the repo's rebrand script if available (positional args: old prefix, new prefix, mode):
   `bash scripts/rebrand-design-system-prefix.sh SAI [PREFIX] --apply`
4. Verify no dead demo/showcase Swift files or bundled markdown resources still compile into the app target.
5. Run:
   `bash scripts/appstore-43-audit.sh`
6. If the audit still fails, classify every remaining hit as:
   - intentional upstream template/docs
   - DEBUG/test-only
   - third-party SDK noise
   - still-blocking production/app-owned

Constraints:
- Keep useful boilerplate features unless I explicitly ask to remove them.
- Preserve DEBUG clone-and-run behavior.
- No force unwraps in new production code.
- Do not hide failures by weakening the audit script.
```

Paste this into Claude Code, Cursor, or your editor's AI chat after you've branched off `main`. It runs the heavy renaming pass and flags couplings before you submit.

```markdown theme={null}
You are auditing an iOS app for App Store Guideline 4.3 (Spam) and 4.2.6
(template apps) before submission. The app is built on SwiftAI Boilerplate
Pro; the architecture is shared with other apps, which is fine. The goal
is to remove undifferentiated product, listing, and binary fingerprints.

Do these passes in order. After each pass, print a short report and wait
for me to confirm before continuing.

Pass 1: Branding map.
- Search the repo (excluding Tests, .build, Pods, DerivedData) for any
  occurrence of: "SwiftAI", "Boilerplate", "SwiftAIBoilerplatePro",
  "swiftaiboilerplate.com", boilerplate support email, boilerplate
  bundle ID prefix.
- Output a table: file path, line, old token, suggested replacement
  using my product name "<MY_APP_NAME>" and bundle ID "<MY_BUNDLE_ID>".
- Do not edit yet. Wait for me to confirm.

Pass 2: User-visible strings.
- Once I confirm, apply the renames from Pass 1 only to user-visible
  strings: .strings files, Localizable, SwiftUI Text(...), accessibility
  labels, push payload templates, email templates.
- Leave Swift type names, package names, and folder names alone unless
  I tell you otherwise.
- Print a diff summary.

Pass 3: Dead app-target code.
- List every file in the **app target's** Compile Sources whose symbols
  aren't referenced from any view that appears in the running app's
  navigation graph. Include sample data, example views, and demo
  flows.
- Output the candidate removal list. Do not delete; I'll review.

Pass 4: Module coupling check.
- If FeatureChat is being removed, list every reference to its public
  types from outside the FeatureChat package, especially in the AI
  module's clients and CompositionRoot.
- Same for Payments → FeatureSettings paywall hooks.
- Output a "blocking removals" list with file:line references.

Pass 5: App Store listing review.
- Read the screenshots referenced in /AppStoreAssets (or wherever I
  point you) and the App Store description draft if I paste one.
- Tell me: does the first screenshot lead with the hero feature?
  Does the description's first sentence answer "what this app does
  for me"? Where does it still sound like a generic AI-chat
  template?

Constraints:
- Don't invent files or symbols. If you can't find something, say so.
- Don't claim the app will pass review. Your job is to reduce the
  patterns reviewers commonly cite under 4.3 / 4.2.6.
- Stop after each pass and print a short summary.
```

## If you already got a 4.3 rejection

Don't panic, and don't argue with the reviewer in the first reply.

<Steps>
  <Step title="Read the rejection literally">
    Apple's message usually quotes the guideline number and points at one or two specific things: a screenshot, a string, a flow, or a binary similarity. Treat that as the entire problem statement, not a hint at a wider issue.
  </Step>

  <Step title="Run the full pre-submit workflow again">
    Even if the rejection mentions only one thing, re-run `bash scripts/appstore-43-audit.sh` and walk every pre-submit step. Reviewers compare binaries; if one fingerprint matched, others probably did too.
  </Step>

  <Step title="Reply in App Review with what changed">
    In App Store Connect → Resolution Center, write a short reply: what you changed, why your app is differentiated, and a one-paragraph plain-language description of what users do with it. Resubmit a new build with a bumped build number.
  </Step>

  <Step title="If you disagree, request a call">
    If you've done the work and still believe the rejection is wrong, you can request a phone call through App Review. Show up with your branding map, screenshots, and a clear answer to "who is this for and what makes it different." Don't argue the guideline; argue the facts.
  </Step>
</Steps>

## What a boilerplate can't guarantee

Honest version: a boilerplate can save you weeks of plumbing. It can't tell Apple your app is differentiated, because that's a judgment call about your product, your listing, and your category. The patterns above are the ones reviewers cite most often. They don't cover product-market fit, content quality, or whether your category is genuinely too crowded.

If your idea is "a chat app with a different color scheme," no checklist will save you. If your idea is a real product that happens to use a chat interface, this checklist removes the noise so reviewers can see it.

## Related

<CardGroup>
  <Card title="Building Your App" icon="hammer" href="/pages/guides/building-your-app">
    Branding, backend, and feature customization
  </Card>

  <Card title="Deployment Guide" icon="rocket" href="/pages/guides/deployment">
    TestFlight and App Store submission steps
  </Card>

  <Card title="Customization Recipes" icon="palette" href="/pages/guides/customization">
    Colors, themes, onboarding, and modules
  </Card>

  <Card title="Apple Guideline 4.3" icon="apple" href="https://developer.apple.com/app-store/review/guidelines/#4.3">
    Read Apple's wording directly
  </Card>
</CardGroup>


# Authentication Guide
Source: https://docs.swiftaiboilerplate.com/pages/guides/authentication

Unified authentication with Apple, Google, and Email via Supabase

This boilerplate provides a complete authentication solution using Supabase Auth with support for:

* **Apple Sign In** - Native iOS authentication
* **Google Sign In** - OAuth via Google
* **Email/Password** - Traditional email authentication

All authentication methods are unified through Supabase, providing a consistent user experience and automatic session management.

<Note>
  You can skip this guide while exploring the app in mock mode. Complete it when you are ready to connect real Supabase authentication providers.
</Note>

## Features

### Unified Sign In Experience

* **Single Sign In Screen**: All authentication options on one screen
* **Social OAuth**: Apple and Google sign in via Supabase Auth
* **Email Authentication**: Sign up and sign in with email/password
* **Password Reset**: Forgot password flow via email

### Session Persistence

✅ **Users stay logged in for days, not hours** - Production-ready session management that just works

The app implements battle-tested session persistence:

1. **Keychain Storage**: Auth tokens are securely stored in iOS Keychain
2. **Automatic Session Loading**: When the app launches, sessions are restored from Keychain
3. **Expired Session Recovery**: Even if access token has expired, the app automatically refreshes using the refresh token
4. **Proactive Refresh**: Tokens are refreshed 60 seconds before expiry
5. **Retry Logic**: Failed refresh attempts retry up to 3 times with exponential backoff

### Session Behavior

| Scenario                  | Behavior                                       |
| ------------------------- | ---------------------------------------------- |
| App opened after 1 hour   | ✅ Silent refresh, user stays logged in         |
| App opened after 3 days   | ✅ Silent refresh, user stays logged in         |
| App opened after 14+ days | Refresh token expired, user must sign in again |

<Note>
  Refresh token lifetime is configurable in your Supabase dashboard. Default is 7+ days.
</Note>

### Session Lifecycle

```text theme={null}
App Launch
    ↓
Load Session from Keychain
    ↓
Access Token Valid? ──No──→ Attempt Refresh with Refresh Token
    ↓ Yes                         ↓
    ↓                    Refresh Successful? ──No──→ Show Sign In Screen
    ↓                             ↓ Yes
Navigate to Main Screen  ←────────┘
    ↓
Schedule Proactive Refresh (60s before expiry)
    ↓
Silent background refresh
    ↓
Continue using app seamlessly
```

## Setup

### 1. Configure Supabase

#### Enable Social Providers

1. Go to [Supabase Dashboard](https://app.supabase.com)
2. Select your project
3. Navigate to **Authentication** → **Providers**

### Apple Sign In Setup (Step-by-Step)

<Steps>
  <Step title="Step 1: Go to Supabase Authentication">
    In your Supabase dashboard, navigate to **Authentication** settings. This is where you'll enable Apple as a sign-in provider.
  </Step>

  <Step title="Step 2: Enable Apple Sign In Provider">
    Go to **Sign In Providers** and find Apple in the list. Click on it to configure.
  </Step>

  <Step title="Step 2.1: Enable Apple Sign In">
    Toggle **Enable Sign in with Apple** to ON. This activates Apple as an authentication provider in your Supabase project.
  </Step>

  <Step title="Step 3: Configure Apple Developer Identifiers">
    In [Apple Developer Portal](https://developer.apple.com), go to **Certificates, Identifiers & Profiles**:

    1. Select **Identifiers** → Your App ID
    2. Ensure **Sign in with Apple** capability is checked
    3. Click **Save**
  </Step>

  <Step title="Step 4: Complete Apple Developer Portal Setup">
    Complete the Apple Developer Portal configuration:

    * **Services ID**: Create one if needed for web callback
    * **Team ID**: Your Apple Developer Team ID
    * **Key ID**: Generate a new key with Sign in with Apple enabled
    * **Private Key**: Download and save securely

    Add these to your Supabase Apple provider settings.
  </Step>

  <Step title="Step 5: Add Xcode Capability">
    In Xcode, go to your target's **Signing & Capabilities**:

    1. Click **+ Capability**
    2. Search for "Sign in with Apple"
    3. Add it to your target

    This enables the native Apple Sign In button in your app.
  </Step>
</Steps>

<Note>
  Apple requires apps that offer third-party login (like Google) to also support Sign in with Apple. The boilerplate has this pre-built with Supabase integration.
</Note>

### Google Sign In Setup

Google Sign In uses two pieces of configuration:

* A **Web OAuth client** for Supabase, because Supabase owns the OAuth callback URL
* An **iOS OAuth client** for the native Google Sign-In SDK, because the app runs on iPhone and is identified by your Bundle ID

<Warning>
  If Google asks for a Bundle ID, use your app's iOS bundle identifier. The boilerplate derives every target's bundle ID from a single `APP_BUNDLE_ID` in `Config/App.xcconfig` (each target sets `PRODUCT_BUNDLE_IDENTIFIER = $(APP_BUNDLE_ID)`), so set `APP_BUNDLE_ID` there or read the resolved value from Xcode target settings. If Google asks for an App Store ID, you can usually leave it blank while developing locally. Add it later after you create the app record in App Store Connect.
</Warning>

<Steps>
  <Step title="Find your Supabase callback URL">
    In your Supabase project, copy your project reference from the project URL, then build this callback URL:

    ```text theme={null}
    https://YOUR_PROJECT_REF.supabase.co/auth/v1/callback
    ```

    Keep this URL open. You will paste it into Google Cloud in the next step.
  </Step>

  <Step title="Create the Web OAuth client in Google Cloud">
    Open [Google Cloud Console](https://console.cloud.google.com), select or create a project, then go to **APIs & Services** -> **Credentials**.

    1. Click **Create Credentials** -> **OAuth client ID**
    2. Choose **Web application**
    3. Name it something like `SwiftAI Supabase Web`
    4. Add the Supabase callback URL under **Authorized redirect URIs**
    5. Save the client

    Copy the generated **Client ID** and **Client Secret**. These values go into Supabase.
  </Step>

  <Step title="Enable Google in Supabase">
    In Supabase, go to **Authentication** -> **Sign In / Providers** -> **Google**.

    1. Toggle **Enable Sign in with Google** on
    2. Paste the **Web OAuth Client ID** from Google Cloud
    3. Paste the **Web OAuth Client Secret** from Google Cloud
    4. Save the provider
  </Step>

  <Step title="Create the iOS OAuth client in Google Cloud">
    Back in Google Cloud **Credentials**, create a second OAuth client:

    1. Click **Create Credentials** -> **OAuth client ID**
    2. Choose **iOS**
    3. Enter your **Bundle ID** exactly as it resolves from `APP_BUNDLE_ID` in `Config/App.xcconfig`, for example `com.yourcompany.yourapp`
    4. Leave **App Store ID** blank for local development if you do not have an App Store Connect app yet
    5. Save the client

    Copy the generated **iOS Client ID**. This value goes into your app's `Config/Secrets.xcconfig` as `GOOGLE_CLIENT_ID`.
  </Step>
</Steps>

### 2. Configure iOS App

**Update Secrets Configuration:**

```bash theme={null}
# Config/Secrets.xcconfig
SUPABASE_URL = https://YOUR_PROJECT_REF.supabase.co
SUPABASE_ANON_KEY = YOUR_PUBLIC_ANON_KEY

# For Google Sign In (optional)
GOOGLE_CLIENT_ID = YOUR_IOS_CLIENT_ID
```

<Warning>
  After editing `Config/Secrets.xcconfig`, run `bash scripts/update-config.sh` and rebuild the app. The generated Swift configuration is not updated automatically.
</Warning>

**Add Google Sign In SDK (Optional):**

Google Sign In is optional. `GoogleSignInCoordinator` is guarded by `#if canImport(GoogleSignIn)`, so the app builds and runs without the SDK — Google sign-in is simply unavailable until you add it.

To enable it, add the GoogleSignIn-iOS package to the Xcode project via **File → Add Package Dependencies**:

```text theme={null}
https://github.com/google/GoogleSignIn-iOS
```

Then add the `GoogleSignIn` product to the app target.

### Google Credential Reference

| Field                 | Where to Get It                                                     | Where to Put It                                                    |
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Supabase callback URL | Supabase project ref                                                | Google Cloud Web OAuth client -> Authorized redirect URIs          |
| Web Client ID         | Google Cloud Web OAuth client                                       | Supabase Google provider                                           |
| Web Client Secret     | Google Cloud Web OAuth client                                       | Supabase Google provider                                           |
| iOS Client ID         | Google Cloud iOS OAuth client                                       | `Config/Secrets.xcconfig` as `GOOGLE_CLIENT_ID`                    |
| Bundle ID             | `APP_BUNDLE_ID` in `Config/App.xcconfig` (or Xcode target settings) | Google Cloud iOS OAuth client                                      |
| App Store ID          | App Store Connect app record                                        | Optional for local development; add before production if available |

### 3. Setup CompositionRoot

The boilerplate comes with auth pre-configured, but here's how it works:

```swift theme={null}
// CompositionRoot.swift

// Create auth client with social providers
let authClient = SessionManager(
    httpClient: httpClient,
    keychain: keychain,
    apple: AppleSignInCoordinator(),
    google: GoogleSignInCoordinator(clientID: googleClientID), // Optional
    config: authConfig
)
```

## Usage

### Sign In Flow

The `SignInView` provides a premium, minimal authentication experience:

```swift theme={null}
SignInView(authClient: authClient)
```

**Design Philosophy:**

* Clean, Apple-like aesthetic with generous whitespace
* Native Apple button (HIG compliant) as primary CTA
* Visual hierarchy: Apple → Google → "Use email instead" link
* Premium feel with continuous corner radii and subtle borders
* Adapts to light/dark mode automatically

**Features:**

* **Apple Sign In**: Native button (HIG compliant) - primary option
* **Google Sign In**: Secondary button with subtle border
* **Email Sign In**: Shown via "Use email instead" link (opens sheet)
* **Create Account**: Accessible from email login sheet
* **Forgot Password**: Accessible from email login sheet

**Theme Integration:**
All auth screens (Sign In, Sign Up, Forgot Password) adapt to the active theme:

* Links and accents use `DSColors.accentPrimary` (warm pink in Aurora, neutral in others)
* Text colors use `DSColors.textPrimary` and `DSColors.textSecondary`
* Backgrounds and surfaces adapt to theme palette
* Icons inherit theme accent color
* No hardcoded system blue - everything theme-aware

**Customization:**
To adjust the visual design, edit `SwiftAIBoilerplatePro/AppShell/SignInView.swift`:

**Spacing & Rhythm:**

* Top space: `Spacer().frame(height: 100)` - Adjust for vertical positioning
* Between hero and buttons: `64pt` - Control breathing room
* Bottom space: `80pt` then `48pt` - Legal section padding

**Typography:**

* App title: `28pt semibold rounded` - Adjust size/weight
* Tagline: `15pt regular, 0.3 tracking, 70% opacity` - Refine elegance
* Legal text: `12pt, 55% opacity` - Keep whisper-quiet

**Colors & Effects:**

* Avatar blur: `blur(radius: 20)` on gradient circle
* Background: Subtle top-to-bottom gradient
* Google button: `surface.opacity(0.6)` with `0.5pt border`
* Link colors: Uses `accentPrimary.opacity(0.7)` for cohesion

**Animations:**

* Hero fade-in: `.easeOut(duration: 0.6)` on appear
* Buttons slide: `.delay(0.15)` for staggered entrance
* Error message: `.spring(response: 0.35)` for smooth entry

**Container Width:**

* Max width: `380pt` for button container (narrower = more refined)

### Check Authentication State

```swift theme={null}
// Check current user
let user = await authClient.currentUser()

if let user = user {
    print("Signed in as: \(user.email ?? "unknown")")
} else {
    print("Not signed in")
}

// Observe auth state changes
for await state in authClient.authStates() {
    switch state {
    case .authenticated(let user):
        print("User signed in: \(user.id)")
    case .unauthenticated:
        print("User signed out")
    case .refreshing:
        // Show loading UI while recovering expired session
        print("Refreshing session...")
    }
}
```

### Sign Out

```swift theme={null}
try await authClient.signOut()
```

This will:

1. Revoke the access token on the server
2. Clear tokens from Keychain
3. Clear in-memory session
4. Navigate to sign-in screen

## How It Works

### Apple Sign In Flow

1. User taps "Continue with Apple"
2. System shows Apple Sign In sheet
3. User authenticates with Face ID/Touch ID
4. App receives Apple ID token + nonce
5. Token is exchanged with Supabase for session
6. Session stored in Keychain
7. User navigated to main screen

```swift theme={null}
// Internal flow
let (idToken, nonce) = try await apple.requestIDToken(...)
let session = try await api.exchangeAppleIDToken(idToken: idToken, nonce: nonce)
try await persistSession(session)
```

### Google Sign In Flow

1. User taps "Continue with Google"
2. Google Sign In SDK presents OAuth flow
3. User selects Google account
4. App receives Google ID token
5. Token is exchanged with Supabase for session
6. Session stored in Keychain
7. User navigated to main screen

```swift theme={null}
// Internal flow
let idToken = try await google.requestIDToken()
let session = try await api.exchangeGoogleIDToken(idToken: idToken)
try await persistSession(session)
```

### Email Sign In Flow

1. User enters email and password
2. Credentials sent to Supabase
3. Supabase validates and returns session
4. Session stored in Keychain
5. User navigated to main screen

```swift theme={null}
// Internal flow
let session = try await api.signInWithEmail(email: email, password: password)
try await persistSession(session)
```

## Session Persistence Details

### How Sessions Are Stored

Sessions are stored in iOS Keychain with the following keys:

```text theme={null}
auth_access_token   - JWT access token
auth_refresh_token  - Long-lived refresh token
auth_expires_at     - Token expiration timestamp
auth_user_json      - User profile data
```

Security:

* Uses `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
* Data is encrypted by iOS
* Survives app updates
* Deleted on app uninstall

### Automatic Session Loading

On app launch (`loadInitialSession()`):

1. **Load from Keychain**: Attempts to load stored session
2. **Validate Expiry**: Checks if access token is expired
3. **Attempt Refresh**: If expired, tries to refresh using the refresh token (up to 3 attempts)
4. **Recover or Clear**: Restores session if refresh succeeds, clears if refresh token is also expired
5. **Emit State**: Notifies observers of auth state (`.refreshing` during recovery)

```swift theme={null}
// SessionManager+Persistence.swift
func loadInitialSession() async {
    do {
        if let session = try loadSession() {
            if Date.now > session.expiresAt {
                // Access token expired - try the refresh token before
                // signing the user out (it usually outlives the access token)
                await attemptSessionRefresh(with: session)
                return
            }

            // Session valid, restore it
            currentSession = session
            emit(.authenticated(session.user))

            // Schedule proactive refresh (or refresh now if due soon)
            if session.needsRefresh {
                Task { try? await refreshIfNeeded() }
            } else {
                scheduleRefresh(for: session)
            }
        }
    } catch {
        try? clearSession()
    }
}
```

<Tip>
  The `.refreshing` state allows you to show a loading indicator while the session is being recovered, providing a smooth user experience.
</Tip>

### Token Refresh Strategy

The app uses **proactive refresh** and **reactive recovery** to ensure users stay logged in:

**Proactive Refresh (Before Expiry):**

1. **Schedule Refresh**: 60 seconds before token expiry
2. **Silent Background Execution**: User never sees a loading state
3. **Token Rotation**: Handles Supabase refresh token rotation

**Reactive Recovery (After Expiry):**

1. **Detect Expired Session**: On app launch, check if access token expired
2. **Attempt Refresh**: Use refresh token to get new access token
3. **Retry Logic**: Up to 3 attempts with exponential backoff
4. **Emit `.refreshing` State**: Show loading UI if needed

```swift theme={null}
// Proactive: Scheduled 60 seconds before expiry
let refreshTime = session.expiresAt.addingTimeInterval(-60)
let delay = max(0, refreshTime.timeIntervalSinceNow)
refreshTask = Task {
    try await sleeper.sleep(for: delay)
    if !Task.isCancelled {
        try await refreshIfNeeded()
    }
}

// Reactive: Recover an expired session on app launch
func attemptSessionRefresh(with expiredSession: AuthSession) async {
    currentSession = expiredSession
    emit(.refreshing)

    for attempt in 1...3 {
        do {
            let newSession = try await api.refresh(refreshToken: expiredSession.refreshToken)
            try await persistSession(newSession)
            currentSession = newSession
            emit(.authenticated(newSession.user))
            scheduleRefresh(for: newSession)
            return
        } catch {
            if attempt < 3 {
                try? await sleepBeforeRetry(attempt: attempt)
            }
        }
    }

    // Refresh token also invalid - clear and require sign-in
    try? clearSession()
    currentSession = nil
    emit(.unauthenticated)
}
```

<Info>
  **Result**: Users stay logged in for days (until refresh token expires), not just 1 hour (access token lifetime).
</Info>

## Navigation Based on Auth State

The `LaunchRouter` automatically handles navigation:

```swift theme={null}
// LaunchRouter observes auth state
for await state in authClient.authStates() {
    switch state {
    case .authenticated:
        destination = .main  // Show main app
    case .unauthenticated:
        destination = .signIn  // Show sign in
    case .refreshing:
        // Keep current screen, just refreshing token
    }
}
```

This means:

* ✅ Users automatically navigate to main screen when signed in
* ✅ Users automatically navigate to sign in when signed out
* ✅ No manual navigation needed
* ✅ Works for all auth methods (Apple, Google, Email)

## Best Practices

### Always Check Auth State

```swift theme={null}
// Don't store user state yourself
// ❌ Bad
@State private var isSignedIn = false

// ✅ Good - observe auth state
for await state in authClient.authStates() {
    // React to state changes
}
```

### Handle Sign Out Gracefully

```swift theme={null}
func signOut() {
    Task {
        do {
            try await authClient.signOut()
            // Navigation handled automatically by LaunchRouter
        } catch {
            // Show error to user
            errorMessage = "Failed to sign out: \(error.localizedDescription)"
        }
    }
}
```

### Use Session Tokens for API Calls

When the `HTTPClient` is built with an `AuthInterceptor`, the current access token is attached to every request automatically — call sites never touch the token:

```swift theme={null}
// AuthInterceptor adds `Authorization: Bearer <access_token>` if the
// header isn't already set, sourcing the token from a TokenProvider.
let request = HTTPRequest(path: "/rest/v1/profiles", method: .get)
let response = try await httpClient.send(request)
let profile = try JSONDecoder().decode(UserProfile.self, from: response.data)
```

## Troubleshooting

### Users Have to Sign In Every Time

This should be rare with the new session recovery. Check:

1. Keychain is accessible (not disabled in Xcode capabilities)
2. `loadInitialSession()` is being called
3. No errors in `SessionManager` initialization
4. Check logs for refresh attempts and failures
5. Verify refresh token hasn't expired (7+ days of inactivity)

<Note>
  With proper session recovery, users only need to sign in again if their refresh token expires (typically 7+ days of not opening the app).
</Note>

### Google Sign In Not Working

1. Verify `GOOGLE_CLIENT_ID` is set to the **iOS OAuth Client ID**, not the Web Client ID.
2. Verify the Supabase Google provider uses the **Web OAuth Client ID** and **Web OAuth Client Secret**.
3. Ensure the Google Cloud Web OAuth client has this exact authorized redirect URI: `https://YOUR_PROJECT_REF.supabase.co/auth/v1/callback`.
4. Ensure the Google Cloud iOS OAuth client Bundle ID exactly matches the bundle ID resolved from `APP_BUNDLE_ID` in `Config/App.xcconfig`.
5. If you changed `Secrets.xcconfig`, run `bash scripts/update-config.sh`, clean, and rebuild.
6. Verify GoogleSignIn SDK is installed.
7. For local development, do not block on App Store ID. Add it later after creating the app in App Store Connect.

### Apple Sign In Fails

1. **Supabase Configuration**: Verify Apple provider is enabled in Supabase Authentication → Providers
2. **Apple Developer Portal**: Check that Sign in with Apple capability is enabled on your App ID
3. **Xcode Capability**: Ensure "Sign in with Apple" capability is added in Signing & Capabilities
4. **Credentials**: Verify Team ID, Key ID, and Private Key are correct in Supabase
5. **Bundle ID**: Check bundle ID matches between Xcode, App Store Connect, and Supabase

### Token Refresh Fails

Check logs for:

* Network connectivity issues
* Supabase service status
* Invalid refresh token (forces re-authentication)
* Too many concurrent refresh attempts

## Security Considerations

1. **Tokens in Keychain**: Never store tokens in UserDefaults or files
2. **HTTPS Only**: All auth requests use HTTPS
3. **Token Expiry**: Access tokens expire (default: 1 hour), but sessions persist via refresh tokens
4. **Refresh Token Lifetime**: Configurable in Supabase dashboard (default: 7+ days)
5. **Refresh Rotation**: Supabase rotates refresh tokens for security
6. **Server-Side Validation**: Always validate tokens server-side
7. **Detailed Logging**: Auth events are logged for debugging (tokens are never logged)

## Next Steps

<CardGroup>
  <Card title="Supabase Auth Docs" icon="database" href="https://supabase.com/docs/guides/auth">
    Official Supabase authentication documentation
  </Card>

  <Card title="Apple Sign In Guide" icon="apple" href="https://developer.apple.com/sign-in-with-apple/">
    Apple's official Sign in with Apple documentation
  </Card>

  <Card title="Google Sign In Setup" icon="google" href="https://developers.google.com/identity">
    Google Identity Platform documentation
  </Card>

  <Card title="Auth Module" icon="lock" href="/pages/modules/auth">
    Technical documentation for the Auth package
  </Card>
</CardGroup>


# Building Your App
Source: https://docs.swiftaiboilerplate.com/pages/guides/building-your-app

Complete step-by-step customization guide from boilerplate to App Store

<Info>
  **Complete guide:** This page is the web version. For the deeper prompt library, see `docs/BUILDING_YOUR_APP.md` in your project.
</Info>

<Warning>
  **Before you submit:** Run the [App Store 4.3 hardening checklist](/pages/guides/app-store-4-3-hardening). Branded boilerplates get flagged when the binary, listing, and screenshots still look like the template. Five passes, one prompt, \~1 hour.
</Warning>

## What This Guide Covers

This is your **complete roadmap** from boilerplate to App Store:

<CardGroup>
  <Card title="Branding" icon="palette">
    Name, icon, colors, onboarding
  </Card>

  <Card title="Backend" icon="server">
    Supabase, RevenueCat, API keys
  </Card>

  <Card title="Features" icon="puzzle-piece">
    Customize chat, home, profile, settings
  </Card>

  <Card title="Legal" icon="gavel">
    Privacy, terms, compliance
  </Card>

  <Card title="Testing" icon="flask">
    Run tests, fix bugs
  </Card>

  <Card title="Launch" icon="rocket">
    App Store submission
  </Card>
</CardGroup>

## Two Ways to Use This Guide

<Tabs>
  <Tab title="Manual (Traditional)">
    **Step-by-step instructions** with exact file paths:

    * What to change
    * Where to find it
    * How to verify it works
    * What to test

    **Time:** Detailed, thorough approach
  </Tab>

  <Tab title="AI-Assisted (Fast)">
    **Ready-to-use LLM prompts** for Cursor/Claude:

    * Copy prompt
    * Paste in AI assistant
    * AI makes the changes
    * You review and test

    **Time:** 3-5x faster
  </Tab>
</Tabs>

<Note>
  Prefer a guided, automated path? The **App Generator** is a separate, standalone macOS product (coming soon) that drives your own coding-agent CLI to scaffold a differentiated, App Store Guideline 4.3-safe app from this template. It is not bundled in the boilerplate. See [license & pricing](/pages/reference/license) for details.
</Note>

## Quick Examples

### Change App Name

**Manual:**

1. Set the user-facing name in `BrandConfig.appDisplayName` (`Packages/DesignSystem/Sources/DesignSystem/Tokens/BrandConfig.swift`)
2. Set the app identity in `APP_BUNDLE_ID` in `Config/App.xcconfig` — every target's bundle ID and app-group entitlements derive from this single value

**AI Prompt:**

```text theme={null}
Change appDisplayName to "MyAwesomeApp" and APP_BUNDLE_ID to
"com.mycompany.myawesomeapp". Update all user-facing text.
```

### Customize Colors

**Manual:**

1. Open `SwiftAIBoilerplatePro/Resources/DesignSystemColors.xcassets` and edit `Primary.colorset`
2. Edit the accent color in `SwiftAIBoilerplatePro/Assets.xcassets/AccentColor.colorset`
3. Test in light/dark mode

**AI Prompt:**

```text theme={null}
Change primary color to #6C5CE7 (purple) and accent to #00D4AA (teal).
Update Primary.colorset in SwiftAIBoilerplatePro/Resources/DesignSystemColors.xcassets
and AccentColor.colorset in SwiftAIBoilerplatePro/Assets.xcassets, both for light and dark.
```

## Complete Guide Contents

### Initial Setup

* Clone and run
* Change branding
* Customize onboarding

### Backend

* Supabase deployment
* RevenueCat setup
* API configuration

### Feature Customization

* Home screen
* Chat experience
* Profile
* Settings
* Add new features

### Legal & Compliance

* Privacy policy
* Terms of service
* App Store requirements

### Testing & Launch

* Run test suite
* TestFlight beta
* App Store submission
* Production checklist

### LLM Prompts Library

**Ready-to-use prompts** throughout the guide for:

* Branding changes
* UI customization
* Feature additions
* Backend setup
* Troubleshooting

## Quick Start Path

<Steps>
  <Step title="Phase 1: Setup">
    Clone → Run → Understand architecture
  </Step>

  <Step title="Phase 2: Branding">
    Name → Icon → Colors → Onboarding
  </Step>

  <Step title="Phase 3: Backend">
    Supabase → RevenueCat → Test real auth
  </Step>

  <Step title="Phase 4: Customize">
    Home → Chat → Your unique features
  </Step>

  <Step title="Phase 5: Legal">
    Update policies → Add required disclosures
  </Step>

  <Step title="Phase 6: Launch">
    Test → App Store assets → [4.3 hardening](/pages/guides/app-store-4-3-hardening) → Submit
  </Step>
</Steps>

## View Complete Guide

<Card title="View Complete Building Guide" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/BUILDING_YOUR_APP.md">
  Comprehensive guide with manual steps AND LLM prompts
</Card>

## Related Resources

<CardGroup>
  <Card title="Supabase Setup" icon="server" href="/pages/guides/supabase-setup">
    Backend deployment
  </Card>

  <Card title="RevenueCat Setup" icon="dollar" href="/pages/guides/revenuecat-setup">
    Subscription configuration
  </Card>

  <Card title="docs/CLAUDE.md" icon="robot" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/CLAUDE.md">
    AI coding guidelines for assistants working in your project
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    System design
  </Card>
</CardGroup>

## Common Tasks

<AccordionGroup>
  <Accordion title="Change App Branding">
    * App name and bundle ID
    * App icon
    * Primary and accent colors
    * Onboarding content
  </Accordion>

  <Accordion title="Add New Feature">
    * Create SwiftData model
    * Create repository
    * Create ViewModel
    * Create View
    * Wire up in CompositionRoot
  </Accordion>

  <Accordion title="Customize Home Screen">
    * Edit hero section
    * Change feature cards
    * Modify quick actions
  </Accordion>

  <Accordion title="Deploy to Production">
    * Update legal docs
    * Prepare App Store assets
    * Run full test suite
    * Archive and submit
  </Accordion>
</AccordionGroup>

## Success Tips

<Tip>
  **For Manual Development:**

  * Follow file paths exactly
  * Test after each change
  * Commit to git frequently
  * Use ⌘⇧F to search code
</Tip>

<Tip>
  **For AI-Assisted Development:**

  * Always reference relevant docs in prompts
  * Review AI changes before running
  * Ask AI to verify changes compile
  * One feature at a time
</Tip>

## Need Help?

The [full guide](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/BUILDING_YOUR_APP.md) adds a troubleshooting section, common pitfalls, per-phase verification steps, and pro tips. For the test workflow, see the [Testing guide](/pages/guides/testing) — one `Boilerplate.xctestplan` run covers \~598 tests across 12 package test targets plus the app test suites.


# Chat Sync Setup
Source: https://docs.swiftaiboilerplate.com/pages/guides/chat-sync

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>
  <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>
  <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


# Crashlytics Setup
Source: https://docs.swiftaiboilerplate.com/pages/guides/crashlytics-setup

Add Firebase Crashlytics to track crashes and errors in production.

<Info>
  **Complete setup guide:** See `/docs/integrations/Crashlytics.md` in the project
</Info>

## What is Crashlytics?

<CardGroup>
  <Card title="Crash Reports" icon="bug">
    Automatic crash detection with stack traces
  </Card>

  <Card title="Error Tracking" icon="triangle-exclamation">
    Non-fatal errors and custom logging
  </Card>

  <Card title="User Privacy" icon="shield">
    GDPR compliant with user consent toggle
  </Card>

  <Card title="Free Tier" icon="dollar">
    Unlimited reports on Firebase free tier
  </Card>
</CardGroup>

<Warning>
  Users rarely report crashes. Without crash reporting, you are flying blind. Crashlytics captures every crash with full context so you can fix issues before they tank your App Store ratings.
</Warning>

## Step-by-Step Setup

<Steps>
  <Step title="Step 1: Go to Firebase Console">
    Navigate to the [Firebase Console](https://console.firebase.google.com) and create a new project or select an existing one.
  </Step>

  <Step title="Step 2: Name Your Project">
    Give your Firebase project a name. This will be your crash reporting dashboard for monitoring your iOS app.
  </Step>

  <Step title="Step 3: Disable Analytics (Optional)">
    For now, you can disable Google Analytics. You can always enable it later if needed. Crashlytics works independently.
  </Step>

  <Step title="Step 4: Add iOS App">
    Click **Add app** and select the iOS platform. This will start the iOS app registration process.
  </Step>

  <Step title="Step 5: Register Your App">
    Enter your iOS bundle identifier. Make sure it matches exactly with your Xcode project bundle ID.
  </Step>

  <Step title="Step 6: Download GoogleService-Info.plist">
    Download the `GoogleService-Info.plist` file. Add it to your Xcode project root and make sure it's added to your target.

    * ✅ Check "Copy items if needed"
    * ✅ Select your app target
  </Step>

  <Step title="Step 7: Add Firebase SDK">
    Add the Firebase SDK to your project. We recommend using Swift Package Manager (SPM) for easier dependency management.
  </Step>

  <Step title="Step 8: Add via Swift Package Manager">
    In Xcode, go to **File → Add Packages**. Enter the Firebase iOS SDK URL:

    ```text theme={null}
    https://github.com/firebase/firebase-ios-sdk
    ```

    Select the **FirebaseCrashlytics** package.
  </Step>

  <Step title="Step 9: Add Initialization Code">
    Add Firebase initialization code to your `App.swift` or `AppDelegate`:

    ```swift theme={null}
    import Firebase

    // In your App init or AppDelegate
    FirebaseApp.configure()
    ```
  </Step>

  <Step title="Step 10: Add Linker Flags">
    In Build Settings, add `-ObjC` to **Other Linker Flags**. This is required for Firebase to work correctly with Swift.
  </Step>

  <Step title="Step 11: Add Run Script Phase">
    Add a new Run Script phase in **Build Phases**:

    1. Click **+** → **New Run Script Phase**
    2. Name it "Upload dSYMs to Crashlytics"
    3. Add the upload script (see Firebase docs)
  </Step>

  <Step title="Step 12: Configure Input Files">
    Add the required input files to the run script phase:

    ```text theme={null}
    ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}
    $(SRCROOT)/$(BUILT_PRODUCTS_DIR)/$(INFOPLIST_PATH)
    ```
  </Step>

  <Step title="Step 13: Complete Run Script Setup">
    Verify your run script phase is configured correctly with both the script and input files. This ensures crash reports are properly symbolicated.
  </Step>

  <Step title="Step 14: Set Debug Information Format">
    In **Build Settings**, set **Debug Information Format** to `DWARF with dSYM File` for Release builds. This generates the debug symbols needed for crash reports.
  </Step>

  <Step title="Step 15: Add Test Crash Code">
    Add a test crash button to verify Crashlytics is working:

    ```swift theme={null}
    #if DEBUG
    Button("Test Crash") {
        fatalError("Test crash for Firebase")
    }
    #endif
    ```
  </Step>

  <Step title="Step 16: Test on Real Device">
    Run your app on a **real device** (not simulator) and trigger the test crash. Relaunch the app to send the crash report to Firebase.

    <Warning>
      Crashlytics does not work reliably in the simulator. Always test on a real device.
    </Warning>
  </Step>

  <Step title="Step 17: Verify in Dashboard">
    Check your Firebase Crashlytics dashboard. You should see the test crash appear (may take a few minutes).

    <Note>
      Remember to **remove the test crash code** before submitting to the App Store!
    </Note>
  </Step>
</Steps>

## How It Works

### Automatic Integration

The boilerplate includes a **CrashReporter protocol** that automatically switches between Firebase Crashlytics and NoOp based on availability:

```swift theme={null}
// From CompositionRoot.swift (automatic)
// checkCrashlyticsAvailable() returns true when GoogleService-Info.plist is bundled
if FeatureFlags.crashlyticsEnabled && Self.checkCrashlyticsAvailable() {
    self.crashReporter = CrashlyticsCrashReporter()  // Real tracking
} else {
    self.crashReporter = NoOpCrashReporter()         // No tracking
}
```

`crashlyticsEnabled` is off in DEBUG and reads the `CRASHLYTICS_ENABLED` environment variable in Release (`FeatureFlags.swift`). Add the plist and flip the flag — no other code changes needed.

### User Privacy

Users control crash reporting in **Settings → Share Diagnostics**:

* ✅ ON → Crashes sent to Firebase
* ❌ OFF → No data sent

**GDPR Compliant:**

* Never sends email addresses
* User has opt-out control
* Clear privacy disclosure

## What Gets Tracked

### Automatically

* Crash reports with stack traces
* Device info (model, iOS version)
* App version
* User ID (anonymized, no email)
* Session info

### Custom (Optional)

* Non-fatal errors
* Custom logs/breadcrumbs
* User attributes (subscription tier, theme, etc.)

## Viewing Reports

**Firebase Console:**

1. Go to Firebase Console
2. Select your project
3. Crashlytics (in sidebar)
4. View crashes, errors, logs

**Reports include:**

* Stack traces
* Device information
* User ID
* App version
* Custom logs

## Cost

**Firebase Free Tier:**

* ✅ Unlimited crash reports
* ✅ 30-day retention
* ✅ Basic analytics
* ✅ Enough for most apps

**Blaze Plan (optional):**

* Extended retention
* More features
* Pay as you go (very low cost)

## Troubleshooting

<AccordionGroup>
  <Accordion title="Crashes not appearing in dashboard">
    * Make sure you tested on a **real device**, not simulator
    * Relaunch the app after the crash to send the report
    * Wait a few minutes for the report to appear
    * Check that `GoogleService-Info.plist` is in your target
  </Accordion>

  <Accordion title="Symbolication not working">
    * Verify dSYM upload script is running
    * Check that Debug Information Format is set to `DWARF with dSYM File`
    * Ensure input files are configured correctly
  </Accordion>

  <Accordion title="Build errors after adding Firebase">
    * Make sure `-ObjC` is in Other Linker Flags
    * Clean build folder (⌘⇧K) and rebuild
    * Check that you only added FirebaseCrashlytics package
  </Accordion>
</AccordionGroup>

## Related Guides

<CardGroup>
  <Card title="Full Integration Guide" icon="book">
    See complete details in `/docs/integrations/Crashlytics.md`
  </Card>

  <Card title="Feature Flags" icon="flag">
    Configure in `Composition/FeatureFlags.swift`
  </Card>

  <Card title="Settings Module" icon="gear" href="/pages/modules/feature-settings">
    User consent toggle
  </Card>

  <Card title="Privacy Policy" icon="shield">
    Update `Resources/privacy.md` to mention crash reporting
  </Card>
</CardGroup>

## Need Help?

The boilerplate handles all the integration automatically. You just need to:

1. Add `GoogleService-Info.plist`
2. Enable feature flag
3. Build and run

If you have issues, check the troubleshooting section above or in `/docs/integrations/Crashlytics.md`.


# Customization Recipes
Source: https://docs.swiftaiboilerplate.com/pages/guides/customization

Common customization patterns and examples

<Note>
  For complete customization guide with LLM prompts, see [Building Your App](/pages/guides/building-your-app)
</Note>

<Warning>
  **Shipping a white-labeled version?** Customizing colors and onboarding isn't enough on its own. Before you submit, run the [App Store 4.3 hardening checklist](/pages/guides/app-store-4-3-hardening) to clear binary fingerprints, branding leftovers, and listing copy that still reads like a template.
</Warning>

## Branding

### Change App Colors

**What to customize:** The design tokens read their colors from the DesignSystem package's own asset catalog via `Bundle.module`:

```text theme={null}
Packages/DesignSystem/Sources/DesignSystem/Resources/Assets.xcassets/
├── AccentPrimary.colorset      # DSColors.accentPrimary / .primary
├── AccentSecondary.colorset
├── Background.colorset
├── Surface.colorset
├── SurfaceElevated.colorset
├── TextPrimary.colorset
├── TextSecondary.colorset
├── ChipBackground.colorset
├── Danger.colorset / Success.colorset / Warning.colorset
└── ...
```

**Steps:**

1. Open the color set in Xcode
2. Change Light Appearance color
3. Change Dark Appearance color
4. Build → colors update everywhere

**All components use design tokens** - change once, applies everywhere. Note: the `system`/`light`/`dark` themes read these assets, while the `aurora` and `obsidian` themes use hard-coded values in `DSColors.swift`, so customizing those requires editing the matching `switch activeTheme` branches.

### Replace App Icon

**Steps:**

1. Create 1024×1024 PNG
2. Drag to `SwiftAIBoilerplatePro/Assets.xcassets/AppIcon.appiconset`
3. Xcode generates all required sizes
4. Build and verify

### Customize Onboarding

**File:** `SwiftAIBoilerplatePro/AppShell/OnboardingPage.swift`

**Change the `defaultPages` array:**

```swift theme={null}
static let defaultPages: [OnboardingPage] = [
    OnboardingPage(
        title: "Your Title",
        description: "Your description",
        systemImage: "sparkles",  // Any SF Symbol
        accentColor: "blue"        // Hex or system color name
    ),
    // Add more pages...
]
```

## UI Customization

### Add Home Screen Feature Card

**File:** `SwiftAIBoilerplatePro/AppShell/HomeContent.swift`

Add to `HomeContent.FeatureItem.defaults` (or pass your own `featuredItems` into `HomeContent`):

```swift theme={null}
public static let defaults: [HomeContent.FeatureItem] = [
    // ... existing cards
    HomeContent.FeatureItem(
        title: "Your Feature",
        description: "Feature description",
        systemImage: "bookmark.fill",
        accentColor: "blue"
    ),
]
```

### Change Chat Bubble Colors

Bubble colors are derived from design tokens, not from dedicated bubble color sets. In `DSColors.swift`:

* `bubbleUserOrFallback` → `accentPrimary` (the `AccentPrimary.colorset` for system/light/dark)
* `bubbleAssistantOrFallback` → `surface` (a system color, `Color(.secondarySystemBackground)`, for system/light/dark)

Change the user bubble by editing `AccentPrimary.colorset` in `Packages/DesignSystem/Sources/DesignSystem/Resources/Assets.xcassets/`. The assistant bubble follows the system surface color, so adjust the `surface` token's `switch activeTheme` branch in `DSColors.swift` to override it.

### Add Custom Theme

<Steps>
  <Step title="Create Color Sets">
    In the DesignSystem package catalog (`Packages/DesignSystem/Sources/DesignSystem/Resources/Assets.xcassets`), create color sets for any semantic colors your theme needs.
  </Step>

  <Step title="Add Theme Case">
    In `SettingsDTO.swift`, add a case to the string-backed `Theme` enum (used by the settings UI):

    ```swift theme={null}
    public enum Theme: String, Sendable, Equatable, CaseIterable {
        case system, light, dark, aurora, obsidian
        case myTheme  // Add this
    }
    ```
  </Step>

  <Step title="Map Colors">
    In `DSColors.swift`, add a `case .myTheme` to the internal `ThemePalette` enum and to each token `switch activeTheme` block.
  </Step>

  <Step title="Add to Picker">
    The appearance picker in `SettingsAppearanceSection.swift` iterates `SettingsDTO.Theme.allCases`, so the new case appears automatically once the enum and mappings are in place.
  </Step>
</Steps>

## Feature Customization

### Add Custom AI Persona

**File:** `Packages/FeatureChat/Sources/FeatureChat/ViewModels/ChatViewModel.swift`

`LLMMessage` lives in `FeatureChat` and its `role` is a `String` (`"user" | "assistant" | "system"`):

```swift theme={null}
// Inside ChatViewModel.send() (the real entry point is `public func send() async`),
// build the prompt list with a persona system message:
let systemPrompt = LLMMessage(
    role: "system",
    content: """
    You are a professional Swift developer.
    Provide clear, concise answers with code examples.
    """
)

let messages = [systemPrompt] + history  // `history` mapped to [LLMMessage]
// Pass `messages` to llmClient when streaming
```

<Note>
  The server-side AI Edge Function (`supabase/functions/ai/index.ts`) injects its own fixed `SYSTEM_PROMPT` and clients may only send `user`/`assistant` roles, so a client-supplied system message is for local/echo flows. To change the deployed persona, edit `SYSTEM_PROMPT` in the function and redeploy.
</Note>

### Add New SwiftData Model

<Steps>
  <Step title="Create Model">
    ```swift theme={null}
    @Model
    class YourModel {
        @Attribute(.unique) var id: UUID
        var property: String
        var createdAt: Date
    }
    ```
  </Step>

  <Step title="Create DTO">
    ```swift theme={null}
    struct YourModelDTO: Identifiable, Sendable {
        let id: UUID
        let property: String
        
        init(_ model: YourModel) {
            self.id = model.id
            self.property = model.property
        }
    }
    ```
  </Step>

  <Step title="Create Repository">
    Protocol + implementation following existing patterns
  </Step>

  <Step title="Add to Schema">
    In `SwiftAIBoilerplatePro/Composition/CompositionRoot.swift`, add your model to the `Schema([Conversation.self, Message.self, Settings.self])` array.
  </Step>
</Steps>

### Add Custom Setting

<Steps>
  <Step title="Update Settings Model">
    In `Packages/Storage/Sources/Storage/Models/Settings.swift`:

    ```swift theme={null}
    @Model
    public final class Settings {
        public var theme: String  // "system" | "light" | "dark"
        public var yourSetting: Bool = false  // Add this
    }
    ```
  </Step>

  <Step title="Update ViewModel">
    ```swift theme={null}
    @Observable
    class SettingsViewModel {
        var yourSetting: Bool
        
        func toggleYourSetting(_ enabled: Bool) async {
            // Save to repository
        }
    }
    ```
  </Step>

  <Step title="Update UI">
    ```swift theme={null}
    Toggle("Your Setting", isOn: $viewModel.yourSetting)
        .onChange(of: viewModel.yourSetting) {
            Task { await viewModel.toggleYourSetting($0) }
        }
    ```
  </Step>
</Steps>

## Backend Customization

### Change AI Model

**File:** `supabase/functions/ai/index.ts`

For cost safety, the function validates the requested model against an allowlist (security rule BL-003). To allow a different OpenRouter model, add it to `ALLOWED_MODELS`:

```typescript theme={null}
// Only allow-listed models are accepted; everything else is rejected with 400.
const ALLOWED_MODELS = [
  'openai/gpt-3.5-turbo',
  'openai/gpt-4o-mini',
  'anthropic/claude-3-5-sonnet',  // Add the models you want to permit
]
```

The request body's `model` defaults to `openai/gpt-3.5-turbo` and must be in this list. The server-side `SYSTEM_PROMPT` and role allowlist (`user`/`assistant`) are also enforced here.

**Deploy:**

```bash theme={null}
supabase functions deploy ai
```

### Add Usage Limits

`PaymentsClient.currentState()` and `state.isSubscribed` are real APIs; the per-day count below is illustrative — back it with your own repository query.

```swift theme={null}
func canSendMessage() async -> Bool {
    let state = await paymentsClient.currentState()
    
    if state.isSubscribed {
        return true  // Unlimited for pro
    } else {
        let count = await messageRepository.todayCount()  // your own query
        return count < 20  // Free tier limit
    }
}
```

## Module Customization

Each module has detailed customization examples:

<CardGroup>
  <Card title="Core" href="/pages/modules/core">
    Custom errors, log categories
  </Card>

  <Card title="Networking" href="/pages/modules/networking">
    Custom requests, interceptors
  </Card>

  <Card title="Storage" href="/pages/modules/storage">
    New models, repositories
  </Card>

  <Card title="Auth" href="/pages/modules/auth">
    Social providers, custom fields
  </Card>

  <Card title="Payments" href="/pages/modules/payments">
    New tiers, usage limits
  </Card>

  <Card title="AI" href="/pages/modules/ai">
    Models, personas, prompts
  </Card>

  <Card title="FeatureChat" href="/pages/modules/feature-chat">
    UI styles, actions, search
  </Card>

  <Card title="FeatureSettings" href="/pages/modules/feature-settings">
    New settings, paywall
  </Card>

  <Card title="DesignSystem" href="/pages/modules/design-system">
    Themes, components, tokens
  </Card>
</CardGroup>

## Pro Tips

<Tip>
  **Test after each change** - Don't stack multiple changes without testing
</Tip>

<Tip>
  **Use design tokens** - Never hardcode colors or spacing
</Tip>

<Tip>
  **Follow existing patterns** - Look for similar features first
</Tip>

<Tip>
  **Keep files ≤ 300 lines** - Extract components when needed
</Tip>

## Need More Help?

<CardGroup>
  <Card title="Building Guide" icon="book" href="/pages/guides/building-your-app">
    Step-by-step guide with LLM prompts
  </Card>

  <Card title="Module Docs" icon="cube" href="/pages/modules/core">
    Detailed technical docs
  </Card>

  <Card title="CLAUDE.md" icon="robot" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/CLAUDE.md">
    AI coding guidelines
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    System design
  </Card>
</CardGroup>


# Deployment Guide
Source: https://docs.swiftaiboilerplate.com/pages/guides/deployment

Ship your app to TestFlight and the App Store with OpenRouter AI integration

<Info>
  Find complete deployment steps in your project [Building Your App](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/BUILDING_YOUR_APP.md)
</Info>

## OpenRouter Setup

Before deploying, you need to set up the AI proxy through Supabase Edge Functions. This keeps your API keys secure on the server.

<Warning>
  Never bundle API keys in your iOS app. Keys can be extracted from the binary. Our architecture routes all AI requests through Supabase Edge Functions.
</Warning>

<Steps>
  <Step title="Generate OpenRouter API Key">
    Sign up or sign in to [OpenRouter](https://openrouter.ai):

    1. Create your first project
    2. Generate your API key

    <Note>
      This is a **private key**. We will deploy it directly to our Supabase Edge Function and never bundle it with our app or push it to git.
    </Note>
  </Step>

  <Step title="Set OpenRouter Key as Supabase Secret">
    Set your OpenRouter key as a Supabase secret:

    ```bash theme={null}
    supabase secrets set OPENROUTER_API_KEY=sk-or-your-openrouter-key
    ```

    This keeps your API key secure on the server side.
  </Step>

  <Step title="Deploy AI Edge Function">
    Deploy the AI Edge Function to Supabase:

    ```bash theme={null}
    supabase functions deploy ai
    ```

    The boilerplate includes a ready-to-deploy Edge Function that handles all AI API calls securely.
  </Step>

  <Step title="Verify Deployment">
    Verify your function is deployed:

    1. Go to **Supabase Dashboard** → **Edge Functions**
    2. See your `ai` function listed
    3. Note down the function URL
  </Step>

  <Step title="Update the proxy config">
    Open `Config/Secrets.xcconfig` in Xcode and set the base URL plus path. The function name (`ai`) is the `PROXY_PATH`, not part of `PROXY_BASE_URL`:

    ```bash theme={null}
    PROXY_BASE_URL = https://your-project-ref.supabase.co/functions/v1
    PROXY_PATH = /ai
    ```

    Then run the update script:

    ```bash theme={null}
    bash scripts/update-config.sh
    ```
  </Step>
</Steps>

## Deployment Phases

<Steps>
  <Step title="Pre-Deployment">
    * Run the full test suite (\~598 tests across 12 package test targets + the app test suites, one `Boilerplate.xctestplan` run)
    * Fix all linter warnings
    * Test on real devices
    * Update legal documents
  </Step>

  <Step title="TestFlight Beta">
    * Archive build
    * Upload to App Store Connect
    * Add internal testers
    * Gather feedback
  </Step>

  <Step title="App Store Submission">
    * Prepare metadata
    * Create screenshots
    * Submit for review
    * Monitor status
  </Step>

  <Step title="Production Launch">
    * Configure production backends
    * Monitor crashes
    * Respond to reviews
    * Plan updates
  </Step>
</Steps>

## Pre-Deployment Checklist

<AccordionGroup>
  <Accordion title="Code Quality">
    * [ ] All tests pass (⌘U)
    * [ ] No warnings in build
    * [ ] Tested on real device
    * [ ] Performance is smooth
    * [ ] No crashes in common flows
  </Accordion>

  <Accordion title="Configuration">
    * [ ] Real backends configured (not mock)
    * [ ] API keys in `Config/Secrets.xcconfig`
    * [ ] Bundle ID matches App Store Connect
    * [ ] Version number set (e.g., 1.0.0)
    * [ ] Build number set (start at 1)
  </Accordion>

  <Accordion title="Legal">
    * [ ] Privacy policy updated
    * [ ] Terms of service updated
    * [ ] Subscription terms updated
    * [ ] Privacy policy URL works
    * [ ] Terms URL works
  </Accordion>

  <Accordion title="Assets">
    * [ ] App icon (1024×1024)
    * [ ] Screenshots for all sizes
    * [ ] App description written
    * [ ] Keywords added
    * [ ] Support URL set
  </Accordion>
</AccordionGroup>

## TestFlight Deployment

### 1. Archive Build

```text theme={null}
# In Xcode
Product → Archive

# Wait for archive to complete
# Organizer window opens automatically
```

### 2. Validate Archive

```text theme={null}
# In Organizer
1. Select your archive
2. Click "Validate App"
3. Choose options:
   - Upload symbols: Yes
   - Manage version: No
4. Click "Validate"
5. Fix any errors
```

### 3. Upload to App Store

```text theme={null}
# In Organizer
1. Click "Distribute App"
2. Choose "App Store Connect"
3. Next → Upload
4. Wait for processing (~5-10 minutes)
```

### 4. Add Testers

**Internal Testers (up to 100):**

* App Store Connect → TestFlight → Internal Testing
* Add team members
* They receive email invite
* Install via TestFlight app

**External Testers (up to 10,000):**

* Create group: "Beta Testers"
* Add email addresses
* Requires beta review (1-2 days)
* Public link available

### 5. Test Thoroughly

* [ ] Sign up flow
* [ ] Chat functionality
* [ ] Subscription purchases (sandbox)
* [ ] Settings and preferences
* [ ] Performance on various devices

## App Store Submission

<Warning>
  **Run [App Store 4.3 hardening](/pages/guides/app-store-4-3-hardening) before this step.** It covers the binary `strings` audit, branding map, dead-code removal, and screenshot ordering. The most common rejection reason for boilerplate-based apps is undifferentiated product, not a metadata typo.
</Warning>

### 1. Prepare Metadata

**In App Store Connect:**

```text theme={null}
App Information:
- Name: Your App Name
- Subtitle: Short description
- Privacy Policy URL: https://yoursite.com/privacy
- Category: Productivity (or your category)
- Content Rights: Does not use third-party content
```

### 2. Create Screenshots

**Required sizes:**

* 6.7" (iPhone 15 Pro Max): 1290 × 2796
* 6.5" (older Pro Max): 1284 × 2778
* 5.5" (older Plus): 1242 × 2208
* 12.9" iPad Pro: 2048 × 2732 (if supporting iPad)

**Tips:**

* 4-10 screenshots per size
* Show key features
* Add text overlays
* First screenshot most important

### 3. Write Description

**Template:**

```markdown theme={null}
[Your App] is an AI-powered [category] that helps you [benefit].

FEATURES:
• AI Chat - Get instant answers
• Smart Conversations - History saved
• Premium Themes - Beautiful UI
• Cross-Device Sync - Access everywhere

PERFECT FOR:
• [Target audience 1]
• [Target audience 2]

PREMIUM FEATURES:
• Unlimited messages
• All AI models
• Priority support

Privacy Policy: [URL]
Terms: [URL]
```

### 4. Configure App Privacy

Answer privacy questionnaire:

**Data collected:**

* Contact Info: Email (for account)
* Identifiers: User ID (for backend)
* Usage Data: App interactions (if analytics)
* User Content: Chat messages

For each: Linked to identity, Used for app functionality

### 5. Submit for Review

```text theme={null}
# In App Store Connect
1. App Store tab → Version
2. Add screenshots
3. Add description
4. Select build
5. Submit for Review
```

**Review time:** 24-48 hours typically

## Production Configuration

### Backend Setup

<Tabs>
  <Tab title="Supabase">
    1. Use production Supabase project
    2. Verify Edge Function deployed (`supabase functions deploy ai`)
    3. Set production OpenRouter key (`supabase secrets set OPENROUTER_API_KEY=...`)
    4. Monitor API usage in Supabase dashboard
  </Tab>

  <Tab title="RevenueCat">
    1. Switch to **production API key** in `Secrets.xcconfig`
    2. Verify App Store Connect products are approved
    3. Map production products in RevenueCat offerings
    4. Test a real purchase before launch
  </Tab>

  <Tab title="OpenRouter">
    1. Add credits to your OpenRouter account
    2. Set up usage alerts and spending limits
    3. Monitor token usage in dashboard
    4. Consider rate limiting in Edge Function
  </Tab>
</Tabs>

### Final Verification

```swift theme={null}
// In SwiftAIBoilerplatePro/Composition/FeatureFlags.swift
// Crashlytics is opt-in via env var, even in Release builds.
public static var crashlyticsEnabled: Bool {
    #if DEBUG
    return false // Off by default in debug
    #else
    return ProcessInfo.processInfo.environment["CRASHLYTICS_ENABLED"] == "true"
    #endif
}
```

To turn Crashlytics on in production, set the `CRASHLYTICS_ENABLED=true` environment variable in your Release scheme (and follow the [Crashlytics setup guide](/pages/guides/crashlytics-setup)). Then verify your production secrets:

```bash theme={null}
# In Config/Secrets.xcconfig - Verify production URLs
SUPABASE_URL = https://production-project.supabase.co
REVENUECAT_API_KEY = appl_PRODUCTION_KEY
```

## Post-Launch

### Monitor

* [ ] Crashlytics dashboard (if enabled)
* [ ] App Store Connect analytics
* [ ] RevenueCat subscription metrics
* [ ] Supabase API usage
* [ ] User reviews and ratings

### Respond

* [ ] Reply to user reviews
* [ ] Fix critical bugs immediately
* [ ] Plan feature updates
* [ ] Gather user feedback

### Update Regularly

**Recommended cadence:**

* Bug fixes: As needed (1-3 days)
* Minor updates: Every 2-4 weeks
* Major features: Every 2-3 months

## Complete Guide

<Card title="View Complete Launch Checklist" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/BUILDING_YOUR_APP.md#launch-checklist">
  Find complete deployment checklist in your project
</Card>

## Related Resources

<CardGroup>
  <Card title="Testing Guide" icon="flask" href="/pages/guides/testing">
    Run full test suite
  </Card>

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

  <Card title="RevenueCat Setup" icon="dollar" href="/pages/guides/revenuecat-setup">
    Production subscriptions
  </Card>

  <Card title="Building Guide" icon="hammer" href="/pages/guides/building-your-app">
    Complete customization
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Archive fails">
    * Clean build (⌘⇧K)
    * Check signing certificates
    * Verify provisioning profiles
    * Update Xcode if needed
  </Accordion>

  <Accordion title="App rejected">
    * Read rejection carefully
    * Fix specific issues mentioned
    * Update metadata if needed
    * Resubmit with explanation
    * If the rejection cites Guideline 4.3 or 4.2.6, see the [4.3 hardening recovery steps](/pages/guides/app-store-4-3-hardening#if-you-already-got-a-43-rejection)
  </Accordion>

  <Accordion title="Crashes in production">
    * Check Crashlytics logs
    * Reproduce locally
    * Fix and submit hotfix
    * Expedited review if critical
  </Accordion>
</AccordionGroup>


# OneSignal Push Notifications
Source: https://docs.swiftaiboilerplate.com/pages/guides/onesignal-setup

Add push notifications to your app with OneSignal SDK

<Info>
  **Complete setup guide:** See `/docs/integrations/OneSignal.md` in the project
</Info>

## What is OneSignal?

<CardGroup>
  <Card title="Push Notifications" icon="bell">
    Send push notifications to engage users
  </Card>

  <Card title="Rich Notifications" icon="image">
    Images, buttons, badges, and custom sounds
  </Card>

  <Card title="Analytics" icon="chart-line">
    Confirmed delivery and engagement tracking
  </Card>

  <Card title="Segmentation" icon="users">
    Target users by behavior, tags, or segments
  </Card>
</CardGroup>

<Note>
  **Optional Integration**: OneSignal is completely optional. Your app works perfectly fine without it. Simply don't configure the App ID if you don't need push notifications.
</Note>

## Features Included

* ✅ Push notifications via OneSignal SDK
* ✅ Rich notifications with images, buttons, and badges
* ✅ Confirmed delivery analytics
* ✅ User segmentation support
* ✅ In-app messaging capability
* ✅ Notification Service Extension pre-configured
* ✅ Graceful degradation (works without configuration)

## Prerequisites

* [OneSignal account](https://onesignal.com) (free tier available)
* Apple Developer account (for push certificate)
* App ID with Push Notifications capability enabled

## Setup Guide

OneSignal provides excellent, regularly-updated documentation for iOS SDK setup. We recommend following their official guide:

<Card title="OneSignal iOS SDK Setup" icon="arrow-up-right-from-square" href="https://documentation.onesignal.com/docs/ios-sdk-setup">
  Follow OneSignal's comprehensive step-by-step guide for iOS integration
</Card>

### Quick Overview

<Steps>
  <Step title="Create OneSignal Account">
    Go to [OneSignal](https://onesignal.com) and create a free account. The free tier includes unlimited push notifications for up to 10,000 subscribers.
  </Step>

  <Step title="Follow OneSignal's iOS Setup">
    Their guide covers:

    * Adding Push Notifications capability
    * Configuring Background Modes
    * Setting up App Groups
    * Adding Notification Service Extension
    * Installing the SDK

    [Open OneSignal iOS SDK Setup →](https://documentation.onesignal.com/docs/ios-sdk-setup)
  </Step>

  <Step title="Add App ID to Config">
    After OneSignal setup, add your App ID to `Config/Secrets.xcconfig`:

    ```bash theme={null}
    ONESIGNAL_APP_ID = YOUR_ONESIGNAL_APP_ID
    ```
  </Step>

  <Step title="Run Update Config Script">
    Generate the Swift configuration:

    ```bash theme={null}
    bash scripts/update-config.sh
    ```
  </Step>

  <Step title="Build and Test">
    Build and run on a **real device** (push notifications don't work in simulator):

    1. Run the app
    2. Accept push notification permission
    3. Send a test notification from OneSignal dashboard
    4. Verify notification appears on device
  </Step>
</Steps>

## How It Works

### Automatic Integration

The boilerplate automatically initializes OneSignal from `AppDelegate` when the App ID is configured:

```swift theme={null}
// AppDelegate.initializeOneSignal(launchOptions:) — runs automatically
let appId = AppConfiguration.ONESIGNAL_APP_ID

guard AppConfiguration.isConfigured("ONESIGNAL_APP_ID") else {
    AppLogger.error("OneSignal App ID not configured - push notifications disabled.",
                    category: AppLogger.notifications)
    return
}

OneSignal.initialize(appId, withLaunchOptions: launchOptions)
OneSignal.Notifications.requestPermission({ accepted in
    AppLogger.info("OneSignal notification permission: \(accepted ? "granted" : "denied")",
                   category: AppLogger.notifications)
}, fallbackToSettings: true)
```

**No code changes needed.** Just add the App ID to your config and rebuild.

### Graceful Degradation

If OneSignal is not configured:

* App launches normally
* No SDK initialization
* No errors or crashes
* Push notification code paths are skipped

## Removing OneSignal

If you don't need push notifications:

1. **Leave ONESIGNAL\_APP\_ID empty** in `Secrets.xcconfig`
2. The SDK won't initialize
3. No push notification code will run

To completely remove:

1. Remove OneSignal package from Swift Package Manager
2. Delete the Notification Service Extension target
3. Remove OneSignal references from code
4. See `/docs/integrations/OneSignal.md` for complete removal guide

## Troubleshooting

<AccordionGroup>
  <Accordion title="Notifications not received">
    * Test on a **real device** (not simulator)
    * Verify APNs certificate/key is correct in OneSignal
    * Check Push Notifications capability is enabled in Xcode
    * Ensure user accepted notification permission
    * Check OneSignal dashboard for delivery status
  </Accordion>

  <Accordion title="Rich notifications not showing images">
    * Verify Notification Service Extension is in your target
    * Check image URL is HTTPS
    * Ensure image is under 10MB
    * Test with a simple image first
  </Accordion>

  <Accordion title="OneSignal not initializing">
    * Verify ONESIGNAL\_APP\_ID is set in Secrets.xcconfig
    * Run `bash scripts/update-config.sh`
    * Check Configuration.swift has the App ID
    * Clean and rebuild (⌘⇧K then ⌘B)
  </Accordion>
</AccordionGroup>

## Cost

**OneSignal Free Tier:**

* ✅ Unlimited push notifications
* ✅ Up to 10,000 subscribers
* ✅ Basic analytics
* ✅ Enough for most indie apps

**Paid Plans:**

* More subscribers
* Advanced analytics
* A/B testing
* Priority support

## Related Guides

<CardGroup>
  <Card title="OneSignal Official Docs" icon="arrow-up-right-from-square" href="https://documentation.onesignal.com/docs/ios-sdk-setup">
    Comprehensive iOS SDK setup guide
  </Card>

  <Card title="Supabase Setup" icon="database" href="/pages/guides/supabase-setup">
    Backend configuration
  </Card>

  <Card title="Crashlytics Setup" icon="bug" href="/pages/guides/crashlytics-setup">
    Another optional integration
  </Card>

  <Card title="Deployment" icon="rocket" href="/pages/guides/deployment">
    Ship to App Store
  </Card>
</CardGroup>

## Need Help?

* 📖 Check the troubleshooting section above
* 📚 See `/docs/integrations/OneSignal.md` in your project
* 💬 [Create an issue](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/issues)
* 🔍 Search [OneSignal docs](https://documentation.onesignal.com)


# Profile Photo Setup
Source: https://docs.swiftaiboilerplate.com/pages/guides/profile-photos

Store profile photos in Supabase Storage for cross-device access.

<Info>
  **Complete setup guide:** see `docs/integrations/ProfilePhotos.md` in your project repo.
</Info>

## What Is Profile Photo Storage?

<CardGroup>
  <Card title="Cloud Storage" icon="cloud-arrow-up">
    Photos stored in Supabase Storage
  </Card>

  <Card title="Cross-Device" icon="mobile">
    Same photo on all devices
  </Card>

  <Card title="Automatic Compression" icon="compress">
    \~500KB target size
  </Card>

  <Card title="Fallback" icon="shield">
    Works locally if upload fails
  </Card>
</CardGroup>

## Quick Overview

<Steps>
  <Step title="Create Storage Bucket">
    In Supabase Dashboard:

    * Storage → New Bucket
    * Name: `profile-photos`
    * Public: ✅ Enable
  </Step>

  <Step title="Set RLS Policies">
    Photos are uploaded under `avatars/{userId}_{timestamp}.jpg`. Add these policies (the full setup guide also adds matching UPDATE and DELETE policies):

    ```sql theme={null}
    -- Users can upload their own photos
    CREATE POLICY "Users upload own" ON storage.objects
    FOR INSERT TO authenticated WITH CHECK (
      bucket_id = 'profile-photos' AND
      (storage.foldername(name))[1] = 'avatars' AND
      auth.uid()::text = (storage.foldername(name))[2]
    );

    -- Photos are public (read)
    CREATE POLICY "Photos public" ON storage.objects
    FOR SELECT TO public USING (bucket_id = 'profile-photos');
    ```

    The full guide also adds matching UPDATE and DELETE policies.
  </Step>

  <Step title="Uncomment Implementation">
    In `SupabaseProfilePhotoStorageClient.swift`:

    * Uncomment `import Supabase`
    * Remove comment blocks
  </Step>

  <Step title="Enable in CompositionRoot">
    ```swift theme={null}
    self.profilePhotoStorageClient = SupabaseProfilePhotoStorageClient(
        supabaseClient: supabaseClient,
        bucketName: "profile-photos"
    )
    ```
  </Step>
</Steps>

## How It Works

```text theme={null}
Upload Flow:
User selects photo → Compress (~500KB) → Upload to Supabase → Update profile

Download Flow:
App opens → Load from Supabase → Cache locally → Display
```

**Benefits:**

* ✅ Photos sync across devices
* ✅ Automatic compression
* ✅ Public CDN URLs
* ✅ Graceful fallback to local
* ✅ Privacy-first (iOS 17+ PhotosPicker)

## Prerequisites

* Supabase project configured
* Supabase dependency in Storage package
* User authenticated

## What You Get

After setup:

* ✅ Upload profile photos
* ✅ Photos sync across devices
* ✅ Automatic compression
* ✅ CDN-hosted images
* ✅ Local fallback if upload fails
* ✅ No camera permissions needed (PhotosPicker)

## Complete Guide

The **12KB comprehensive guide** includes:

* Storage bucket configuration
* Row Level Security policies
* Upload implementation
* Compression strategy
* Error handling
* Testing procedures

<Card title="View Complete Setup Guide" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/integrations/ProfilePhotos.md">
  Find complete profile photo storage guide in your project
</Card>

## Related Guides

<CardGroup>
  <Card title="Storage Module" icon="database" href="/pages/modules/storage">
    Storage architecture
  </Card>

  <Card title="Chat Sync" icon="cloud" href="/pages/guides/chat-sync">
    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?

* 📖 Complete troubleshooting in full guide
* 💬 [Create an issue](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/issues)
* 🔍 Check Supabase Storage logs


# RevenueCat Setup
Source: https://docs.swiftaiboilerplate.com/pages/guides/revenuecat-setup

Complete guide to configuring in-app subscriptions with RevenueCat

<Info>
  **Find complete step-by-step guide in your project:** [revenuecat.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/integrations/RevenueCat.md)
</Info>

## What You'll Set Up

<CardGroup>
  <Card title="Subscriptions" icon="credit-card">
    Monthly and annual subscription plans
  </Card>

  <Card title="Paywall" icon="lock">
    Beautiful subscription UI (already built!)
  </Card>
</CardGroup>

## Prerequisites

* Apple Developer account (\$99/year)
* [RevenueCat account](https://revenuecat.com) (free tier available)
* Completed [Supabase Setup](/pages/guides/supabase-setup)

<Warning>
  Subscriptions are the trickiest integration to get right. Work through each step in order, and reach out if you get stuck.
</Warning>

## Part 1: App Store Connect Setup

<Steps>
  <Step title="Create Bundle Identifier">
    Go to **App Store Connect** → **Certificates, Identifiers & Profiles** → **Identifiers** (left menu) → **Add new identifier**.

    Create a new App ID with your bundle identifier (e.g., `com.yourcompany.yourapp`).
  </Step>

  <Step title="Enable Capabilities">
    Select your App ID and enable the required capabilities:

    * ✅ Push Notifications
    * ✅ In-App Purchase
    * ✅ Sign in with Apple
    * ✅ Associated Domains
    * ✅ Any other capabilities you need
  </Step>

  <Step title="Create New App">
    Go to **Apps** in App Store Connect and click **Create new app** (+ button).
  </Step>

  <Step title="Fill App Form">
    Fill the form with your bundle ID and create the app:

    * Platform: iOS
    * Name: Your App Name
    * Primary Language: English (or your language)
    * Bundle ID: Select the one you created
    * SKU: A unique identifier (e.g., `yourapp2024`)
  </Step>

  <Step title="Create Subscription Group">
    If you're adding subscriptions:

    1. Go to **Subscriptions** from the left menu
    2. Click **Create** to add a new subscription group
    3. Name it (e.g., "Premium Access")
  </Step>

  <Step title="Create Subscriptions">
    Create subscriptions under the subscription group:

    * Add **Monthly** subscription (e.g., `monthly_subscription`)
    * Add **Annual** subscription (e.g., `annual_subscription`)

    <Warning>
      Make sure to note down the **Product IDs** exactly as you create them. Arrange their order in **descending order** as described by Apple (longest duration first).
    </Warning>
  </Step>
</Steps>

## Part 2: RevenueCat Dashboard Setup

<Steps>
  <Step title="Create RevenueCat Project">
    Go to [RevenueCat](https://app.revenuecat.com) and create a new project:

    1. Click **Create New Project**
    2. Name your project
    3. Select **iOS** as platform
  </Step>

  <Step title="Create Offerings">
    Create a new offering in RevenueCat:

    1. Go to **Products** → **Entitlements**
    2. Create entitlement named `pro` (or your choice)
    3. Go to **Offerings** and create a new offering
    4. Add your subscription products to the offering

    <Warning>
      Make **100% sure** the entitlement name matches what you use in your app code and note it down.
    </Warning>
  </Step>

  <Step title="SDK Already Installed">
    The RevenueCat SDK is already installed in the boilerplate!

    Just make sure:

    * Package dependencies are resolved in Xcode
    * You have your **test API key** ready

    <Note>
      The remaining steps RevenueCat suggests (SDK initialization, configuration, entitlement checks) are already wired up in the `Payments` package, so you only need the API key and entitlement ID.
    </Note>
  </Step>

  <Step title="Update Config with API Key">
    Add your test API key to `Config/Secrets.xcconfig`:

    ```text theme={null}
    REVENUECAT_API_KEY = appl_YOUR_TEST_API_KEY
    RC_ENTITLEMENT_ID = pro
    ```

    Then run the update config script again:

    ```bash theme={null}
    bash scripts/update-config.sh
    ```

    This regenerates `SwiftAIBoilerplatePro/Generated/Configuration.swift` with your values.
  </Step>
</Steps>

## Part 3: Testing Configuration

<Steps>
  <Step title="Disable Auth Bypass">
    In Xcode, configure the scheme for testing:

    1. Select your target from top menu
    2. **Edit Scheme** → **Arguments** tab
    3. Under **Environment Variables**, set `AUTH_BYPASS` to `0` (or remove it)
  </Step>

  <Step title="StoreKit Configuration">
    For **simulator testing**:

    1. Select your target → **Edit Scheme**
    2. Go to **Options** tab
    3. **StoreKit Configuration** → select the bundled `StoreKitConfiguration.storekit` (in `SwiftAIBoilerplatePro/Resources/`)

    <Note>
      For **real device testing**, leave StoreKit Configuration set to **None**.
    </Note>
  </Step>

  <Step title="Verify Subscription Status">
    Make sure the statuses of your subscriptions are **Ready to Submit** in App Store Connect.

    Check each subscription product and ensure all required fields are filled.
  </Step>

  <Step title="App Store Connect API Key">
    Configure your App Store Connect API Key in RevenueCat:

    <Card title="RevenueCat Official Guide" icon="link" href="https://www.revenuecat.com/docs/service-credentials/itunesconnect-app-specific-shared-secret/app-store-connect-api-key-configuration">
      Follow RevenueCat's official documentation for App Store Connect API key setup
    </Card>

    <Note>
      We're not documenting this step in detail because when Apple changes it, RevenueCat updates their docs immediately.
    </Note>
  </Step>

  <Step title="Map Product IDs Correctly">
    In your RevenueCat offering, make sure to map the correct test product with your real App Store product.

    <Warning>
      Product IDs must match **exactly**. For example, if your 12-month subscription is mapped to a 1-month test product, it won't work. They must be mapped correctly.
    </Warning>
  </Step>

  <Step title="Verify Offerings Load">
    Run your app and navigate to the paywall. You should see your subscription offerings loading correctly.

    <Note>
      Detailed live RevenueCat logs are added to the project. If you have problems fetching products, analyze the console logs.
    </Note>
  </Step>
</Steps>

## Part 4: Sandbox Testing

<Steps>
  <Step title="Create Sandbox Account">
    Create a sandbox test account:

    1. Go to **App Store Connect**
    2. **Users and Access** → **Sandbox**
    3. Create a new sandbox tester account
  </Step>

  <Step title="Sign In on Device">
    On your simulator or device:

    1. Go to **Settings** → **Developer**
    2. Sign in with your **Sandbox Account**
    3. Try purchasing from your app
  </Step>

  <Step title="Common Issue: Bundle Mismatch">
    Be aware of this common issue: **Bundle ID mismatch** between App Store Connect and RevenueCat.

    <Warning>
      Make sure to upload a build to App Store Connect first. This registers your bundle ID properly and resolves many "products not found" issues.
    </Warning>
  </Step>

  <Step title="Verify on Dashboard">
    Check the RevenueCat customers dashboard after making a test purchase.

    <Note>
      It may take some time (up to an hour) for transactions to appear in the dashboard.
    </Note>
  </Step>
</Steps>

## What You Get

After setup:

* ✅ Working subscription purchases
* ✅ Beautiful paywall UI
* ✅ Subscription status tracking
* ✅ Restore purchases functionality
* ✅ Simulator testing with StoreKit Configuration
* ✅ Detailed logging for debugging

## Product Setup Example

**Monthly Subscription:**

* Product ID: `monthly_subscription`
* Type: Auto-Renewable Subscription
* Price: \$9.99/month

**Annual Subscription:**

* Product ID: `annual_subscription`
* Type: Auto-Renewable Subscription
* Price: \$79.99/year

## Troubleshooting

<AccordionGroup>
  <Accordion title="Products not loading">
    * Verify Product IDs match exactly in App Store Connect, RevenueCat, and StoreKit config
    * Upload a build to App Store Connect first
    * Check RevenueCat logs in console
    * Ensure subscription status is "Ready to Submit"
  </Accordion>

  <Accordion title="Purchase fails in sandbox">
    * Sign out of real App Store account
    * Sign in with sandbox account in Settings → Developer
    * Restart the app
    * Try again
  </Accordion>

  <Accordion title="Entitlement not granted">
    * Verify entitlement name matches in code and RevenueCat dashboard
    * Check that products are correctly mapped to entitlement
    * Wait a few minutes and check RevenueCat dashboard
  </Accordion>

  <Accordion title="Bundle ID mismatch error">
    * Ensure bundle ID in Xcode matches App Store Connect
    * Upload a test build to App Store Connect
    * Re-sync products in RevenueCat
  </Accordion>
</AccordionGroup>

## Related Guides

<CardGroup>
  <Card title="Payments Module" icon="dollar" href="/pages/modules/payments">
    Technical documentation
  </Card>

  <Card title="Feature Settings" icon="gear" href="/pages/modules/feature-settings">
    Paywall UI details
  </Card>

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

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

## Need Help?

* 📖 Check the troubleshooting section above
* 💬 [Create an issue](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/issues)
* 🔍 Search [RevenueCat docs](https://docs.revenuecat.com)


# Agentic Development Setup
Source: https://docs.swiftaiboilerplate.com/pages/guides/skills-setup

Set up Claude Code for agentic iOS development with SwiftAI Boilerplate Pro

SwiftAI Boilerplate Pro ships with a production-tested `AGENTS.md` at the repository root that gives Claude Code and Claude-powered agents project context from the first message. It points the agent to the full guidelines in `docs/CLAUDE.md`. Combined with community skills, Claude understands your architecture, follows your patterns, and can build and verify features autonomously.

<Info>
  **Ready out of the box.** `AGENTS.md` is at the root of the boilerplate and references `docs/CLAUDE.md`. Open Claude Code or Xcode Coding Intelligence from the project directory so the agent can load these automatically.
</Info>

## How It Works

`AGENTS.md` and `docs/CLAUDE.md` tell Claude about **your project**: the MVVM architecture, module boundaries, which abstractions to use, build commands, and what patterns to follow.

Community skills teach Claude about **iOS development in general**: SwiftUI best practices, App Store guidelines, simulator automation.

| Layer                | What It Provides                                  | File                                  |
| -------------------- | ------------------------------------------------- | ------------------------------------- |
| **Project-specific** | Architecture, abstractions, module boundaries     | `AGENTS.md` (root) → `docs/CLAUDE.md` |
| **Domain-wide**      | iOS best practices, debugging, testing, App Store | Community skills                      |

Together, they let Claude generate code that fits your project and follows platform conventions.

***

## Xcode Coding Intelligence

Xcode Coding Intelligence with Claude Agent works well with SwiftAI Boilerplate Pro as long as the agent is opened from the repository root. The important files are:

```text theme={null}
SwiftAIBoilerplatePro/
├── AGENTS.md
├── SwiftAIBoilerplatePro.xcodeproj
├── Packages/
└── docs/
    └── CLAUDE.md
```

`AGENTS.md` must stay in the project root; it points the agent to `docs/CLAUDE.md`. If an agent says it cannot see the project instructions, check that you opened the repository folder itself, not only the `docs/` folder or an individual Xcode file.

<Steps>
  <Step title="Open the full project">
    Open the root folder that contains `AGENTS.md` and `SwiftAIBoilerplatePro.xcodeproj`.
  </Step>

  <Step title="Start Claude Agent in Xcode">
    Use Xcode Coding Intelligence from that project context. The boilerplate instructions are already written for SwiftUI, MVVM, Swift Packages, Supabase, RevenueCat, OpenRouter, and strict concurrency.
  </Step>

  <Step title="Verify the agent loaded context">
    Ask: "Before coding, summarize the rules from `docs/CLAUDE.md` that apply to this project." If the answer does not mention SwiftAI Boilerplate Pro modules and build commands, restart the agent from the repository root.
  </Step>
</Steps>

<Tip>
  The auto-loaded entry point is the root `AGENTS.md`, which references `docs/CLAUDE.md`. The other files under `docs/` are human-readable guides and deeper references.
</Tip>

***

## Recommended Skills

You can install community skills to extend Claude's iOS knowledge. Installation methods differ by skill:

* Commands that start with `/plugin` run inside **Claude Code or Claude Agent chat**.
* Commands that start with `git`, `cp`, or `npx` run in your **terminal**.

<CardGroup>
  <Card title="Apple Platform Skills" icon="apple">
    Apple platform conventions, Xcode project structure, SwiftUI, App Store review awareness, and platform-idiomatic patterns.

    **Run in terminal:**

    ```bash theme={null}
    git clone https://github.com/rshankras/claude-code-apple-skills.git
    mkdir -p .claude/skills
    cp -R claude-code-apple-skills/skills/* .claude/skills/
    ```

    **Source:** [rshankras/claude-code-apple-skills](https://github.com/rshankras/claude-code-apple-skills)
  </Card>

  <Card title="iOS Simulator" icon="mobile">
    Lets Claude boot, build, install, and interact with the iOS Simulator directly. Your AI can run and test the app it builds.

    **Run in Claude chat:**

    ```text theme={null}
    /plugin marketplace add conorluddy/ios-simulator-skill
    /plugin install ios-simulator-skill@conorluddy
    ```

    **Source:** [conorluddy/ios-simulator-skill](https://github.com/conorluddy/ios-simulator-skill)
  </Card>

  <Card title="SwiftUI Best Practices" icon="paintbrush">
    State management (`@State`, `@Binding`, `@Observable`), view architecture, performance, accessibility, animations, and Liquid Glass (iOS 26).

    **Run in terminal:**

    ```bash theme={null}
    npx skills add AvdLee/SwiftUI-Agent-Skill --all
    ```

    **Source:** [AvdLee/SwiftUI-Agent-Skill](https://github.com/AvdLee/SwiftUI-Agent-Skill)
  </Card>
</CardGroup>

<Note>
  The boilerplate works without community skills. They are optional additions on top of the included `AGENTS.md` and `docs/CLAUDE.md`, and community repositories may change their install commands over time.
</Note>

<Info>
  **App Generator is a separate product (coming soon).** The agentic workflow on this page uses *your own* coding-agent CLI on the boilerplate source. The App Generator is a standalone macOS tool that drives your agent CLI to scaffold a differentiated app from the template; it ships separately and is not bundled with the boilerplate. See [License & Updates](/pages/reference/license) for editions and availability.
</Info>

***

## Skill-Module Mapping

Which skills help most when working on each boilerplate module:

| Module                    | Best Skills                                   | Why                                                    |
| ------------------------- | --------------------------------------------- | ------------------------------------------------------ |
| **FeatureChat**           | SwiftUI Best Practices, iOS Simulator         | View architecture, state management, simulator testing |
| **Auth**                  | Apple Platform Skills                         | App Store guidelines, security                         |
| **Payments**              | Apple Platform Skills                         | In-app purchase compliance                             |
| **AI**                    | SwiftUI Best Practices                        | Async/await, streaming patterns                        |
| **Storage**               | SwiftUI Best Practices                        | SwiftData best practices                               |
| **DesignSystem**          | SwiftUI Best Practices, Apple Platform Skills | Accessibility, theming                                 |
| **Rating prompt feature** | Apple Platform Skills                         | SKStoreReviewController guidelines                     |
| **Localization**          | Apple Platform Skills, SwiftUI Best Practices | L10n, VoiceOver                                        |

***

## Further Reading

* **[AI-Assisted Development](/pages/guides/ai-assisted-development)**: Cursor and Bolt AI configurations


# Supabase Setup
Source: https://docs.swiftaiboilerplate.com/pages/guides/supabase-setup

Complete guide to setting up Supabase for authentication, database, and AI proxy.

<Info>
  **Find complete step-by-step guide in your project:** [Supabase.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/integrations/Supabase.md)
</Info>

## What You'll Set Up

<CardGroup>
  <Card title="Authentication" icon="shield">
    Email/password and Apple Sign In authentication
  </Card>

  <Card title="AI Proxy" icon="brain">
    Secure Edge Function for OpenRouter API calls
  </Card>
</CardGroup>

## Prerequisites

* [Supabase account](https://supabase.com) (free tier available)
* [OpenRouter account](https://openrouter.ai) (pay-as-you-go)
* Supabase CLI installed:
  ```bash theme={null}
  brew install supabase/tap/supabase
  # or: npm install -g supabase
  ```

## Step-by-Step Setup

<Steps>
  <Step title="Step 1: Open Project Settings">
    Go to Supabase dashboard and navigate to **Project Settings**.

    This is where you'll find all the credentials needed to connect your Swift app.
  </Step>

  <Step title="Step 2: Find Your API Keys">
    Find the **API Keys** tab on the left menu, then copy your **anon-public key**.

    <Note>
      This is a public key that's safe to include in your iOS app bundle.
    </Note>
  </Step>

  <Step title="Step 3: Copy Your Project ID">
    Write down your project ID. The easiest way is usually copying it from the address bar of your browser.

    ```text theme={null}
    https://supabase.com/dashboard/project/YOUR_PROJECT_ID
    ```
  </Step>

  <Step title="Step 4: Add to Secrets.xcconfig">
    Open `Config/Secrets.xcconfig` in Xcode and add your credentials:

    ```text theme={null}
    SUPABASE_URL = https://YOUR_PROJECT_ID.supabase.co
    SUPABASE_ANON_KEY = your-anon-public-key
    ```

    <Warning>
      The Secrets.xcconfig file must be under the **Config** folder in your project root.
    </Warning>
  </Step>

  <Step title="Step 5: Login to Supabase CLI">
    Open Terminal, navigate to your repo, and login to Supabase:

    ```bash theme={null}
    cd ~/path-to-your-repo
    supabase login
    ```

    Follow the instructions (press Enter to open browser and login).
  </Step>

  <Step title="Step 6: Link Your Project">
    Link your project to your repo:

    ```bash theme={null}
    supabase link --project-ref YOUR_PROJECT_ID
    ```
  </Step>

  <Step title="Step 7: Create Generated Directory">
    Create the generated directory for your configuration file:

    ```bash theme={null}
    mkdir -p "SwiftAIBoilerplatePro/Generated"
    ```

    <Note>
      If you renamed the app target folder, replace `SwiftAIBoilerplatePro` with your actual app folder name.
    </Note>
  </Step>

  <Step title="Step 8: Run Update Config Script">
    Run the update config script to generate your Swift configuration file:

    ```bash theme={null}
    bash scripts/update-config.sh
    ```

    This generates a new Swift file including your public keys. It is safe to have this in the bundle.
  </Step>

  <Step title="Step 9: Disable Email Confirmation (Development)">
    For ease of development, temporarily disable the **Confirm email** option from Supabase:

    1. Go to **Authentication** → **Providers** → **Email**
    2. Disable **Confirm email**

    <Warning>
      Remember to re-enable this before production launch if you want email verification.
    </Warning>
  </Step>
</Steps>

## What You Get

After setup:

* ✅ Real email/password authentication
* ✅ Sign in with Apple working
* ✅ Secure session management with auto-refresh
* ✅ Production-ready backend

## Continue Setup

After completing Supabase setup, continue with:

<CardGroup>
  <Card title="OpenRouter Setup" icon="brain" href="/pages/guides/deployment#openrouter-setup">
    Deploy AI Edge Function
  </Card>

  <Card title="RevenueCat Setup" icon="dollar" href="/pages/guides/revenuecat-setup">
    Configure subscriptions
  </Card>
</CardGroup>

## Related Guides

<CardGroup>
  <Card title="Chat Sync" icon="cloud" href="/pages/guides/chat-sync">
    Optional: Sync conversations across devices
  </Card>

  <Card title="Profile Photos" icon="image" href="/pages/guides/profile-photos">
    Optional: Cloud photo storage
  </Card>

  <Card title="Building Your App" icon="hammer" href="/pages/guides/building-your-app">
    Complete customization guide
  </Card>

  <Card title="Authentication Module" icon="lock" href="/pages/modules/auth">
    Technical documentation
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication not working">
    * Verify SUPABASE\_URL and SUPABASE\_ANON\_KEY are correct
    * Run `bash scripts/update-config.sh` again
    * Clean and rebuild in Xcode (⌘⇧K then ⌘B)
  </Accordion>

  <Accordion title="Configuration.swift not generated">
    * Make sure you created the Generated directory
    * Check the path matches your project structure
    * Run the update-config script from the project root
  </Accordion>

  <Accordion title="CLI login fails">
    * Make sure you have Supabase CLI installed
    * Try `supabase logout` then `supabase login` again
    * Check your internet connection
  </Accordion>
</AccordionGroup>

## Need Help?

* 📖 Check the troubleshooting section above
* 💬 [Create an issue](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/issues)
* 🔍 Search [Supabase docs](https://supabase.com/docs)


# Testing Guide
Source: https://docs.swiftaiboilerplate.com/pages/guides/testing

Run the full ~598-test suite in one pass, write tests, and measure coverage

The v2.2.0 boilerplate ships with roughly 598 tests that all run in a single pass through `Boilerplate.xctestplan`. One `xcodebuild test` against the `SwiftAIBoilerplatePro` scheme exercises every package test target plus the app's unit and UI suites.

<Info>
  **Complete testing strategy in your project:** [TestingStrategy.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/foundations/TestingStrategy.md)
</Info>

## Test Suite Overview

`Boilerplate.xctestplan` wires up 14 test targets: the 12 package test targets and the app's two targets.

<CardGroup>
  <Card title="12 package test targets" icon="cube">
    `CoreTests`, `TestSupportTests`, `NetworkingTests`, `StorageTests`, `AuthTests`, `DesignSystemTests`, `FeatureChatTests`, `FeatureRatingTests`, `FeatureSettingsTests`, `PaymentsTests`, `LocalizationTests`, `AITests`
  </Card>

  <Card title="App test suites" icon="mobile">
    `SwiftAIBoilerplateProTests` (unit + integration) and `SwiftAIBoilerplateProUITests` (end-to-end XCUITest flows)
  </Card>
</CardGroup>

<Note>
  `TestSupport` is the v2.2 test-infrastructure package (it exposes `URLProtocolStub` for network stubbing). It is not one of the 11 reusable product packages — it exists only to support the test targets.
</Note>

**Total: \~598 tests, one test-plan run.**

## Run Tests

<Tabs>
  <Tab title="Xcode">
    ```text theme={null}
    # Run the whole test plan
    ⌘ + U

    # Run a single test — click the diamond next to the test function
    # Run a test class — click the diamond next to the class name
    ```
  </Tab>

  <Tab title="Command Line">
    ```bash theme={null}
    # Whole workspace via the test plan
    xcodebuild test \
      -scheme SwiftAIBoilerplatePro \
      -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2'

    # Convenience wrapper with a coverage report
    ./scripts/run-tests.sh --coverage --open

    # A single package (runs `swift test` inside Packages/<name>)
    ./scripts/run-tests.sh --package Core --coverage
    ```
  </Tab>
</Tabs>

<Note>
  The repo targets the **iPhone 17 Pro, OS=26.2** simulator (the destination CI uses). `scripts/run-tests.sh` itself drives the app test target on **iPhone 16, OS=18.6** to exercise the pre-iOS-26 `SAIGlass` Material fallback — pass any installed destination by editing the script's `DESTINATION` if your simulators differ.
</Note>

## Coverage

Coverage is measured with `xccov`, not asserted per module. `scripts/run-tests.sh --coverage` writes `coverage-report.txt` and an HTML report, and warns (does not fail) if overall app coverage drops below its local `COVERAGE_THRESHOLD` of 85%.

CI enforces a separate **product-coverage floor of 25%** (`MINIMUM_COVERAGE` in `.github/workflows/ci.yml`). It computes coverage over product targets only — test targets and vendored dependencies (`SnapshotTesting`, `InlineSnapshotTesting`, `OneSignal`) are excluded so they don't deflate the number.

## Writing Tests

The packages use XCTest with protocol-based fakes. The patterns below mirror the suites that ship in the repo.

### Unit Test Example

`ChatViewModel` is constructed with `conversationID`, a `MessageRepository`, and an `LLMClient`. You set `inputText` and call `send()`. Tests inject `FakeMessageRepository` and `FakeLLMClient` (from `FeatureChatTests`).

```swift theme={null}
@MainActor
final class ChatViewModelTests: XCTestCase {
    func testSendAppendsUserMessage() async {
        // Arrange
        let fakeRepo = FakeMessageRepository()
        let fakeLLM = FakeLLMClient(chunks: ["Hello", " ", "world"])
        let viewModel = ChatViewModel(
            conversationID: UUID(),
            messageRepository: fakeRepo,
            llmClient: fakeLLM
        )

        // Act
        viewModel.inputText = "Hello, AI!"
        await viewModel.send()

        // Assert — the user message landed and the input cleared
        let userMessages = viewModel.messages.filter { $0.role == .user }
        XCTAssertEqual(userMessages.count, 1)
        XCTAssertEqual(viewModel.inputText, "")
    }
}
```

### Integration Test Example

`CompositionRootTests` wires the real `CompositionRoot` with test configs and asserts the dependency graph is built.

```swift theme={null}
@MainActor
final class CompositionRootTests: XCTestCase {
    func testGraphIsWired() throws {
        let authConfig = AuthConfig(
            supabaseURL: try XCTUnwrap(URL(string: "https://test.supabase.co")),
            supabaseAnonKey: "test_anon_key"
        )
        let paymentsConfig = PaymentsConfig(
            apiKey: "test_api_key",
            entitlementID: "test_entitlement"
        )

        let composition = try CompositionRoot(
            authConfig: authConfig,
            paymentsConfig: paymentsConfig
        )

        XCTAssertNotNil(composition.httpClient)
        XCTAssertNotNil(composition.sessionManager)
        XCTAssertNotNil(composition.makeChatViewModel(conversationID: UUID()))
    }
}
```

### UI Test Example

UI tests set `UI_TESTING=1` in the launch environment so the app skips the first-launch onboarding/permission prompts that would otherwise block automation. They drive the app by its real accessibility labels.

```swift theme={null}
func testChatFlow() throws {
    let app = XCUIApplication()
    app.launchEnvironment["UI_TESTING"] = "1"
    app.launch()

    app.buttons["Debug: Mock Sign In"].tap()
    app.tabBars.buttons["Chat"].tap()
    app.buttons["New Chat"].firstMatch.tap()

    let input = app.textFields["Type a message..."]
    input.tap()
    input.typeText("Hello, test message")
    app.buttons["Send"].tap()

    XCTAssertTrue(app.staticTexts["Hello, test message"].waitForExistence(timeout: 5))
}
```

## CI/CD Integration

`.github/workflows/ci.yml` runs on every push to `main`/`develop` and on pull requests targeting those branches. Its jobs:

* **Build & Test (iOS 26.2)** — builds and runs the full test plan on iPhone 17 Pro / iOS 26.2 with coverage, then enforces the 25% product-coverage floor.
* **Build & Test (iOS 18.6 fallback path)** — `test-ios18-fallback` rebuilds and runs the suite on iPhone 16 Pro / iOS 18.6 to prove the `SAIGlass` Material fallback still compiles and passes on pre-iOS-26 simulators. No coverage gate — it catches fallback-path regressions only.
* **Template Manifest** — validates `template.manifest.json` via `scripts/validate-template-manifest.sh`.
* **Secret Scan** — Gitleaks over the full history.
* **SwiftLint** — `swiftlint lint --strict`.

### Coverage Reports

* The iOS 26.2 job posts a coverage summary as a PR comment.
* `.github/workflows/coverage-report.yml` runs weekly (Mondays 09:00 UTC) and on demand, producing a detailed report and opening a GitHub issue if any module falls below the 25% threshold.
* `scripts/run-tests.sh --coverage --open` generates a local HTML breakdown.

## Test Organization

```text theme={null}
Boilerplate.xctestplan
├── App targets
│   ├── SwiftAIBoilerplateProTests      # unit + integration (CompositionRoot, proxy, paywall)
│   └── SwiftAIBoilerplateProUITests    # XCUITest end-to-end flows (auth, chat, settings)
│
└── Package test targets (12)
    ├── CoreTests
    ├── TestSupportTests
    ├── NetworkingTests
    ├── StorageTests
    ├── AuthTests
    ├── DesignSystemTests
    ├── FeatureChatTests
    ├── FeatureRatingTests
    ├── FeatureSettingsTests
    ├── PaymentsTests
    ├── LocalizationTests
    └── AITests
```

## Best Practices

<AccordionGroup>
  <Accordion title="What to Test">
    **Do test:**

    * ✅ ViewModels (business logic)
    * ✅ Repositories (data access)
    * ✅ Clients (external services)
    * ✅ Error scenarios
    * ✅ Edge cases

    **Don't test:**

    * ❌ SwiftUI Views (snapshot instead)
    * ❌ Third-party libraries
    * ❌ Framework code
  </Accordion>

  <Accordion title="Test Structure">
    * Use Arrange-Act-Assert pattern
    * One assertion per test (when possible)
    * Clear test names (testSendMessage\_WhenOffline\_ShowsError)
    * Mock external dependencies
    * Test in isolation
  </Accordion>

  <Accordion title="Mock Guidelines">
    * Protocol-based mocking
    * Track call counts
    * Configurable behavior
    * Avoid over-mocking
    * Use real objects when simple
  </Accordion>
</AccordionGroup>

## Coverage Measurement

```bash theme={null}
# Generate the local HTML report and open it
./scripts/run-tests.sh --coverage --open

# Coverage for one package only
./scripts/run-tests.sh --package Core --coverage
```

The local report warns below 85% app coverage; CI gates only the 25% product-coverage floor described under [CI/CD Integration](#cicd-integration).

## View Complete Guide

<Card title="View Complete Testing Guide" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/foundations/TestingStrategy.md">
  Complete guide with examples, patterns, and best practices
</Card>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tests fail on CI but pass locally">
    * Match the CI destination: iPhone 17 Pro, OS=26.2
    * Confirm Xcode 26.2+ (CI selects Xcode 26.2)
    * Clear derived data, then rebuild
    * Look for timing-sensitive async tests
  </Accordion>

  <Accordion title="Coverage lower than expected">
    * Run with `--coverage`
    * Add tests for untested branches and error scenarios
    * Make sure `async` code is actually awaited in the test
  </Accordion>

  <Accordion title="UI tests flaky or stuck on first launch">
    * Set `app.launchEnvironment["UI_TESTING"] = "1"` so the app skips the first-launch onboarding/permission alert that blocks automation
    * Use `waitForExistence(timeout:)` instead of bare `exists`
    * Drive elements by their accessibility labels (e.g. `"Send"`, `"Type a message..."`)
    * Avoid asserting mid-animation
  </Accordion>
</AccordionGroup>


# Welcome to SwiftAI Boilerplate Pro
Source: https://docs.swiftaiboilerplate.com/pages/index

Swift 6 + iOS 26 Liquid Glass iOS boilerplate for AI-powered apps. Streaming chat, Supabase auth, RevenueCat subscriptions, and 11 clean Swift Packages.

**Ship your AI-powered iOS app in days, not months.**

SwiftAI Boilerplate Pro is a production-ready iOS foundation built by an iOS engineer with 10 years of commercial experience, who has shipped multiple production apps. It includes everything you need to build and launch AI chat applications with authentication, subscriptions, and analytics out of the box.

<Note>
  **v2.2.0 is live: the App Store Guideline 4.3(a) playbook** — a Release-binary audit gate plus hardening checklist and prompt packs that fail your build until the app is rebranded and 4.3-safe. Requires Xcode 26.2+. See the [changelog](/pages/reference/changelog) and the [migration guide](/pages/migration/v1-9-to-v2-0).
</Note>

<Note>
  All setup, integration, and publishing steps are explained here on these docs. For customization and design patterns, see the corresponding files under /docs in your project.
</Note>

<Info>
  **App Generator is a separate product (coming soon).** A standalone macOS app that drives your own coding-agent CLI to generate a differentiated, 4.3-safe app from this template — it ships no LLM and is sold separately. Existing and past buyers are grandfathered: lifetime access to all new boilerplate versions (v2.2.0 and beyond, no new charge), plus App Generator access when it ships. See the [license & updates model](/pages/reference/license) for the full breakdown.
</Info>

<Tip>
  **Found an issue or confusing setup step?** Please open a [GitHub issue](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/issues). Include your Xcode version, Swift version, boilerplate tag or branch, the exact error text, and the steps you took so we can reproduce it quickly.
</Tip>

## What You Get

<CardGroup>
  <Card title="App Store 4.3(a) Playbook" icon="shield-check" href="/pages/guides/app-store-4-3-hardening">
    Release-binary audit gate, hardening checklist, and prompt packs that keep your app 4.3-safe
  </Card>

  <Card title="AI-Assisted Development" icon="wand-magic-sparkles" href="/pages/guides/ai-assisted-development">
    Claude Code, Cursor AI, and Bolt AI configurations included
  </Card>

  <Card title="AI Chat" icon="message" href="/pages/modules/ai">
    Streaming responses via OpenRouter (500+ models)
  </Card>

  <Card title="Authentication" icon="lock" href="/pages/modules/auth">
    Supabase Auth + Sign in with Apple, ready to go
  </Card>

  <Card title="Subscriptions" icon="credit-card" href="/pages/modules/payments">
    RevenueCat integration with paywall UI
  </Card>

  <Card title="Design System" icon="palette" href="/pages/modules/design-system">
    5 themes, tokens, and components
  </Card>

  <Card title="~598 Tests" icon="flask" href="/pages/guides/testing">
    \~598 tests across 12 package test targets + the app test suites, in one test-plan run
  </Card>
</CardGroup>

## Quick Stats

* **275+ hours** of development already done
* **\~598 tests** across 12 package test targets + the app test suites, in one test-plan run
* **11 Swift Packages** cleanly separated for reuse in any iOS project
* **AI-Assisted Development** with Claude Code CLAUDE.md, Cursor AI rules, and Bolt AI chat modes
* **Comprehensive docs** with examples and LLM prompt packs
* **2 chat UIs** (bubble and centered styles)

## Time Saved

<Info>
  This boilerplate typically saves **5-8 weeks** of build time and $20,000-$30,000 in development cost compared to building from scratch.

  Module savings are conservative estimates based on prior builds; your mileage may vary by scope and team experience.
</Info>

See the complete feature breakdown in [Features Reference](/pages/reference/features).

## Get Started in 3 Steps

<Steps>
  <Step title="Installation">
    Clone the repo and run the app with mock backends

    [View Installation Guide →](/pages/installation)
  </Step>

  <Step title="Quick Start">
    Go from zero to a running app in 10 minutes

    [View Quick Start →](/pages/quickstart)
  </Step>

  <Step title="Customize">
    Follow the in-doc customization roadmap, then use the deeper files in your project’s `/docs` folder when you need more detail.

    [View Building Your App →](/pages/guides/building-your-app)
  </Step>
</Steps>

## Production Setup Order

After the mock app runs, use this sequence to connect real services:

| Step | Goal                                    | Guide                                                                                                                                                                            |
| ---- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | Create Supabase project and secrets     | [Supabase Setup](/pages/guides/supabase-setup)                                                                                                                                   |
| 2    | Configure Apple, Google, and email auth | [Authentication Guide](/pages/guides/authentication)                                                                                                                             |
| 3    | Deploy the OpenRouter AI proxy          | [Deployment Guide](/pages/guides/deployment#openrouter-setup)                                                                                                                    |
| 4    | Set up subscriptions and entitlements   | [RevenueCat Setup](/pages/guides/revenuecat-setup)                                                                                                                               |
| 5    | Add optional services                   | [Crashlytics](/pages/guides/crashlytics-setup), [OneSignal](/pages/guides/onesignal-setup), [Chat Sync](/pages/guides/chat-sync), [Profile Photos](/pages/guides/profile-photos) |
| 6    | Prepare App Store submission            | [App Store 4.3 Hardening](/pages/guides/app-store-4-3-hardening)                                                                                                                 |

## Architecture Overview

Built with modern iOS development best practices:

* **Swift 6 strict concurrency** - `@MainActor`, `@Observable`, explicit `any`, Sendable boundaries
* **iOS 26 Liquid Glass** - `SAIGlass` primitive with automatic Material fallback on iOS 17–25
* **MVVM Architecture** - Clean separation of concerns
* **Dependency Injection** - CompositionRoot pattern
* **Protocol-Oriented** - Swappable implementations
* **SwiftData** - Modern persistence (iOS 17+)

[Learn about the architecture →](/pages/architecture)

## Foundation Modules

<CardGroup>
  <Card title="Core" icon="cube" href="/pages/modules/core">
    Error handling, logging, utilities

    **Saves: 6–10 hrs**
  </Card>

  <Card title="Networking" icon="wifi" href="/pages/modules/networking">
    HTTP client with interceptors

    **Saves: 12-20 hrs**
  </Card>

  <Card title="Storage" icon="database" href="/pages/modules/storage">
    SwiftData + Keychain + Cloud sync

    **Saves: 16-24 hrs**
  </Card>

  <Card title="Auth" icon="shield" href="/pages/modules/auth">
    Supabase + Apple + Google + Email

    **Saves: 20-32 hrs**
  </Card>

  <Card title="Subscriptions" icon="dollar" href="/pages/modules/payments">
    RevenueCat subscriptions

    **Saves: 16-24 hrs**
  </Card>

  <Card title="AI" icon="brain" href="/pages/modules/ai">
    LLM client with streaming

    **Saves: 24-40 hrs**
  </Card>

  <Card title="Feature Chat" icon="comments" href="/pages/modules/feature-chat">
    Complete chat UI (2 styles)

    **Saves: 40-60 hrs**
  </Card>

  <Card title="Settings" icon="gear" href="/pages/modules/feature-settings">
    Settings + Paywall UI

    **Saves: 12-16 hrs**
  </Card>

  <Card title="Design System" icon="swatchbook" href="/pages/modules/design-system">
    Design tokens, 5 themes, and components

    **Saves: 20-32 hrs**
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Install" icon="download" href="/pages/installation">
    Get the boilerplate running locally
  </Card>

  <Card title="Quick Start" icon="bolt" href="/pages/quickstart">
    10-minute guide to first run
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    Understand the system design
  </Card>

  <Card title="Build Your App" icon="hammer" href="/pages/guides/building-your-app">
    Complete customization guide
  </Card>
</CardGroup>

## Need Help?

* [Complete Documentation Hub](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/INDEX.md)
* [GitHub Issues](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/issues)
* Use the built-in [CLAUDE.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/CLAUDE.md) guide for AI-assisted development


# Installation
Source: https://docs.swiftaiboilerplate.com/pages/installation

Get the boilerplate running in **under 10 minutes**.

## Prerequisites

Before starting, ensure you have:

* **macOS 15+ with Xcode 26.2+**. v2.2.0 uses the iOS 26 SDK to compile Liquid Glass APIs (`Glass`, `glassEffect`, `GlassEffectContainer`). Runtime still supports iOS 17+ via a SwiftUI `Material` fallback built into `SAIGlass`.
* Swift 6.0 toolchain (bundled with Xcode 26.2+)
* Git installed

<Note>
  No backend setup required for initial run. The app includes mock backends for immediate development.
</Note>

<Warning>
  **Using older Xcode?** Stay on the [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0) tag until you can upgrade. v2.0 and later use iOS 26 SDK symbols that older toolchains cannot compile, regardless of `#available` checks.
</Warning>

## Step 1: Get the Repository

You have three options to access the boilerplate:

<Tabs>
  <Tab title="Clone (Recommended)">
    Clone the repository to get started immediately with easy updates:

    ```bash theme={null}
    git clone https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution.git
    cd SwiftAIBoilerplatePro-Distribution
    ```

    Pull updates anytime with `git pull`.
  </Tab>

  <Tab title="Fork">
    Fork the repository to your own GitHub account for full control:

    1. Click **Fork** on the repository page
    2. Clone your fork:

    ```bash theme={null}
    git clone https://github.com/YOUR_USERNAME/SwiftAIBoilerplatePro-Distribution.git
    cd SwiftAIBoilerplatePro-Distribution
    ```

    Sync upstream updates when needed.
  </Tab>

  <Tab title="Download ZIP">
    Download directly without Git:

    1. Go to the repository page
    2. Click **Code** → **Download ZIP**
    3. Extract and open in Xcode
  </Tab>
</Tabs>

<Warning>
  **Keep it private!** All forks and copies must remain in **private repositories**. Do not make your fork public or share the boilerplate code publicly. This protects the code and your [license](/pages/reference/license).
</Warning>

## Step 1.1: Version Control Safely

If you cloned the boilerplate, do not push your app changes back to the boilerplate repository. The safest workflow is to keep two Git remotes:

* `upstream`: the original SwiftAI Boilerplate Pro repository, used only to pull future boilerplate updates
* `origin`: your private repository, used for your app's code

<Steps>
  <Step title="Rename the boilerplate remote to upstream">
    After cloning, Git names the boilerplate repository `origin`. Rename it so normal pushes do not go back to the boilerplate source.

    ```bash theme={null}
    git remote rename origin upstream
    git remote -v
    ```
  </Step>

  <Step title="Create an empty private repository">
    In GitHub, GitLab, or Bitbucket, create a new **private** repository for your app. Do not initialize it with a README, license, or `.gitignore` because the boilerplate already includes project files.
  </Step>

  <Step title="Add your private repository as origin">
    Replace the URL with your private repository URL:

    ```bash theme={null}
    git remote add origin https://github.com/YOUR_USERNAME/YOUR_PRIVATE_REPO.git
    ```
  </Step>

  <Step title="Push your first private copy">
    Most projects use `main`. If your local branch is named `master`, replace `main` with `master`.

    ```bash theme={null}
    git push -u origin main
    ```
  </Step>
</Steps>

### Daily Git Workflow

After setup, your normal commits go to your private repository:

```bash theme={null}
git add .
git commit -m "Add my custom feature"
git push
```

### Pull Boilerplate Updates Later

When a new boilerplate version ships, pull it from `upstream` and then push the merged result to your private `origin`:

```bash theme={null}
git fetch upstream
git merge upstream/main
git push
```

<Note>
  Future-version access depends on your tier. The **$199 lifetime license** includes all future versions and updates; the **$99 single download** is a current-version snapshot only. Existing buyers keep lifetime access (and get App Generator access when it ships). See [License & updates](/pages/reference/license).
</Note>

### Handling Merge Conflicts

Merge conflicts can happen when you and the boilerplate both changed the same lines. Git will pause the merge and mark the files with conflict markers:

```text theme={null}
<<<<<<< HEAD
your app changes
=======
new boilerplate changes
>>>>>>> upstream/main
```

Open each conflicted file, keep the final code you want, delete the marker lines, then finish the merge:

```bash theme={null}
git status
git add .
git commit -m "Resolve upstream merge conflicts"
git push
```

<Tip>
  Keep custom app code in your private `origin`. Use `upstream` only for reading and merging official boilerplate updates.
</Tip>

## Step 2: Open in Xcode

```bash theme={null}
open SwiftAIBoilerplatePro.xcodeproj
```

<Tip>
  The project uses Swift Package Manager. Xcode will automatically resolve dependencies on first open (takes \~30 seconds).
</Tip>

<Tip>
  If you use `xcodes` or `asdf-xcode`, the repo pins `26.3` via `.xcode-version`. Run `xcodes install` (or `asdf install xcode`) inside the repo to match.
</Tip>

## Step 3: Configure Environment (Optional)

**For immediate testing:** You can skip this step! The app runs with mock services out of the box.

**For production services:**

1. **Copy the config template:**

```bash theme={null}
cp Config/Secrets.example.xcconfig Config/Secrets.xcconfig
```

2. **Fill in your API keys** in `Config/Secrets.xcconfig`

3. **IMPORTANT - Update configuration:**

```bash theme={null}
bash scripts/update-config.sh
```

<Warning>
  Every time you change `Config/Secrets.xcconfig`, you **must** run `bash scripts/update-config.sh` and rebuild. This is **not automatic**.
</Warning>

<Info>
  **For immediate testing**, you can leave the default placeholder values! The app will use:

  * `MockAuthClient` (no Supabase needed)
  * `EchoLLMClient` (echoes messages back)
  * No payment functionality
</Info>

## Step 4: Build and Run

Press **⌘ + R** in Xcode or:

```bash theme={null}
xcodebuild -scheme SwiftAIBoilerplatePro \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2'
```

## What You'll See

On first run, the app will:

1. **Show onboarding** - 3 swipeable pages
2. **Display sign-in** - Use any email/password (mock auth)
3. **Home screen** - Feature cards and quick actions
4. **Chat works!** - Send messages, get echo responses
5. **Settings screen** - Explore different themes

<Check>
  If you see the home screen, you're all set! The app is running with mock backends.
</Check>

## Project Structure

```text theme={null}
SwiftAIBoilerplatePro/
├── SwiftAIBoilerplatePro/        # Main app
│   ├── AppShell/                  # UI screens
│   ├── Composition/               # DI container (LLMClientFactory, etc.)
│   ├── Generated/                 # Configuration.swift (from update-config.sh)
│   └── Resources/                 # Assets
├── Packages/                      # 11 reusable Swift packages + TestSupport
│   ├── Core/                      # Foundation
│   ├── Networking/                # HTTP client
│   ├── Storage/                   # SwiftData
│   ├── Auth/                      # Authentication
│   ├── Payments/                  # Subscriptions
│   ├── AI/                        # LLM client (re-exports FeatureChat)
│   ├── FeatureChat/               # Chat UI (owns LLMClient/LLMMessage)
│   ├── FeatureRating/             # In-app review prompts
│   ├── FeatureSettings/           # Settings
│   ├── Localization/              # Strings + AppError.localizedUserMessage
│   ├── DesignSystem/              # UI components (SAIGlass)
│   └── TestSupport/               # Test-only infra (URLProtocolStub), v2.2
├── Config/                        # Build configuration
│   ├── App.xcconfig               # APP_BUNDLE_ID, SWIFT_VERSION, deployment target
│   └── Secrets.xcconfig           # Your API keys
├── Boilerplate.xctestplan         # Single workspace test plan
└── supabase/                      # Backend (optional)
    └── functions/ai/              # AI proxy → OpenRouter
```

## Mock vs Production Mode

### Mock Mode (Default)

Perfect for:

* ✅ Rapid initial development
* ✅ UI testing without setup
* ✅ Exploring the codebase
* ✅ Avoiding API or subscription costs

**What's mocked:**

* Authentication (any email works)
* AI responses (echoed locally)
* Payments (simulated states)

### Production Mode

When you're ready to go live, switching to Production Mode is seamless.
This boilerplate is designed so you can move from mock data to real users and APIs in just a few setup steps, all clearly documented.

Required when you need:

* Real user authentication (via Supabase)
* Actual AI responses
* Working subscriptions and payments

<Warning>
  To complete the backend setup see [Quick Start](/pages/quickstart) or [Setup Guides](/pages/guides/supabase-setup).
</Warning>

## Verify Installation

<Steps>
  <Step title="App Builds">
    No build errors in Xcode
  </Step>

  <Step title="Tests Pass">
    Run tests with **⌘ + U**. One pass of `Boilerplate.xctestplan` runs \~598 tests across 12 package test targets + the app test suites — all should pass.
  </Step>

  <Step title="UI Works">
    Navigate through onboarding → sign in → home → chat
  </Step>
</Steps>

## Common Issues

### Dependencies Won't Resolve

**Solution:**

```bash theme={null}
# In Xcode
File → Packages → Reset Package Caches
File → Packages → Update to Latest Package Versions
```

### Missing Config File

**Error:** `Config/Secrets.xcconfig not found`

**Solution:**

```bash theme={null}
cp Config/Secrets.example.xcconfig Config/Secrets.xcconfig
```

### Build Errors

**Solution:**

```bash theme={null}
# Clean build
⌘ + Shift + K

# Or from terminal
xcodebuild clean
```

## Next Steps

<CardGroup>
  <Card title="Quick Start" icon="bolt" href="/pages/quickstart">
    Get to your first running app
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    Understand the system design
  </Card>

  <Card title="Build Your App" icon="hammer" href="/pages/guides/building-your-app">
    Complete customization guide
  </Card>

  <Card title="Setup Backends" icon="server" href="/pages/guides/supabase-setup">
    Connect real services
  </Card>
</CardGroup>

## Development Tips

<Tip>
  **Using AI assistants?** Check out [CLAUDE.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/CLAUDE.md) for guidelines on AI-assisted development.
</Tip>

<Info>
  **Want to customize immediately?** Read the [Building Your App guide](/pages/guides/building-your-app) which includes ready-to-use LLM prompts for common tasks.
</Info>


# Upgrading from v1.9 to v2.0
Source: https://docs.swiftaiboilerplate.com/pages/migration/v1-9-to-v2-0

The full migration path for Swift 6, iOS 26 Liquid Glass, and the v2.0 architecture refactor.

v2.0 is the Swift 6 and iOS 26 Liquid Glass release. It changes the toolchain floor, ships a new Liquid Glass primitive, and splits oversized files into ≤ 400-line extension siblings. Most downstream apps upgrade in under an hour.

<Info>
  **Canonical release notes:** [`RELEASE_NOTES.md`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/RELEASE_NOTES.md) in the boilerplate repo. This guide is the step-by-step version.
</Info>

## 1. Toolchain

v2.0 uses iOS 26 SDK symbols (`Glass`, `glassEffect`, `GlassEffectContainer`) that older toolchains cannot compile, regardless of `#available` checks.

**Required:**

* macOS 15+
* Xcode 26.2+ (Swift 6.0)
* iOS 17+ runtime (unchanged)

**The repo pins `26.3` via `.xcode-version`.** If you use `xcodes` or `asdf-xcode`, run `xcodes install` (or `asdf install xcode`) inside the repo to match.

<Warning>
  **Stuck on older Xcode?** Pin your build to [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0) until you can upgrade. There is no forward-compatible fallback; the iOS 26 SDK is required to compile.
</Warning>

## 2. Apply the Supabase migration

v2.0 ships a new SQL migration that fixes an authorization (IDOR) gap in the `get_conversation_with_stats` function — it was `SECURITY DEFINER` with no `auth.uid()` ownership check, so any authenticated user could read any conversation by UUID.

```bash theme={null}
# From the repo root
supabase migration up
```

Or run the file directly:

```bash theme={null}
psql "$SUPABASE_DB_URL" \
  -f supabase/migrations/20260408000000_fix_conversation_stats_auth.sql
```

## 3. Redeploy the `ai` edge function

The Edge Function was updated alongside the migration. Redeploy it so the new version picks up the fix:

```bash theme={null}
supabase functions deploy ai
```

## 4. Install the secrets pre-commit hook

v2.0 ships a pre-commit hook that blocks accidental secret commits (the hook lives in `.githooks/`). Enable it once per clone:

```bash theme={null}
git config core.hooksPath .githooks
```

This is a one-time, per-clone setting. It is not picked up automatically.

## 5. Reapply downstream customisations

A lot of oversized files were split into extension siblings to stay under the new ≤ 400-line rule. Public entry points are unchanged, but if you customised any of these files, your edits may now belong in a subview or sibling file.

| Touched in v1.9         | Where the content lives now                                                       |
| ----------------------- | --------------------------------------------------------------------------------- |
| `ProfileView.swift`     | `AppShell/Profile/*.swift` (composition root + section files)                     |
| `SettingsView.swift`    | `FeatureSettings/Views/Settings/*.swift` (≤ 125-line root + one file per section) |
| `EmailSignUpView.swift` | `AppShell/Auth/EmailSignUp*.swift`                                                |
| `SessionManager.swift`  | `+SignIn`, `+Refresh`, `+Persistence` extensions                                  |
| `L10n.swift`            | `L10n+<Namespace>.swift` per nested enum                                          |
| `ChatViewModel.swift`   | `ChatViewModel+Memory.swift` for history/memory                                   |

Strategy: `git log` the file, find the function you edited, `grep` for it in the new tree, port the change.

## 6. Fighting-glass cleanup

This is the biggest source of visual regressions when upgrading. On iOS 26, SwiftUI handles sheet and container materials for you. If your downstream code piles manual backgrounds on top, you block the Material SwiftUI already provides and you fight Liquid Glass on iOS 26.

**Remove these patterns from your own views:**

* `.background(DSColors.background)` on SwiftUI containers (`NavigationStack`, `Form`, `List`, sheets, `TabView`).
* `DSColors.background.ignoresSafeArea()` stacked under sheets or full-screen covers.
* `.background(.black)` or `.background(Color.clear)` under `.presentationBackground` on sheets.
* `.scrollContentBackground(.hidden)` on forms that already use `.formStyle(.grouped)`. `.grouped` already does the right thing on iOS 26.
* Explicit `.safeAreaInset(edge: .bottom)` gutters under a `TabView`. The tab bar's own inset is already respected.

**Use instead:**

* `.saiGlass(.regular)` when you need glass on a custom view.
* `SAIGlassContainer { ... }` when multiple glass surfaces sit near each other.
* `.saiScrollEdgeGlass(_:)` for scroll-edge treatment under nav and input chrome.
* `.saiTabBarMinimize(.onScrollDown)` if you want iOS 26 tab bar minimisation (it is a no-op on iOS 17–25).

## 7. Paywall CTA theming

Paywall CTAs in v2.0 use the standard system styles:

```swift theme={null}
Button("Upgrade") { ... }
    .buttonStyle(.borderedProminent)

Button("Maybe later") { ... }
    .buttonStyle(.bordered)
```

If you were theming these buttons via `.background()`, **switch to `.tint()`**:

```swift theme={null}
// Before (v1.9)
Button("Upgrade") { ... }
    .background(BrandConfig.accentColor)

// After (v2.0)
Button("Upgrade") { ... }
    .buttonStyle(.borderedProminent)
    .tint(BrandConfig.accentColor)
```

`.tint()` lets the standard button style render the glass-aware surface correctly on iOS 26, and still picks up the correct Material on iOS 17–25.

## Quick verification checklist

After the upgrade, run through this list before shipping:

* [ ] App builds under Xcode 26.2+ with zero Swift 6 warnings.
* [ ] Supabase migration ran cleanly (`supabase migration list` shows `20260408000000_fix_conversation_stats_auth`).
* [ ] The `ai` Edge Function returns a streaming response end-to-end.
* [ ] `git config core.hooksPath` returns `.githooks`.
* [ ] Sheets, paywall, settings, and chat all look right on **iOS 26** (Liquid Glass) and **iOS 17–18** (Material fallback).
* [ ] No remaining `.onReceive(...)` on `ToastCenter` or `DeepLinkBus` in downstream code; migrate to `.onChange(of:)`.
* [ ] No remaining `.background(DSColors.background.ignoresSafeArea())` under containers.

## Related

<CardGroup>
  <Card title="Changelog" icon="list" href="/pages/reference/changelog">
    Full v2.0.0 release entry
  </Card>

  <Card title="Liquid Glass API" icon="gem" href="/pages/modules/design-system#liquid-glass">
    `SAIGlass`, modifiers, container
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    Swift 6 concurrency model + ≤ 400-line rule
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/pages/quickstart#troubleshooting">
    Common upgrade errors and fixes
  </Card>
</CardGroup>


# Accessibility Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/accessibility

Make your iOS app inclusive by default with VoiceOver, Dynamic Type, Reduce Motion, and High Contrast support

Every app deserves to be usable by everyone. The Accessibility module makes building inclusive iOS apps effortless with pre-defined labels, SwiftUI modifiers, and comprehensive support for iOS accessibility features.

<Info>
  **Package location:** `Packages/DesignSystem/Sources/DesignSystem/Accessibility/`
</Info>

## Overview

The Accessibility module is part of the DesignSystem package and provides ready-to-use accessibility features that work with VoiceOver, Dynamic Type, Reduce Motion, and High Contrast modes out of the box.

<CardGroup>
  <Card title="Pre-defined VoiceOver Labels" icon="ear-listen">
    Typed labels for common UI patterns, ready to apply
  </Card>

  <Card title="Dynamic Type" icon="text-size">
    Text scales beautifully with user preferences
  </Card>

  <Card title="Reduce Motion" icon="bolt-slash">
    Respects motion sensitivity settings
  </Card>

  <Card title="High Contrast" icon="circle-half-stroke">
    Colors adapt for better readability
  </Card>
</CardGroup>

## Quick Start

### VoiceOver Labels

One line for full accessibility:

```swift theme={null}
import DesignSystem

// Apply pre-defined accessibility
Button("Send") { }
    .saiAccessible(A11y.Chat.sendButton)
// VoiceOver: "Send message, button. Double tap to send your message."

// Works for all common UI patterns
Image("avatar")
    .saiAccessible(A11y.Profile.photo)
// VoiceOver: "Profile photo. Double tap to change your profile photo."
```

### Dynamic Type Support

Text scales beautifully with user preferences:

```swift theme={null}
Text("Respects user settings")
    .saiScaledFont(size: 18, weight: .semibold, relativeTo: .body)
// Automatically scales with iOS text size settings
// Capped to prevent layout issues at extreme sizes
```

### Reduce Motion

Respects users who experience discomfort with animations:

```swift theme={null}
Button("Animate") { }
    .scaleEffect(isPressed ? 0.95 : 1.0)
    .saiReducedMotionAnimation(.spring())
// Animation plays normally OR instant state change
// Based on user's Reduce Motion setting
```

### High Contrast Mode

Colors adapt automatically for users who need more contrast:

```swift theme={null}
Text("Adapts to user needs")
    .saiContrastAwareForeground(
        normal: DSColors.textSecondary,
        highContrast: DSColors.textPrimary
    )
```

## File Structure

```text theme={null}
Packages/DesignSystem/Sources/DesignSystem/Accessibility/
├── A11y.swift          # Pre-defined labels (A11yLabel + A11y namespaces)
├── A11yModifiers.swift # SwiftUI modifiers (sai* View extensions)
└── A11yAudit.swift     # Debug-only audit overlay + checklist
```

## Pre-Defined Labels

The `A11y` enum groups typed `A11yLabel` values by feature. Use `A11y.<Group>.<label>` directly, or extend the enum with your own (see [Adding Custom Labels](#adding-custom-labels)).

<AccordionGroup>
  <Accordion title="A11y.Chat">
    `sendButton`, `messageInput`, `userMessage`, `assistantMessage`, `newChat`, `historyList`, `copyAction`, `deleteAction`
  </Accordion>

  <Accordion title="A11y.Auth">
    `signInApple`, `signInGoogle`, `emailInput`, `passwordInput`, `signOut`
  </Accordion>

  <Accordion title="A11y.Settings">
    `themeSelector`, `notificationsToggle`, `diagnosticsToggle`, `deleteAccount`
  </Accordion>

  <Accordion title="A11y.Profile">
    `photo`, `displayName`, `editButton`
  </Accordion>

  <Accordion title="A11y.Payments">
    `subscribeButton`, `restoreButton`, `planOption(name:price:)`, `subscriptionStatus(isSubscribed:)`
  </Accordion>

  <Accordion title="A11y.Navigation">
    `back`, `close`, `menu`, `tab(name:selected:)`
  </Accordion>

  <Accordion title="A11y.Common">
    `loading`, `error(message:)`, `success(message:)`, `dismiss`
  </Accordion>
</AccordionGroup>

## Adding Custom Labels

### 1. Define Your Label

```swift theme={null}
extension A11y {
    public enum MyFeature {
        public static let action = A11yLabel(
            label: "Custom action",
            hint: "Double tap to perform custom action"
        )
        
        public static let toggle = A11yLabel(
            label: "Enable feature",
            hint: "Double tap to toggle"
        )
    }
}
```

### 2. Apply to Views

```swift theme={null}
Button("Action") { }
    .saiAccessible(A11y.MyFeature.action)

Toggle("Feature", isOn: $enabled)
    .saiAccessible(A11y.MyFeature.toggle)
```

## SwiftUI Modifiers

### `.saiAccessible(_:)`

Apply a pre-defined accessibility label:

```swift theme={null}
Button("Send") { }
    .saiAccessible(A11y.Chat.sendButton)
```

### `.saiAccessibilityHidden()`

Hide decorative elements from VoiceOver:

```swift theme={null}
Image("background")
    .saiAccessibilityHidden()
```

### `.saiScaledFont(size:weight:relativeTo:)`

Dynamic Type-aware font sizing:

```swift theme={null}
Text("Title")
    .saiScaledFont(size: 24, weight: .bold, relativeTo: .title)
```

### `.saiReducedMotionAnimation(_:)`

Motion-sensitive animation:

```swift theme={null}
.saiReducedMotionAnimation(.spring(response: 0.3))
```

### `.saiContrastAwareForeground(normal:highContrast:)`

High contrast color adaptation:

```swift theme={null}
.saiContrastAwareForeground(
    normal: .secondary,
    highContrast: .primary
)
```

## Debug Tools

### Accessibility Audit Overlay

`accessibilityAuditOverlay(showWarnings:)` is a DEBUG-only modifier that adds a toggle button and a colored-legend overlay to a view during development. It is compiled out of Release builds.

```swift theme={null}
#Preview {
    MainContent()
        .accessibilityAuditOverlay()
}
```

The overlay legend flags:

* Red — critical issues (missing/empty labels, buttons without hints, images without labels, touch targets smaller than 44x44 points, insufficient contrast)
* Yellow — warnings (generic or overly long labels, missing traits, redundant labels)
* Green — accessible

For console output, `A11yAudit.printResults(_:)` prints issue and warning counts, and `A11yChecklist.printChecklist()` prints the manual review checklist.

## Testing Accessibility

### Unit Tests

```swift theme={null}
func testAccessibilityLabels() {
    // label is non-optional; hint is String?
    XCTAssertFalse(A11y.Chat.sendButton.label.isEmpty)
    XCTAssertEqual(A11y.Chat.sendButton.hint, "Double tap to send your message")
}
```

### UI Tests

```swift theme={null}
func testVoiceOverNavigation() throws {
    let app = XCUIApplication()
    app.launch()
    
    // Find the button by its accessibility label
    let sendButton = app.buttons["Send message"]
    XCTAssertTrue(sendButton.exists)
    
    // Verify accessibility hint
    XCTAssertEqual(
        sendButton.label,
        "Send message"
    )
}
```

### Manual Testing

<Steps>
  <Step title="Enable VoiceOver">
    Settings → Accessibility → VoiceOver → On
  </Step>

  <Step title="Navigate your app">
    Swipe right to move through elements
  </Step>

  <Step title="Verify announcements">
    Listen for clear, helpful descriptions
  </Step>

  <Step title="Test Dynamic Type">
    Settings → Display → Text Size → Largest
  </Step>
</Steps>

## Best Practices

<CardGroup>
  <Card title="Label all interactive elements" icon="check">
    Buttons, links, and controls need labels
  </Card>

  <Card title="Hide decorative images" icon="eye-slash">
    Use `.saiAccessibilityHidden()` for backgrounds
  </Card>

  <Card title="Provide meaningful hints" icon="lightbulb">
    Describe what happens when activated
  </Card>

  <Card title="Test with real users" icon="users">
    Accessibility users find issues you miss
  </Card>
</CardGroup>

## Test Coverage

Accessibility helpers are covered through DesignSystem tests and should also be verified manually with VoiceOver, Dynamic Type, Reduce Motion, and high contrast settings on a simulator or device.

## Related

<CardGroup>
  <Card title="Quick Start" href="/pages/quickstart">
    Run the app before auditing accessibility
  </Card>

  <Card title="Architecture" href="/pages/architecture">
    Understand module boundaries
  </Card>

  <Card title="Localization Module" href="/pages/modules/localization">
    Type-safe strings and i18n
  </Card>

  <Card title="Design System" href="/pages/modules/design-system">
    UI tokens and components
  </Card>
</CardGroup>


# AI Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/ai

Production-ready LLM streaming via a Supabase Edge Function → OpenRouter. Server-side keys, model allowlist, and a backend you control.

<Info>
  **Full technical details** in your project at `/docs/modules/AI.md`
</Info>

## What You Get

* ✅ **Proxy architecture** - API keys server-side only (secure)
* ✅ **Streaming SSE** - Real-time token-by-token responses
* ✅ **Config-gated** - Auto-selects Proxy or Echo client from `PROXY_BASE_URL`
* ✅ **OpenRouter backend** - One Edge Function reaches OpenRouter's 500+ models; the shipped function allowlists a small set you expand
* ✅ **Cancellation support** - Stop generation mid-stream (structured-concurrency cancellation)
* ✅ **Echo fallback** - Test UI without API costs

**Time saved: 24-40 hours** of implementing streaming, proxy setup, error handling, and testing.

<Note>
  **Module coupling.** The `LLMClient` protocol and `LLMMessage` type live in the **FeatureChat**
  package, and the **AI** package re-exports FeatureChat (`@_exported import FeatureChat`). If you
  remove chat, move these two types first or `Packages/AI` will not compile. See
  [App Store 4.3 hardening](/pages/guides/app-store-4-3-hardening) for the per-module removal steps.
</Note>

## What's new in v2.2

* `ProxyLLMClient`'s public API is unchanged. The request builder and SSE stream parser are standalone files under `Sources/AI/Clients/Proxy/`, so you can swap the wire format without rewriting the client.
* Swift 6 strict concurrency throughout: protocol-typed properties use explicit `any`.

## Key Components

### LLMClient Protocol

The protocol is defined in **FeatureChat** (re-exported by the AI package). It has a single
requirement that takes just the conversation history:

```swift theme={null}
public protocol LLMClient: Sendable {
    func streamResponse(messages: [LLMMessage]) -> AsyncThrowingStream<String, Error>
}
```

`ProxyLLMClient` additionally offers a fully-parameterised overload with `model:` and
`temperature:` (the protocol method forwards to it with `nil` defaults):

```swift theme={null}
public func streamResponse(
    messages: [LLMMessage],
    model: String? = nil,
    temperature: Double? = nil
) -> AsyncThrowingStream<String, Error>
```

`LLMMessage` is a simple value type — `role` is a `String` (`"user"`, `"assistant"`, `"system"`),
not an enum:

```swift theme={null}
public struct LLMMessage: Sendable, Equatable {
    public let role: String   // "user" | "assistant" | "system"
    public let content: String
}
```

## Production Setup (From Real Code)

The boilerplate selects the LLM client in `SwiftAIBoilerplatePro/Composition/LLMClientFactory.swift`,
reading the generated `AppConfiguration` (built from `Config/Secrets.xcconfig`). It returns
`EchoLLMClient` until a real `PROXY_BASE_URL` is configured:

```swift theme={null}
@available(iOS 17.0, *)
func createLLMClient(httpClient: any HTTPClient) -> any LLMClient {
    guard let baseURL = URL(string: AppConfiguration.PROXY_BASE_URL),
          !AppConfiguration.PROXY_BASE_URL.contains("YOUR"),
          !AppConfiguration.PROXY_BASE_URL.contains("placeholder") else {
        AppLogger.info("LLM provider: EchoLLMClient (PROXY_BASE_URL not configured)", category: AppLogger.ai)
        return EchoLLMClient()
    }

    let proxyPath = AppConfiguration.PROXY_PATH

    var defaultHeaders: [String: String] = [:]
    if let headersJson = ProcessInfo.processInfo.environment["PROXY_DEFAULT_HEADERS"] {
        defaultHeaders = parseHeadersJSON(headersJson)
    }

    let proxyClient = ProxyLLMClient(
        baseURL: baseURL,
        httpClient: httpClient,  // carries the auth + retry interceptors
        path: proxyPath,
        defaultHeaders: defaultHeaders
    )

    AppLogger.info(
        "LLM provider: ProxyLLMClient (url=\(AppConfiguration.PROXY_BASE_URL), path=\(proxyPath))",
        category: AppLogger.ai
    )
    return proxyClient
}
```

`CompositionRoot` wires it up with `self.llmClient = createLLMClient(httpClient: httpClient)`. The
default generated `PROXY_PATH` is `/ai` (the Edge Function route); `EchoLLMClient` itself lives in
this same factory file, not in the AI package.

### Why This Architecture

**Proxy Pattern (Production):**

* ✅ API keys never in app (stored in Supabase secrets)
* ✅ Authentication via JWT (automatic via AuthInterceptor)
* ✅ Backend controls costs and rate limits
* ✅ Can switch models without app update

**Echo Fallback (Development):**

* ✅ Test UI without backend setup
* ✅ No API costs during development
* ✅ Perfect for rapid iteration
* ✅ Auto-enabled until `PROXY_BASE_URL` is set to a real URL (placeholder/`YOUR` values still use Echo)

## Streaming Pattern

```swift theme={null}
// In ViewModel
for try await chunk in llmClient.streamResponse(messages: messages) {
    // Update UI with each token
    currentResponse += chunk
}
```

**Benefits:**

* ✅ Low latency (first token quickly)
* ✅ Better UX (gradual appearance)
* ✅ Cancellable (stop generation)
* ✅ Memory efficient

## Supported Models

OpenRouter exposes [500+ models](https://openrouter.ai/models). For cost control, the shipped Edge
Function only forwards an explicit **allowlist** — anything else is rejected with `400 Invalid model`:

```ts theme={null}
// supabase/functions/ai/index.ts
const ALLOWED_MODELS = ['openai/gpt-3.5-turbo', 'openai/gpt-4o-mini']
// default when the client omits `model`:
const { messages, model = 'openai/gpt-3.5-turbo', temperature = 0.7 } = await req.json()
```

To use Anthropic, Google, Meta, or any other OpenRouter model, add its slug to `ALLOWED_MODELS`,
redeploy the function, then pass `model:` from the client:

```swift theme={null}
let stream = llmClient.streamResponse(
    messages: messages,
    model: "anthropic/claude-3.7-sonnet",  // must be in ALLOWED_MODELS
    temperature: 0.7
)
```

## Supabase Edge Function

The proxy keeps API keys server-side and enforces auth, entitlement, and rate limits before any
upstream cost is incurred:

```ts theme={null}
// supabase/functions/ai/index.ts
serve(async (req) => {
  // 1. Verify user auth (Supabase JWT)
  // 2. Check the active AI entitlement (server-trusted, RevenueCat-backed)
  // 3. Consume the per-user rate limit (60 req / 60 min by default)
  // 4. Validate model against ALLOWED_MODELS + bounds-check messages
  // 5. Call OpenRouter with the server-side key and stream tokens back
})
```

**Deployment:**

```bash theme={null}
supabase secrets set OPENROUTER_API_KEY=sk-or-v1-YOUR_KEY
supabase functions deploy ai
```

## Customization Examples

### Add a System Prompt

`role` is a plain `String` — use `"system"`, `"user"`, or `"assistant"`:

```swift theme={null}
let systemMessage = LLMMessage(
    role: "system",
    content: """
    You are a professional Swift developer.
    Provide clear, concise answers with code examples.
    """
)

let messages = [systemMessage] + conversationHistory + [userMessage]
```

<Note>
  The shipped Edge Function injects its own server-controlled `SYSTEM_PROMPT` and only accepts
  `user`/`assistant` roles from clients (`ALLOWED_ROLES`). Client-supplied `system` messages are
  only meaningful for a direct client you write yourself (the local `EchoLLMClient` ignores them
  and simply echoes the last user message). To change the production persona,
  edit `SYSTEM_PROMPT` in `supabase/functions/ai/index.ts`.
</Note>

### Add a Direct LLM Provider

The `LLMClient` protocol lives in **FeatureChat** (re-exported by `import AI`). Conform to it to
bypass the proxy:

```swift theme={null}
import AI

final class OpenAIClient: LLMClient {
    func streamResponse(messages: [LLMMessage]) -> AsyncThrowingStream<String, Error> {
        // Direct OpenAI API integration — no proxy
    }
}

// Then return it from createLLMClient(...) in LLMClientFactory.swift
```

## Security

**API keys never in client:**

* ✅ Edge Function holds OpenRouter key
* ✅ User auth required for proxy access
* ✅ Rate limiting at Edge Function
* ✅ No keys in client code
* ✅ Messages not logged by proxy

## Key Files

| Component                                    | Location                                                             |
| -------------------------------------------- | -------------------------------------------------------------------- |
| `LLMClient` protocol + `LLMMessage`          | `Packages/FeatureChat/Sources/FeatureChat/Protocols/LLMClient.swift` |
| AI module namespace (re-exports FeatureChat) | `Packages/AI/Sources/AI/AI.swift`                                    |
| Proxy client                                 | `Packages/AI/Sources/AI/Clients/ProxyLLMClient.swift`                |
| Proxy request builder + SSE parser           | `Packages/AI/Sources/AI/Clients/Proxy/`                              |
| Echo client + `createLLMClient` factory      | `SwiftAIBoilerplatePro/Composition/LLMClientFactory.swift`           |
| Edge Function                                | `supabase/functions/ai/index.ts`                                     |

## Dependencies

* **Core** - Error handling, logging
* **Networking** - HTTP client for proxy
* **FeatureChat** - owns `LLMClient` / `LLMMessage`; the AI package re-exports it

## Used By

* **App target** - `LLMClientFactory` builds the proxy/echo client
* **Custom features** - Your AI features

<Note>
  The boilerplate ships **no LLM**. The optional **App Generator** (a separate macOS product,
  [coming soon](/pages/reference/license)) drives your own coding-agent CLI to scaffold a
  differentiated app from this template — it does not bundle a model either.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Streaming">
    * Use AsyncThrowingStream
    * Handle cancellation
    * Update UI incrementally
    * Show loading state
  </Accordion>

  <Accordion title="Error Handling">
    * Map to AppError
    * Retry transient failures
    * Show user-friendly messages
    * Log technical details
  </Accordion>

  <Accordion title="Cost Management">
    * Choose appropriate model
    * Use mini/flash for simple tasks
    * Cache system prompts
    * Limit message history
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Full Documentation" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/modules/AI.md">
    Complete AI guide
  </Card>

  <Card title="Supabase Setup" icon="server" href="/pages/guides/supabase-setup">
    Deploy Edge Function
  </Card>

  <Card title="Feature Chat" icon="comments" href="/pages/modules/feature-chat">
    See AI integration
  </Card>

  <Card title="Building Guide" icon="hammer" href="/pages/guides/building-your-app">
    Customize AI experience
  </Card>
</CardGroup>

## Test Coverage

The `AITests` target covers the proxy client end to end — request building, SSE stream parsing,
error mapping, and cancellation (`Tests/AITests/Proxy/`). It runs as part of the workspace suite:
**\~598 tests across 12 package test targets + the app test suites**, in one `Boilerplate.xctestplan`
run.

Tests include:

* Request building (headers, path, body)
* SSE stream parsing and `[DONE]` termination
* Error mapping to `AppError`
* Cancellation


# Auth Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/auth

Production **unified authentication** with Apple, Google, and Email via Supabase. Includes **reliable session persistence** and **automatic token refresh**.

<Info>
  **Full technical details** in your project at `/docs/modules/Auth.md`
</Info>

## What You Get

* ✅ **3 auth providers** - Apple, Google, Email (all via Supabase)
* ✅ **Reliable session persistence** - Users stay logged in for days, not hours
* ✅ **Automatic token refresh** - Silent background refresh keeps sessions alive
* ✅ **Expired session recovery** - Refresh tokens restore sessions even after access token expires
* ✅ **Keychain storage** - Secure, encrypted token persistence
* ✅ **AsyncStream state** - Observable authentication state (including `.refreshing`)
* ✅ **MockAuthClient** - DEBUG mode works without backend

**Time saved: 20-32 hours** of auth flows, token management, session handling, and comprehensive testing.

## Module structure (since v2.0)

* **`SessionManager` is split across four files**: `SessionManager.swift`, `SessionManager+SignIn.swift`, `SessionManager+Refresh.swift`, and `SessionManager+Persistence.swift`. The public actor API is **unchanged**. This is the ≤ 400-line rule in action.
* **`SupabaseAuthAPI` helpers moved** to `SupabaseAuthAPI+Mapping.swift`. Private helpers only; no API change.
* All protocol-typed properties now use the explicit `any` keyword required by Swift 6.

## Session Behavior

| Scenario                  | Behavior                                       |
| ------------------------- | ---------------------------------------------- |
| App opened after 1 hour   | ✅ Silent refresh, user stays logged in         |
| App opened after 3 days   | ✅ Silent refresh, user stays logged in         |
| App opened after 14+ days | Refresh token expired, user must sign in again |

<Note>
  Users only need to re-authenticate when the refresh token expires (7+ days by default, configurable in Supabase).
</Note>

## Key Components

### AuthClient Protocol

```swift theme={null}
@available(iOS 17.0, *)
public protocol AuthClient: Sendable {
    func signInWithApple() async throws -> AuthUser
    func signInWithGoogle() async throws -> AuthUser
    func signUpWithEmail(email: String, password: String) async throws -> AuthUser
    func signInWithEmail(email: String, password: String) async throws -> AuthUser
    func resetPassword(email: String) async throws
    func signOut() async throws
    func currentUser() async -> AuthUser?
    func authStates() -> AsyncStream<AuthState>
    func refreshIfNeeded() async throws
}
```

## Production Setup (From Real Code)

How authentication is set up in `CompositionRoot.swift`:

```swift theme={null}
// 1. Configure Supabase (values come from the generated AppConfiguration,
//    built at compile time from Config/Secrets.xcconfig)
let authConfig = AuthConfig(
    supabaseURL: url,                              // AppConfiguration.SUPABASE_URL
    supabaseAnonKey: AppConfiguration.SUPABASE_ANON_KEY
)

// 2. Create HTTP client for Supabase API
let supabaseHTTPClient = Auth.SupabaseHTTPClient(
    baseURL: authConfig.supabaseURL,
    session: .shared
)

// 3. Create Apple Sign In coordinator
let appleSignInCoordinator = Auth.AppleSignInCoordinator()

// 4. Create SessionManager (production auth client)
let sessionManager = Auth.SessionManager(
    httpClient: supabaseHTTPClient,
    keychain: keychainStore,
    apple: appleSignInCoordinator,
    config: authConfig
)

// SessionManager automatically:
// - Loads saved session from Keychain on init
// - Schedules proactive token refresh (60s before expiry)
// - Emits auth state changes via AsyncStream
// - Handles Apple + Email out of the box (Google once a GoogleSignInCoordinator is passed)
```

### What SessionManager Does

**On App Launch:**

1. Loads session from Keychain
2. Validates token expiry
3. Auto-refreshes if expiring soon
4. Emits `.authenticated` or `.unauthenticated` state

**On Sign In:**

1. Exchanges provider token with Supabase
2. Saves access + refresh tokens to Keychain
3. Schedules proactive refresh
4. Emits `.authenticated(user)` state

**Token Refresh:**

* Scheduled 60s before token expiry
* Recovers expired sessions using refresh token
* Retries up to 3 times with exponential backoff
* Handles Supabase token rotation
* Users stay logged in for days, not hours

**Production Quality:**

* ✅ Race-safe refresh mutex
* ✅ Cancellation-aware
* ✅ Comprehensive error handling
* ✅ Fully tested (85%+ coverage)

## Token Management

### Automatic Refresh

```swift theme={null}
// SessionManager handles:
// - Token refresh before expiry
// - Retry on refresh failure
// - Keychain persistence
// - Logout on refresh failure
```

### Secure Storage

All tokens stored in Keychain:

* ✅ Access token
* ✅ Refresh token
* ✅ Never in UserDefaults
* ✅ OS-level encryption

## Auth State Observation

```swift theme={null}
// Observe auth state changes
for await state in authClient.authStates() {
    switch state {
    case .authenticated(let user):
        // Navigate to authenticated content
    case .unauthenticated:
        // Show sign-in screen
    case .refreshing:
        // Keep the current UI while restoring the session
    }
}
```

## Customization Examples

### Add a Social Provider

Apple and Email ship wired out of the box. Google is implemented in the package
(`GoogleSignInCoordinator`) but is **not** wired in `CompositionRoot` by default —
pass a Google provider to `SessionManager(google:)` to enable it. To add another
provider, declare it on `AuthClient` and implement it on the production client
(`SessionManager`, in `SessionManager+SignIn.swift`):

```swift theme={null}
// 1. Add to the AuthClient protocol (Packages/Auth/.../Protocols/AuthClient.swift)
func signInWithGitHub() async throws -> AuthUser

// 2. Implement in SessionManager (Packages/Auth/.../Session/SessionManager+SignIn.swift)
public func signInWithGitHub() async throws -> AuthUser {
    // Exchange the provider token with Supabase, then persist the session
}
```

### Add Custom Fields

```swift theme={null}
// Extend AuthUser (real fields: id, email, name, avatarURL)
struct AuthUser {
    let id: String
    let email: String?
    let name: String?
    let avatarURL: URL?
    var customField: String?  // Add custom fields
}
```

## Mock Auth in DEBUG

**Enabled by default!** No setup needed.

`CompositionRoot` selects the mock at startup. In DEBUG it uses `MockAuthClient`
unless `AUTH_BYPASS=0` is set; in RELEASE the mock is compiled out entirely.

```swift theme={null}
#if DEBUG
let authBypassValue = ProcessInfo.processInfo.environment["AUTH_BYPASS"]
let shouldUseMock = authBypassValue != "0"  // mock unless explicitly disabled

if shouldUseMock {
    self.sessionManager = Auth.MockAuthClient()
} else {
    // real Supabase + Apple + Email auth …
}
#else
// RELEASE always uses real authentication
#endif
```

**To use real auth in DEBUG:**

1. Edit Scheme → Run → Environment Variables
2. Add `AUTH_BYPASS` = `0`
3. Configure Supabase in `Config/Secrets.xcconfig`

## Key Files

| Component     | Location                                                |
| ------------- | ------------------------------------------------------- |
| Protocol      | `Packages/Auth/Sources/Auth/Protocols/AuthClient.swift` |
| Supabase      | `Packages/Auth/Sources/Auth/Supabase/`                  |
| Apple Sign In | `Packages/Auth/Sources/Auth/Apple/`                     |
| Session       | `Packages/Auth/Sources/Auth/Session/`                   |
| Mock          | `Packages/Auth/Sources/Auth/Mock/`                      |

## Dependencies

* **Core** - Error handling, logging
* **Networking** - HTTP client (for Supabase)

## Used By

* **All features** - Protected by authentication
* **CompositionRoot** - Observes auth state
* **LaunchRouter** - Auth-gated navigation

## Best Practices

<AccordionGroup>
  <Accordion title="Token Security">
    * Always store in Keychain
    * Never log tokens
    * Refresh before expiry
    * Clear on sign out
  </Accordion>

  <Accordion title="Error Handling">
    * Map to AppError
    * User-friendly messages
    * Retry transient failures
    * Log technical details
  </Accordion>

  <Accordion title="Testing">
    * Use MockAuthClient
    * Test token refresh
    * Test error scenarios
    * Test state transitions
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Full Documentation" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/modules/Auth.md">
    Complete Auth guide
  </Card>

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

  <Card title="Building Guide" icon="hammer" href="/pages/guides/building-your-app">
    Customize auth flow
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    See auth in system
  </Card>
</CardGroup>

## Test Coverage

**85%+** - Comprehensive auth testing (run via the `AuthTests` target in the single `Boilerplate.xctestplan` pass)

Tests include:

* Sign in/up flows
* Token refresh
* Session management
* Apple Sign In coordination
* Error scenarios
* State transitions


# Core Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/core

Foundation layer providing **typed error handling**, **PII-safe logging**, and shared utilities. Zero dependencies by design.

<Info>
  **Full technical details** in your project at `/docs/modules/Core.md`
</Info>

## What's new

* **v2.2.0** — the localized error surface lives next to Core: `AppError.localizedUserMessage` (en + es) is provided by the Localization package, and every UI error call site now displays it instead of the raw `userMessage`. See the [AI](/pages/modules/ai) and [Localization](/pages/modules/localization) modules for how this threads through the app.
* **v2.0** — `DeepLinkBus` (in Core) is `@Observable`. Consumers that used `.onReceive($bus.latest)` should migrate to `.onChange(of: bus.latest)`. SwiftUI's observation machinery does the rest.
* Swift 6 strict concurrency across the package.

## What You Get

* ✅ **AppError enum** - Maps all system errors to user-friendly messages
* ✅ **AppLogger** - OSLog-based with automatic PII redaction
* ✅ **ResultOrError** - Functional error handling patterns
* ✅ **Theme types** - `ThemeManager` with a `Theme` enum (system, light, dark, aurora, obsidian)
* ✅ **Zero dependencies** - Pure foundation layer

**Time saved: 6-10 hours** of error handling boilerplate, logging infrastructure, and testing.

## Key Components

### AppError (Production Type)

Here's a shortened version of the production enum from the boilerplate:

```swift theme={null}
public enum AppError: Error, Equatable, CustomStringConvertible, LocalizedError, Sendable {
    case network(code: Int, message: String?)
    case decoding
    case unauthorized
    case rateLimited(retryAfter: TimeInterval?)
    // Additional cases omitted for brevity.

    // User-friendly messages
    public var userMessage: String {
        switch self {
        case .network(_, let message) where message?.localizedCaseInsensitiveContains("offline") == true:
            return "You're offline. Please check your internet connection."
        case .network(_, let message) where message?.localizedCaseInsensitiveContains("timeout") == true:
            return "Request timed out. Please try again."
        case .unauthorized:
            return "Invalid email or password. Please check your credentials and try again."
        case .rateLimited:
            return "Too many requests. Please wait a moment and try again."
        // ... handles all cases with actionable messages
        }
    }
}
```

**SignInViewModel:**

```swift theme={null}
// From SwiftAIBoilerplatePro/AppShell/SignInView.swift
func signInWithApple() async {
    do {
        _ = try await authClient.signInWithApple()
        AppLogger.info("Apple sign in successful", category: AppLogger.ui)
        errorMessage = nil
    } catch {
        let appError = AppError.from(error)            // Auto-maps to AppError
        errorMessage = appError.localizedUserMessage   // Localized (en + es) message for the UI
        AppLogger.error("Apple sign in failed: \(error)", category: AppLogger.ui)
    }
}
```

`localizedUserMessage` is the localized counterpart to `AppError.userMessage`, supplied by the Localization package and used by every UI error call site.

**Production Value:**

* ✅ Auto-maps URLError, NSError, custom errors
* ✅ Preserves technical details for logging
* ✅ Provides actionable user messages
* ✅ Sendable for Swift 6 compatibility
* ✅ Equatable for testing

### AppLogger

Structured logging with PII redaction:

```swift theme={null}
// Usage
AppLogger.debug("Message sent", category: AppLogger.ui)
AppLogger.info("API call succeeded", category: AppLogger.networking)
AppLogger.error("Failed to save", category: AppLogger.storage)

// Redact sensitive data before logging
AppLogger.debug("API Key: \(AppLogger.redacted(apiKey))", category: AppLogger.networking)
```

**Categories** (each a `Logger`; pass as `category:`):

* `AppLogger.networking` - HTTP requests
* `AppLogger.ai` - LLM interactions
* `AppLogger.ui` - User interface events
* `AppLogger.feature` - Feature operations
* `AppLogger.storage` - SwiftData / Keychain / persistence
* `AppLogger.notifications` - Notification operations
* `AppLogger.auth` - Authentication flows
* `AppLogger.payments` - Subscriptions and purchases

`AppLogger.subsystem` is the shared subsystem identifier (a `String`), not a category.

## Customization Examples

### Add Custom Error Type

```swift theme={null}
// In AppError
case myFeature(reason: MyFeatureErrorReason)

enum MyFeatureErrorReason {
    case invalidInput
    case processingFailed
}

// Add user message
var userMessage: String {
    switch self {
    case .myFeature(.invalidInput):
        return "Please check your input"
    case .myFeature(.processingFailed):
        return "Processing failed. Please try again"
    }
}
```

### Add Custom Log Category

```swift theme={null}
import OSLog

extension AppLogger {
    static let myFeature = Logger(
        subsystem: subsystem,
        category: "MyFeature"
    )
}

// Use it
AppLogger.info("Feature initialized", category: AppLogger.myFeature)
```

## Key Files

| Component   | Location                                     |
| ----------- | -------------------------------------------- |
| AppError    | `Packages/Core/Sources/Core/AppError.swift`  |
| AppLogger   | `Packages/Core/Sources/Core/AppLogger.swift` |
| Diagnostics | `Packages/Core/Sources/Core/Diagnostics/`    |

## Dependencies

* **None** - Core has zero dependencies (by design)

## Used By

* ✅ All other modules (foundation layer)
* ✅ ViewModels (error handling)
* ✅ Services (logging)

## Best Practices

<AccordionGroup>
  <Accordion title="Error Handling">
    * Always map errors to `AppError`
    * Use specific error reasons
    * Provide actionable user messages
    * Log technical details separately
  </Accordion>

  <Accordion title="Logging">
    * Prefer `AppLogger` over `print()` in app code (`print()` is fine in `#Preview` blocks)
    * Choose appropriate log level
    * Use correct category
    * Redact PII automatically
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Full Documentation" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/modules/Core.md">
    Complete Core guide
  </Card>

  <Card title="Networking Module" icon="wifi" href="/pages/modules/networking">
    Uses Core for errors and logging
  </Card>

  <Card title="Storage Module" icon="database" href="/pages/modules/storage">
    Uses Core for error handling
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    See how Core fits in
  </Card>
</CardGroup>

## Test Coverage

**95%+** - Core is foundational, so it carries some of the highest coverage in the codebase. Its tests run alongside everything else in the single workspace pass: \~598 tests across 12 package test targets (the 11 reusable packages plus the `TestSupport` test-infrastructure package) and the app test suites, all driven by one `Boilerplate.xctestplan` run.

Tests include:

* Error mapping scenarios
* Logger output verification
* PII redaction


# Design System Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/design-system

Production design tokens and UI components with 5 built-in themes. Token-based system ensures visual consistency.

<Info>
  **Full technical details** in your project at `/docs/modules/DesignSystem.md`
</Info>

## What You Get

* ✅ **Token system** - Colors, spacing, typography, radius (never hardcode values)
* ✅ **5 themes** - System, Light, Dark, Aurora, Obsidian
* ✅ **Liquid Glass primitive** - `SAIGlass` with iOS 26 glass and iOS 17–25 Material fallback (new in v2.0)
* ✅ **Premium components** - Buttons, inputs, cards, bubbles
* ✅ **BrandConfig** - Single place to customize app identity
* ✅ **Accessibility** - Dynamic Type, VoiceOver, Reduce Motion
* ✅ **Gradients & motion** - Premium visual effects

**Time saved: 20-32 hours** of design system, theming infrastructure, component library, and testing.

## Liquid Glass

v2.0 introduces `SAIGlass`, a Liquid Glass primitive that uses the iOS 26 `Glass` material on iOS 26+ and falls back to SwiftUI `Material` on iOS 17–25. Same call sites, progressive enhancement at runtime.

**Location:** `Packages/DesignSystem/Sources/DesignSystem/Materials/SAIGlass.swift`

### SAIGlassStyle

```swift theme={null}
public enum SAIGlassStyle {
    case regular  // Standard glass surface (cards, toolbars, sheets)
    case clear    // Edge-to-edge hero surfaces (paywall, onboarding)
}
```

### The `.saiGlass` modifier

One-call glass treatment for any view:

```swift theme={null}
// Simple card
VStack { /* content */ }
    .saiGlass(.regular)

// In a shape, interactive
Text("Tap me")
    .padding()
    .saiGlass(.regular, in: Capsule(), interactive: true)
```

| Modifier                       | Purpose                                                                                                                |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `.saiGlass(_:in:interactive:)` | Apply a glass material to any view. `in:` accepts any `Shape`; `interactive:` enables tap-response morphing on iOS 26. |
| `.saiScrollEdgeGlass(_:)`      | Glass treatment at scroll edges (under nav bars, tab bars).                                                            |
| `.saiSidebarAdaptable()`       | Adaptive sidebar styling for iPad and large displays.                                                                  |
| `.saiTabBarMinimize(_:)`       | Opt into iOS 26 tab bar minimisation on scroll. iOS 17–25 no-op.                                                       |

### SAIGlassContainer

Use when multiple glass surfaces sit near each other so they sample the same background instead of stacking visually:

```swift theme={null}
SAIGlassContainer {
    RatingCard()
    TipCard()
    UpsellCard()
}
```

### SAITabBarMinimizeStyle

```swift theme={null}
TabView { ... }
    .saiTabBarMinimize(.onScrollDown)  // iOS 26 only; no-op on iOS 17–25
```

<Tip>
  **Fighting glass? Stop.** Do **not** pile `.background(DSColors.background)` or `DSColors.background.ignoresSafeArea()` onto SwiftUI containers. They block the Material SwiftUI already provides and wreck Liquid Glass on iOS 26. See the [Migration Guide](/pages/migration/v1-9-to-v2-0) for cleanup steps.
</Tip>

## BrandConfig (Customize Your App)

**Single file** to customize app identity. From `BrandConfig.swift`:

```swift theme={null}
public struct BrandConfig {
    // Change this to your app name (ships with the starter value "App Name")
    public static let appDisplayName = "App Name" // generator:brand appDisplayName

    // Accent color for highlights and CTAs
    public static let accentColor: Color = DSColors.primary

    // SF Symbol for default avatar
    public static let avatarFallbackSymbol = "person.circle.fill" // generator:brand avatarFallbackSymbol

    // Production legal URLs — leave empty until your live HTTPS pages exist.
    // Non-HTTPS / placeholder values resolve to nil (no Release fallback).
    public static let privacyPolicyURLString = ""        // generator:brand privacyPolicyURL
    public static let termsOfServiceURLString = ""       // generator:brand termsOfServiceURL
    public static let subscriptionTermsURLString = ""    // generator:brand subscriptionTermsURL

    // App icon background color (for generated icons)
    public static let appIconBackground: Color = DSColors.primary
}
```

**To rebrand:**

1. Change `appDisplayName` → Your app name
2. Update the `AccentPrimary` color set in `Resources/Assets.xcassets`
3. Change `avatarFallbackSymbol` → Your SF Symbol
4. Set the legal URL strings to your live HTTPS pages before shipping
5. Entire app updates automatically

<Note>
  The `// generator:brand` markers are stable anchors for the App Generator's identity transforms — a separate product (coming soon). Keep one declaration per line and do not remove the markers. They are inert in the boilerplate itself.
</Note>

## Design Tokens (Production System)

### DSColors - Theme-Aware

Every color adapts to the active theme:

```swift theme={null}
// Real usage from auth screen
Text(BrandConfig.appDisplayName)
    .foregroundStyle(DSColors.textPrimary)

Button("Sign In")
    .foregroundStyle(DSColors.accentPrimary)  // Coral in Aurora, blue in default

VStack {}
    .background(DSColors.background)         // Adapts to all 5 themes
```

**Token categories:**

* Text: `textPrimary`, `textSecondary`
* Surfaces: `background`, `surface`, `surfaceElevated`
* Accents: `accentPrimary`, `accentSecondary`
* Borders: `borderHairline`, `borderSubtle`
* Semantic: `success`, `warning`, `danger`

### DSSpacing

Consistent spacing scale:

```swift theme={null}
// Usage
.padding(DSSpacing.md)
VStack(spacing: DSSpacing.lg) { }

// Scale: xs (4pt) → sm (8pt) → md (12pt) → lg (16pt) → xl (24pt)
```

### DSTypography

Text styles with Dynamic Type:

```swift theme={null}
// Usage
Text("Title").font(DSTypography.titleL)
Text("Body").font(DSTypography.body)

// Styles: titleXL, titleL, titleM, body, caption, code
```

### DSRadius

Corner radius values:

```swift theme={null}
// Usage
.cornerRadius(DSRadius.md)

// Scale: xs (8pt) → sm (12pt) → md (16pt) → lg (24pt) → xl (32pt)
// Plus DSRadius.card (= lg, 24pt) — the default card radius
```

## UI Components

<Tabs>
  <Tab title="Buttons">
    ```swift theme={null}
    SAIButton("Primary", style: .primary) { action() }
    SAIButton("Secondary", style: .secondary) { action() }
    SAIButton("Quiet", style: .quiet, size: .sm) { action() }
    ```
  </Tab>

  <Tab title="Inputs">
    ```swift theme={null}
    SAIInputBar(text: $message, onSend: sendMessage)
    SAIInputBar(text: $message, showTokenCount: true, onSend: sendMessage)
    ```
  </Tab>

  <Tab title="Cards & Rows">
    ```swift theme={null}
    SAICard(style: .elevated) {
        // Content
    }

    SAIListRow(title: "Setting", subtitle: "Value") {
        Image(systemName: "chevron.right")  // trailing accessory
    }
    ```
  </Tab>

  <Tab title="Other">
    ```swift theme={null}
    SAIAvatar(name: "John Doe", imageURL: url)
    ChatBubble(role: .user, text: "Hello")
    DSSectionHeader(title: "Section")
    ToastCenter.shared.show(ToastMessage(title: "Success!", style: .success))
    ```
  </Tab>
</Tabs>

## Theme System

### 5 Built-in Themes

<CardGroup>
  <Card title="System" icon="mobile">
    Follows iOS light/dark mode
  </Card>

  <Card title="Light" icon="sun">
    Always light appearance
  </Card>

  <Card title="Dark" icon="moon">
    Always dark appearance
  </Card>

  <Card title="Aurora" icon="stars">
    Premium light — warm cream with coral/peach accents
  </Card>

  <Card title="Obsidian" icon="gem">
    Premium dark — deep navy with electric cyan accents
  </Card>
</CardGroup>

### Applying Themes

From Settings, persist and apply a theme in one call (`SettingsDTO.Theme`):

```swift theme={null}
await settingsViewModel.setTheme(.aurora)  // persists + applies app-wide
```

`ThemeManager` (in the `Core` package) owns the live theme and is also reachable directly:

```swift theme={null}
@Environment(ThemeManager.self) private var themeManager
themeManager.selected = .aurora  // applies instantly, without persisting Settings
```

### How It Works

```text theme={null}
1. settingsViewModel.setTheme maps SettingsDTO.Theme → ThemeManager.Theme
2. ThemeManager persists the choice (UserDefaults) and applies the interface style
3. It posts a "ThemeDidChange" notification
4. DSColors.setTheme(_:colorScheme:) updates DSColors.activeTheme
5. Color tokens return theme-specific values and SwiftUI refreshes
```

## Customization Examples

### Create Custom Theme

<Steps>
  <Step title="Add Color Set">
    In `Resources/Assets.xcassets`, add a color set per token you want to override (e.g. `AccentPrimary`, `Background`). Themed values can also be returned in code (see step 3).
  </Step>

  <Step title="Add Theme Cases">
    Add `case myTheme` to both theme enums — the persisted `SettingsDTO.Theme`
    (`Packages/Storage/.../SettingsDTO.swift`) and the live `ThemeManager.Theme`
    (`Packages/Core/Sources/Core/Theme/ThemeManager.swift`). Then add the
    `.myTheme` branch to the mapping in `SettingsViewModel.setTheme(_:)`, and add a
    matching case to `DSColors.ThemePalette` + `DSColors.setTheme(_:colorScheme:)`.
  </Step>

  <Step title="Map Colors">
    In `DSColors.swift`, branch on `activeTheme`:

    ```swift theme={null}
    public static var accentPrimary: Color {
        switch activeTheme {
        case .myTheme:
            return Color("MyThemePrimary", bundle: .module)
        default:
            return named("AccentPrimary", fallback: .blue)
        }
    }
    ```
  </Step>

  <Step title="Surface in the Picker">
    The settings appearance picker iterates `SettingsDTO.Theme.allCases`, so the
    new case appears automatically once the cases above are wired up.
  </Step>
</Steps>

### Create Custom Component

```swift theme={null}
public struct MyCustomCard: View {
    let title: String
    let subtitle: String
    
    public var body: some View {
        VStack(alignment: .leading, spacing: DSSpacing.sm) {
            Text(title)
                .font(DSTypography.titleM)
                .foregroundStyle(DSColors.textPrimary)
            
            Text(subtitle)
                .font(DSTypography.body)
                .foregroundStyle(DSColors.textSecondary)
        }
        .padding(DSSpacing.md)
        .background(DSColors.surface)
        .cornerRadius(DSRadius.md)
    }
}
```

## Animations

Standard motion timings live in `SAIMotion` and respect Reduce Motion:

```swift theme={null}
// Timings
SAIMotion.quick     // 0.12s — micro-interactions
SAIMotion.standard  // 0.18s — most UI changes
SAIMotion.smooth    // 0.25s — larger transitions

// Springs
SAIMotion.spring        // response 0.3, damping 0.7
SAIMotion.gentleSpring  // subtle bounces

// Accessibility-aware (auto-fallback when Reduce Motion is on)
SAIMotion.adaptiveStandard
SAIMotion.adaptiveSpring

// Usage
.animation(SAIMotion.spring, value: isExpanded)

// Reusable view modifiers
SomeView().pressedEffect(isPressed: isPressed)  // scale + shadow, opacity-only under Reduce Motion
SomeView().shimmer(isActive: true)              // loading shimmer, disabled under Reduce Motion
```

## Accessibility

Built-in support for:

* ✅ **Dynamic Type** - All text scales automatically
* ✅ **VoiceOver** - All components labeled
* ✅ **High Contrast** - Semantic colors adapt
* ✅ **Reduced Motion** - Respects system preference
* ✅ **Minimum Touch Targets** - 44pt minimum

## Key Files

| Component    | Location                                                               |
| ------------ | ---------------------------------------------------------------------- |
| Tokens       | `Packages/DesignSystem/Sources/DesignSystem/Tokens/`                   |
| Components   | `Packages/DesignSystem/Sources/DesignSystem/Components/`               |
| Liquid Glass | `Packages/DesignSystem/Sources/DesignSystem/Materials/SAIGlass.swift`  |
| Colors       | `Packages/DesignSystem/Sources/DesignSystem/Resources/Assets.xcassets` |

## Dependencies

* **None** - DesignSystem is independent

## Used By

* **All features** - Every UI component
* **App Shell** - Main app screens
* **Feature modules** - Chat, Rating, Settings

## Best Practices

<AccordionGroup>
  <Accordion title="Using Tokens">
    * Never hardcode colors
    * Never hardcode spacing
    * Use semantic names
    * Test in all themes
  </Accordion>

  <Accordion title="Creating Components">
    * Use design tokens exclusively
    * Support all themes
    * Add accessibility labels
    * Test Dynamic Type
    * Include preview
  </Accordion>

  <Accordion title="Theming">
    * Semantic colors only
    * Support light + dark
    * Instant switching
    * Persist preference
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Full Documentation" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/modules/DesignSystem.md">
    Complete DesignSystem guide
  </Card>

  <Card title="Feature Settings" icon="gear" href="/pages/modules/feature-settings">
    Theme selection UI
  </Card>

  <Card title="Building Guide" icon="hammer" href="/pages/guides/building-your-app">
    Customize themes
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    See how modules use DesignSystem
  </Card>
</CardGroup>

## Test Coverage

The `DesignSystemTests` target (token + snapshot tests) runs as part of the
workspace suite — \~598 tests across 12 package test targets plus the app test
suites, all in one `Boilerplate.xctestplan` pass.

Tests include:

* Theme switching
* Color mapping
* Component snapshots
* Accessibility
* Dynamic Type


# Feature Chat Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/feature-chat

Complete chat UI with dual styles, streaming, and pagination

Production **chat system** with **2 UI styles**, **streaming AI responses**, **cursor pagination**, and **comprehensive error handling**.

<Info>
  **Full technical details** in your project at `/docs/modules/Feature.Chat.md`
</Info>

## What You Get

* ✅ **2 professional UIs** - Bubble (WhatsApp) and Centered (ChatGPT)
* ✅ **Streaming responses** - Real-time token-by-token rendering
* ✅ **Cursor pagination** - Infinite scroll with smart prefetch
* ✅ **Conversation management** - Create, rename, delete, filter by title
* ✅ **Message limits** - Free-tier cap (`kFreeMessageLimit = 10`) gates non-subscribers
* ✅ **Error handling** - Retry, cancellation, localized error messages

**Time saved: 40-60 hours** of UI implementation, streaming logic, pagination, state management, and testing.

## Liquid Glass layout

* `ChatView` and `ChatGPTStyleView` host the input bar via `.safeAreaInset(edge: .bottom)`. The scroll view is the full body, not a `VStack` stacking input below messages. This is what lets Liquid Glass sample the content behind the input bar on iOS 26.
* The scroll-edge effect is wired through `saiScrollEdgeGlass(.bottom)` so the bottom of the chat transcript blurs into the input chrome.
* `ChatViewModel` has a sibling extension file, `ChatViewModel+Memory.swift`, which keeps memory-extraction concerns out of the main view model.

## UI Styles

<Tabs>
  <Tab title="Bubble Style">
    WhatsApp/iMessage-like interface:

    * Messages in colored bubbles
    * User on right (blue), AI on left (gray)
    * Timestamps and avatars
    * Smooth animations

    **Best for:** Casual, conversational apps
  </Tab>

  <Tab title="Centered Style">
    ChatGPT-like interface:

    * Full-width messages
    * Clean, minimal design
    * Role badges (You/AI)
    * Professional appearance

    **Best for:** Professional, productivity apps
  </Tab>
</Tabs>

**Style is chosen per conversation** - the history screen's launcher cards ("Bubble Chat" / "Prompt Chat") pick which UI opens via `makeChatView(conversationID:style:)`.

## Key Components

### Production Factory

The boilerplate uses a **factory pattern** in `CompositionRoot`:

```swift theme={null}
// Factory method with dependency injection
public func makeChatViewModel(conversationID: UUID) -> ChatViewModel {
    ChatViewModel(
        conversationID: conversationID,
        messageRepository: messageRepository,  // SwiftData repository
        llmClient: llmClient,                  // Proxy or Echo client
        paymentsStatusProvider: PaymentsStatusAdapter(paymentsClient: paymentsClient)
    )
}

// Create a dual-style chat container (renders the selected ChatUIStyle)
public func makeDualStyleChatView(
    conversationID: UUID,
    onRequireSubscription: (() -> Void)? = nil
) -> DualStyleChatView {
    let viewModel = makeChatViewModel(conversationID: conversationID)

    return DualStyleChatView(
        viewModel: viewModel,
        onRequireSubscription: onRequireSubscription
    )
}
```

### ChatViewModel

**What it handles:**

* Message persistence via `messageRepository`
* LLM streaming with cancellation
* Cursor-based pagination (`InfinitePaginator`)
* Error handling and retry (`retryLast()`)
* Loading states
* Free-tier message cap via the injected `paymentsStatusProvider`

### ChatHistoryViewModel

Manages conversation list:

```swift theme={null}
@MainActor
@Observable
public final class ChatHistoryViewModel {
    var conversations: [ConversationDTO]
    var isLoading: Bool

    public func loadConversations() async
    public func createNewConversation() async -> ConversationDTO?
    public func renameConversation(id: UUID, newTitle: String) async
    public func deleteConversation(id: UUID) async
}
```

## Streaming Pattern

Real-time AI response rendering:

```swift theme={null}
// In ChatViewModel.send(): accumulate streamed chunks into the message
var accumulatedText = ""
for try await chunk in llmClient.streamResponse(messages: messages) {
    accumulatedText += chunk
    messages[index].text = accumulatedText  // UI updates via @Observable
}
```

**Benefits:**

* ✅ Low latency (first token fast)
* ✅ Better UX (gradual appearance)
* ✅ Cancellable generation
* ✅ Memory efficient

## Pagination

Efficient infinite scroll for chat history:

```swift theme={null}
// InfinitePaginator handles:
// - Cursor-based pagination (MessageCursor)
// - Reverse chronological order
// - Prefetch before the user hits the end
// - State tracking (idle / loadingMore / endReached / error)

@MainActor
public final class InfinitePaginator {
    public init(pageSize: Int = 50, prefetchThreshold: Int = 5)

    public private(set) var state: State

    public func shouldLoadMore(visibleIndex: Int, totalCount: Int) -> Bool
    public func loadNext(
        using loader: (MessageCursor?) async throws -> (items: [MessageDTO], next: MessageCursor?)
    ) async -> Result<[ChatMessage], AppError>
    public func reset()
}
```

## Customization Examples

### Change Chat Colors

```swift theme={null}
// Bubble colors resolve through DSColors (Packages/DesignSystem):
//   DSColors.bubbleUserOrFallback      -> AccentPrimary colorset
//   DSColors.bubbleAssistantOrFallback -> Surface colorset
//
// Edit those colorsets in
// Packages/DesignSystem/Sources/DesignSystem/Resources/Assets.xcassets
// and both chat styles update automatically.
```

### Add Message Actions

```swift theme={null}
// Add a context menu to MessageRow in ChatView.
// Copy works against the existing ChatMessage.text.
// Regenerate/Delete are methods you add to ChatViewModel yourself —
// they are not shipped on the view model.
.contextMenu {
    Button("Copy", systemImage: "doc.on.doc") {
        UIPasteboard.general.string = message.text
    }
    // Example extension points to implement on ChatViewModel:
    // Button("Regenerate", systemImage: "arrow.clockwise") { ... }
    // Button("Delete", systemImage: "trash", role: .destructive) { ... }
}
```

### Add Custom AI Persona

```swift theme={null}
// In ChatViewModel. LLMMessage.role is a String: "user" | "assistant" | "system".
let systemPrompt = LLMMessage(
    role: "system",
    content: """
    You are a Swift expert.
    Provide clear answers with code examples.
    """
)

let messages = [systemPrompt] + history + [userMessage]
```

### Conversation search

Search ships as client-side filtering in `ChatHistoryView` (no full-text message search).
It matches conversation title and persona name:

```swift theme={null}
// ChatHistoryView.filteredConversations
viewModel.conversations.filter { conversation in
    conversation.title.localizedCaseInsensitiveContains(searchText) ||
    (conversation.personaName?.localizedCaseInsensitiveContains(searchText) ?? false)
}
```

## UI Components

| Component           | Package      | Purpose                                           |
| ------------------- | ------------ | ------------------------------------------------- |
| `ChatView`          | FeatureChat  | Bubble-style chat interface                       |
| `ChatGPTStyleView`  | FeatureChat  | Centered-style interface                          |
| `DualStyleChatView` | FeatureChat  | Container that renders the selected `ChatUIStyle` |
| `MessageRow`        | FeatureChat  | Bubble-style message row                          |
| `ChatHistoryView`   | FeatureChat  | Conversation list                                 |
| `ChatRowCard`       | FeatureChat  | Conversation row                                  |
| `ChatSearchBar`     | FeatureChat  | Search input                                      |
| `EmptyStateView`    | FeatureChat  | No conversations state                            |
| `SAIInputBar`       | DesignSystem | Message composition bar                           |
| `ChatBubble`        | DesignSystem | Reusable message bubble                           |

## Key Files

| Component  | Location                                                     |
| ---------- | ------------------------------------------------------------ |
| ViewModels | `Packages/FeatureChat/Sources/FeatureChat/ViewModels/`       |
| Views      | `Packages/FeatureChat/Sources/FeatureChat/Views/`            |
| Components | `Packages/FeatureChat/Sources/FeatureChat/Views/Components/` |
| Paginator  | `Packages/FeatureChat/Sources/FeatureChat/Paginator/`        |

## Dependencies

* **Core** - Error handling, logging
* **Storage** - Conversation and message persistence
* **DesignSystem** - UI components and tokens
* **Localization** - Localized error messages (`AppError.localizedUserMessage`)

<Warning>
  FeatureChat does **not** depend on AI. It's the other way around: `LLMClient` and
  `LLMMessage` live in FeatureChat, and the **AI** package re-exports FeatureChat
  (`@_exported import FeatureChat`). Removing chat without first relocating those types
  breaks `Packages/AI`. See the per-module removal notes in
  `docs/checklists/APP_STORE_4_3_HARDENING.md`.
</Warning>

## Used By

* **AI** - Re-exports FeatureChat; `ProxyLLMClient` (in `Packages/AI`) conforms to `LLMClient`. The dev-fallback `EchoLLMClient` (app target, `Composition/LLMClientFactory.swift`) also conforms to `LLMClient`
* **Main App** - Primary feature
* **CompositionRoot** - Factory methods for ViewModels

## Best Practices

<AccordionGroup>
  <Accordion title="ViewModel Design">
    * @MainActor for UI updates
    * @Observable for state
    * Async/await for operations
    * Handle all error cases
  </Accordion>

  <Accordion title="Streaming">
    * Update UI incrementally
    * Show typing indicator
    * Support cancellation
    * Handle interruptions
  </Accordion>

  <Accordion title="Performance">
    * Paginate messages
    * Lazy load conversations
    * Compress images
    * Cancel tasks on dismiss
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Full Documentation" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/modules/Feature.Chat.md">
    Find complete FeatureChat guide in your project
  </Card>

  <Card title="UI Styles Guide" icon="palette" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/Packages/FeatureChat/CHAT_UI_STYLES.md">
    Find complete Chat UI patterns guide in your project
  </Card>

  <Card title="AI Module" icon="brain" href="/pages/modules/ai">
    LLM integration
  </Card>

  <Card title="Building Guide" icon="hammer" href="/pages/guides/building-your-app">
    Customize chat
  </Card>
</CardGroup>

## Build with AI (fast)

You can customize this module in minutes using our ready-to-paste LLM prompts.

### Example Prompt

Context: `Packages/FeatureChat/**`
Prompt:
"Refactor chat UI to centered layout using DS spacing/tokens. Add toggle in Settings. Update tests."

### Example Output

```swift theme={null}
struct TypingIndicatorView: View {
  @State private var isVisible = false
  var body: some View { /* minimal dots animation */ }
}
// TODO: drive from ChatMessage.isStreaming / ChatViewModel.isSending (throttle: 600ms)
```

See all prompts → /docs/prompts/Feature.Chat.prompts.md\
See in project: `docs/modules/Feature.Chat.md`

## Test Coverage

The `FeatureChatTests` target runs as part of the workspace suite — **\~598 tests across 12
package test targets + the app test suites**, all in one `Boilerplate.xctestplan` run.

FeatureChat tests cover:

* Message sending
* Streaming responses
* Pagination
* Conversation management
* UI rendering
* Error scenarios


# Feature Settings Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/feature-settings

The **FeatureSettings** module provides settings management and beautiful paywall UI.

<Info>
  **Complete technical documentation:** See `docs/modules/Feature.Settings.md` in the project.
</Info>

## What's new in v2.2

* **`SettingsView.swift` is a ≤ 125-line composition root.** Every section lives in its own file under `Views/Settings/*.swift` (appearance, privacy, notifications, subscription, legal, AI, accessibility, about, and so on). Account sign in/out is handled in the view-model code (`ViewModels/SettingsViewModel+Account.swift`), not a standalone section view. The public entry point is unchanged; downstream customisations that used to edit one giant file now edit the matching section file.
* **Localized error surface.** Error call sites in this module use `AppError.localizedUserMessage` (en + es) from the Localization package, which FeatureSettings now links directly.
* **Paywall CTAs use the standard system styles**: `.buttonStyle(.borderedProminent)` for the primary CTA and `.bordered` for the secondary. If you were styling paywall buttons via `.background()`, switch to `.tint(YourColor)` on the standard styles so Liquid Glass handles the surface correctly on iOS 26.
* Profile, EmailSignUp, and related screens in the app target were split the same way. Check the `SwiftAIBoilerplatePro/AppShell/Profile/` and `SwiftAIBoilerplatePro/AppShell/Auth/` subfolders if a previous customisation disappears from the top-level file.

## Purpose

FeatureSettings module handles:

* **Settings UI** - User preferences management
* **Paywall** - Beautiful subscription screen
* **Theme Selection** - 5 built-in themes
* **Privacy Controls** - Diagnostics, notifications
* **Account Management** - Sign out, delete account

## Key Components

### SettingsViewModel

Manages app-wide settings:

```swift theme={null}
@MainActor
@Observable
public final class SettingsViewModel {
    public var theme: SettingsDTO.Theme
    public var shareDiagnostics: Bool
    public var notificationsEnabled: Bool
    public var hapticsEnabled: Bool
    public var reduceMotion: Bool
    public var isSubscribed: Bool

    public func setTheme(_ newTheme: SettingsDTO.Theme) async
    public func toggleDiagnostics(_ enabled: Bool) async
    public func signOut() async
}
```

### PaywallViewModel

Manages subscription purchases:

```swift theme={null}
@MainActor
@Observable
public final class PaywallViewModel {
    public var offerings: [PaymentsOffering]
    public var selectedOffering: PaymentsOffering?
    public var isLoading: Bool
    public var errorMessage: String?
    public var isSubscribed: Bool

    public func selectOffering(_ offering: PaymentsOffering)
    public func purchase() async
    public func restore() async
}
```

## Settings Categories

<AccordionGroup>
  <Accordion title="Appearance">
    **Theme Selection** (`SettingsDTO.Theme`):

    * System (follows iOS)
    * Light (always light)
    * Dark (always dark)
    * Aurora (premium light theme)
    * Obsidian (premium dark theme)

    Changes apply instantly. Aurora and Obsidian are flagged `isPremium`.
  </Accordion>

  <Accordion title="Privacy & Diagnostics">
    **User Controls:**

    * Share diagnostics (opt-in crash/usage reporting)

    Notification permissions live in their own Notifications section; account deletion is handled by the app-level Account flow.
  </Accordion>

  <Accordion title="Account & Subscription">
    **Management:**

    * Pro status / "Go Pro" and Restore Purchases (Subscription section)
    * Manage Subscription (App Store, from the paywall)
    * Sign in / Sign out (Auth)
    * Account deletion (app-level Account flow)
  </Accordion>

  <Accordion title="Legal">
    **Links:**

    * Privacy Policy
    * Terms of Service
    * Subscription Terms
    * App version display
  </Accordion>
</AccordionGroup>

## Paywall UI

Beautiful subscription screen with:

* ✅ Feature comparison
* ✅ Pricing display
* ✅ Monthly and annual options
* ✅ Clear CTAs
* ✅ Terms and privacy links
* ✅ Restore purchases button

## Customization Examples

### Add New Setting

```swift theme={null}
// 1. Add the field to the persisted SwiftData model (theme is stored as a String)
@Model
public final class Settings {
    public var theme: String
    public var shareDiagnostics: Bool
    public var autoSaveChats: Bool = true  // New setting
}

// 2. Add it to the SettingsDTO so the repository can load/save it
public struct SettingsDTO: Sendable, Equatable {
    public let autoSaveChats: Bool  // New setting
}

// 3. Add to ViewModel and persist via the repository's save(_:)
@Observable
public final class SettingsViewModel {
    public var autoSaveChats: Bool = true

    public func toggleAutoSave(_ enabled: Bool) async {
        autoSaveChats = enabled
        // load the current DTO, set the new value, then save the updated copy
    }
}

// 4. Add to UI
Toggle("Auto-save Chats", isOn: $viewModel.autoSaveChats)
    .onChange(of: viewModel.autoSaveChats) {
        Task { await viewModel.toggleAutoSave($0) }
    }
```

### Customize Paywall

```swift theme={null}
// In PaywallView, edit the feature list — each row is a FeatureRow
// (FeatureRow lives in PaywallView+Components.swift):
FeatureRow(icon: "sparkles", title: "Advanced AI", description: "Get smarter responses with enhanced models")
FeatureRow(icon: "bolt.fill", title: "Faster Processing", description: "Priority queue for quicker results")
FeatureRow(icon: "infinity", title: "Unlimited Usage", description: "No daily limits or restrictions")
FeatureRow(icon: "star.fill", title: "Your Feature", description: "Describe the benefit")  // Add your feature
```

### Add Custom Theme

```swift theme={null}
// 1. Add a color set in Packages/DesignSystem/Sources/DesignSystem/Resources/Assets.xcassets
// 2. Add a case to SettingsDTO.Theme (in the Storage package)
public enum Theme: String, Sendable, Equatable, CaseIterable {
    case system, light, dark, aurora, obsidian
    case custom  // New theme
}

// 3. Map the new case in DSColors / ThemePalette (DesignSystem) and in
//    SettingsDTO.Theme's displayName / symbolName / isPremium helpers
// 4. The Appearance picker is CaseIterable-driven, so it picks up the new case automatically
```

## Paywall Best Practices

<Steps>
  <Step title="Clear Value">
    Show exactly what users get:

    * List specific features
    * Highlight most popular plan
    * Show savings (annual vs monthly)
  </Step>

  <Step title="Easy Purchase">
    * Prominent CTAs
    * Clear pricing
    * Both monthly and annual
    * Restore purchases visible
  </Step>

  <Step title="Transparent Terms">
    * Link to subscription terms
    * Link to privacy policy
    * Cancellation policy clear
    * Auto-renewal explained
  </Step>

  <Step title="Handle Errors">
    * Purchase cancelled (don't error)
    * Network failures (retry)
    * Already subscribed (show status)
    * Restore failures (help user)
  </Step>
</Steps>

## Key Files

| Component   | Location                                                                    |
| ----------- | --------------------------------------------------------------------------- |
| ViewModels  | `Packages/FeatureSettings/Sources/FeatureSettings/ViewModels/`              |
| Settings UI | `Packages/FeatureSettings/Sources/FeatureSettings/Views/SettingsView.swift` |
| Paywall UI  | `Packages/FeatureSettings/Sources/FeatureSettings/Views/PaywallView.swift`  |

## Dependencies

* **Core** - Error handling, logging, theme manager
* **Storage** - `SettingsDTO` / `SettingsRepository` persistence
* **Auth** - Sign in / sign out
* **Payments** - Subscription management
* **DesignSystem** - UI components, `DSColors`
* **Localization** - `AppError.localizedUserMessage`, `L10n` strings

## Used By

* **Main App** - Settings tab
* **All features** - Theme observation
* **Profile** - Subscription status

## Best Practices

<AccordionGroup>
  <Accordion title="Settings Persistence">
    * Save immediately on change
    * Use repository pattern
    * Handle errors gracefully
    * Provide feedback
  </Accordion>

  <Accordion title="Paywall UX">
    * Make it beautiful
    * Highlight value
    * Easy to dismiss
    * Test purchase flow
  </Accordion>

  <Accordion title="Privacy">
    * Opt-in for tracking
    * Clear data policies
    * Easy account deletion
    * GDPR compliance
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Full Documentation" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/modules/Feature.Settings.md">
    Find complete FeatureSettings guide in your project
  </Card>

  <Card title="Payments Module" icon="dollar" href="/pages/modules/payments">
    Subscription management
  </Card>

  <Card title="Design System" icon="palette" href="/pages/modules/design-system">
    Theme system
  </Card>

  <Card title="Building Guide" icon="hammer" href="/pages/guides/building-your-app">
    Customize settings
  </Card>
</CardGroup>

## Build with AI (fast)

You can customize this module in minutes using our ready-to-paste LLM prompts.

### Example Prompt

Context: `Packages/FeatureSettings/**`
Prompt:
"Add a Privacy section to Settings that links to the policy page and includes a clear account-data explanation."

See all prompts → `docs/prompts/Feature.Settings.prompts.md`\
See in project: `docs/modules/Feature.Settings.md`

## Test Coverage

FeatureSettings has its own package test target, run as part of \~598 tests across 12 package test targets + the app test suites (one `Boilerplate.xctestplan` run).

Tests include:

* Settings persistence
* Theme switching
* Paywall display
* Purchase flows
* Error handling


# Localization Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/localization

Type-safe localization system with pluralization support for shipping globally-ready iOS apps

Ship globally from day one with a production-ready localization system featuring type-safe string keys and automatic pluralization support.

<Info>
  **Package location:** `Packages/Localization/`
</Info>

## What's new

* **v2.2** — Localized error surface: `AppError.localizedUserMessage` (en + es) lives here in Localization, now linked by the app target, FeatureSettings, and FeatureChat. All UI error call sites resolve user-facing copy through it.
* **v2.0** — `L10n.swift` is a root `enum L10n` plus one `L10n+<Namespace>.swift` per nested enum (`L10n+Auth.swift`, `L10n+Chat.swift`, `L10n+Settings.swift`, and so on). The public API is identical: `L10n.Auth.tagline`, `L10n.Chat.placeholder`, and every other call site compile unchanged.

## Overview

The Localization module provides compile-time safe string access, eliminating missing translation errors before they reach users.

<CardGroup>
  <Card title="Type-Safe Strings" icon="shield-check">
    Compile-time safety catches missing translations
  </Card>

  <Card title="Pluralization" icon="list-ol">
    Automatic plural rules for every language
  </Card>

  <Card title="2 Languages Included" icon="globe">
    English and Spanish out of the box
  </Card>

  <Card title="100+ Strings" icon="message">
    Pre-localized Auth, Chat, Settings, Payments, Errors
  </Card>
</CardGroup>

## Quick Start

### Basic Usage

```swift theme={null}
import Localization

// Type-safe, autocomplete-friendly
Text(L10n.Auth.tagline)           // "Your AI assistant"
Text(L10n.Chat.placeholder)       // "Type a message..."
Text(L10n.Settings.theme)         // "Theme"

// Error messages that make sense
errorLabel.text = L10n.Error.networkOffline
// "You're offline. Please check your internet connection."
```

### Pluralization

Plural forms are driven by `Localizable.stringsdict`, so each language can define its own rules (English ships with `zero`/`one`/`other`; languages like Russian or Arabic can add their full form sets in their own `.stringsdict`):

```swift theme={null}
// English: "5 messages remaining" / "1 message remaining" / "No messages remaining"
Text(L10n.Chat.messagesRemaining(count))
```

## File Structure

```text theme={null}
Packages/Localization/
├── Package.swift
├── README.md
├── Sources/Localization/
│   ├── L10n.swift                # Root enum + locale utilities
│   ├── L10n+Auth.swift           # One file per namespace
│   ├── L10n+Chat.swift
│   ├── L10n+Settings.swift
│   ├── L10n+Payments.swift
│   ├── L10n+Onboarding.swift
│   ├── L10n+Profile.swift
│   ├── L10n+Theme.swift
│   ├── L10n+Common.swift
│   ├── L10n+Error.swift
│   ├── L10n+A11y.swift
│   ├── L10n+AppError.swift       # AppError.localizedUserMessage (v2.2)
│   ├── Localization.swift        # Module entry
│   └── Resources/
│       ├── en.lproj/             # English
│       │   ├── Localizable.strings
│       │   └── Localizable.stringsdict
│       └── es.lproj/             # Spanish
│           └── Localizable.strings
└── Tests/LocalizationTests/
    ├── L10nTests.swift
    └── L10nAppErrorTests.swift
```

## Adding New Languages

Adding a new language takes just minutes:

<Steps>
  <Step title="Copy existing language folder">
    ```bash theme={null}
    cd Packages/Localization/Sources/Localization/Resources
    cp -r en.lproj de.lproj
    ```
  </Step>

  <Step title="Translate strings">
    Edit `de.lproj/Localizable.strings` with German translations. Adapt the copied `Localizable.stringsdict` if the language needs different plural rules.
  </Step>

  <Step title="Build and test">
    Rebuild — the app automatically picks up new languages.
  </Step>
</Steps>

## Adding Custom Strings

### 1. Add to Localizable.strings

```text theme={null}
// en.lproj/Localizable.strings
"myFeature.title" = "My Feature";
"myFeature.subtitle" = "This is my new feature";
```

Add the same keys to every `.strings` file in `Resources/` (e.g. `es.lproj/`).

### 2. Add Type-Safe Key

Create a new `L10n+MyFeature.swift` extension (one namespace per file, matching the v2.0 layout):

```swift theme={null}
// L10n+MyFeature.swift
import Foundation

public extension L10n {
    enum MyFeature {
        public static var title: String {
            String(localized: "myFeature.title", bundle: bundle)
        }

        public static var subtitle: String {
            String(localized: "myFeature.subtitle", bundle: bundle)
        }
    }
}
```

### 3. Use in Your Views

```swift theme={null}
Text(L10n.MyFeature.title)
Text(L10n.MyFeature.subtitle)
```

## Pre-Localized Strings

The module includes 100+ pre-localized strings covering common app needs:

<AccordionGroup>
  <Accordion title="Authentication">
    * Sign in / Sign up labels
    * Password fields
    * Error messages
    * Social login buttons
    * Email confirmation
  </Accordion>

  <Accordion title="Chat">
    * Message placeholders
    * Send button
    * Typing indicators
    * Message status (sent, delivered, read)
    * Error states
  </Accordion>

  <Accordion title="Settings">
    * Section headers
    * Theme options
    * Account settings
    * Privacy options
    * About section
  </Accordion>

  <Accordion title="Payments">
    * Subscription labels
    * Price formatting
    * Purchase buttons
    * Restore purchases
    * Error messages
  </Accordion>

  <Accordion title="Errors">
    * Network errors
    * Authentication errors
    * Permission errors
    * Generic errors
    * Retry prompts
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup>
  <Card title="Always use L10n" icon="check">
    Never hardcode user-facing strings
  </Card>

  <Card title="Test with pseudolocalization" icon="flask">
    Catch layout issues early
  </Card>

  <Card title="Keep strings short" icon="compress">
    Some languages expand 30%+
  </Card>

  <Card title="Avoid string concatenation" icon="ban">
    Use string interpolation instead
  </Card>
</CardGroup>

## Testing

```swift theme={null}
func testLocalizationKeys() {
    // Verify all keys have translations
    XCTAssertFalse(L10n.Auth.tagline.isEmpty)
    XCTAssertFalse(L10n.Chat.placeholder.isEmpty)
    
    // Test pluralization
    XCTAssertEqual(L10n.Chat.messagesRemaining(0), "No messages remaining")
    XCTAssertEqual(L10n.Chat.messagesRemaining(1), "1 message remaining")
    XCTAssertEqual(L10n.Chat.messagesRemaining(5), "5 messages remaining")
}
```

## Related

<CardGroup>
  <Card title="Quick Start" href="/pages/quickstart">
    Run the app before adding more languages
  </Card>

  <Card title="Architecture" href="/pages/architecture">
    Understand module boundaries
  </Card>

  <Card title="Accessibility Module" href="/pages/modules/accessibility">
    VoiceOver and Dynamic Type support
  </Card>

  <Card title="Design System" href="/pages/modules/design-system">
    UI tokens and components
  </Card>
</CardGroup>


# Networking Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/networking

Production-ready async HTTP client with interceptors, retry/backoff, caching, and AppError mapping

The **Networking** module is a production-grade HTTP layer with:

* **A single async `HTTPClient` API** (`send(_:) -> HTTPResponse`)
* **Interceptors** for auth, headers, and retry decisions
* **Configurable retry** (exponential backoff with jitter, `Retry-After` aware)
* **Response caching** (URLCache-backed, with optional synthetic TTL)
* **Error mapping** to the app-wide `AppError` type

<Info>
  Full technical details live in your project at `docs/modules/Networking.md`.
</Info>

## What's new in v2.2.0

* Swift 6 strict-concurrency clean: `HTTPClient`, `HTTPInterceptor`, `TokenProvider`, `HTTPRequest`, and `HTTPResponse` are all `Sendable`; protocol-typed properties use explicit `any`.
* `URLSessionHTTPClient.applySyntheticTTL` guards on a resolvable URL instead of force-unwrapping, so it stays safe under malformed request inputs. No public API change.

## Purpose

Handles:

* **HTTP requests** via a single `HTTPClient.send(_:)` API
* **Cross-cutting concerns** (auth tokens, app/telemetry headers, retry) through interceptors
* **Consistent error handling** by mapping transport and HTTP errors to `AppError`

## Core Abstractions

### HTTPClient Protocol

```swift theme={null}
public protocol HTTPClient: Sendable {
    func send(_ request: HTTPRequest) async throws -> HTTPResponse
}
```

### HTTPRequest

`HTTPRequest` is a concrete `Sendable` value type — there is no per-endpoint protocol to conform to. Build one with a path and method, then layer headers, query, body, and an optional cache policy via the `with…` helpers.

```swift theme={null}
public struct HTTPRequest: Sendable {
    public let path: String
    public let method: HTTPMethod
    public let headers: [String: String]
    public let query: [String: String?]
    public let body: Data?
    public let cachePolicy: CachePolicy?
}

// Build a request
let request = HTTPRequest(path: "/users/123", method: .get)
    .withHeader("Accept", "application/json")
    .withQuery("expand", "profile")

// Send it and decode the body
let response = try await httpClient.send(request)
let user = try JSONDecoder().decode(User.self, from: response.data)
```

`HTTPMethod` covers `.get`, `.post`, `.put`, `.patch`, `.delete`, `.head`, and `.options`.

### HTTPResponse

`send(_:)` returns an `HTTPResponse`, not a decoded model — you decode `response.data` yourself.

```swift theme={null}
public struct HTTPResponse: Sendable {
    public let statusCode: Int
    public let headers: [String: String]
    public let data: Data
    public let requestID: String?      // extracted from X-Request-ID (case-insensitive)

    public var isSuccess: Bool         // 200..<300
    public var isClientError: Bool     // 400..<500
    public var isServerError: Bool     // 500..<600
}
```

## Interceptors

Interceptors conform to `HTTPInterceptor` and are applied in order. Each can mutate the outgoing `URLRequest` (`adapt`) and/or vote on whether a failed attempt should be retried (`shouldRetry`).

```swift theme={null}
public protocol HTTPInterceptor: Sendable {
    func adapt(_ request: inout URLRequest)
    func shouldRetry(
        response: HTTPURLResponse?,
        data: Data?,
        error: Error?,
        attempt: Int
    ) -> RetryDecision   // .noRetry or .retry(after: TimeInterval?)
}
```

Three interceptors ship out of the box:

<Tabs>
  <Tab title="AuthInterceptor">
    **Bearer-token authentication**

    `AuthInterceptor(tokenProvider:)` adds an `Authorization: Bearer {token}` header:

    * Reads the current token from an injected `TokenProvider`
    * Only sets the header if one is not already present (respects manual overrides)
    * Does nothing when `currentToken()` returns `nil`
    * Returns `.noRetry` — token-refresh logic stays in the Auth module to avoid coupling

    The app wires this with `Storage.KeychainTokenProvider`, so tokens come from the secure iOS Keychain.

    ```swift theme={null}
    let authInterceptor = AuthInterceptor(tokenProvider: keychainTokenProvider)
    ```
  </Tab>

  <Tab title="RetryInterceptor">
    **Retry decisions with exponential backoff**

    `RetryInterceptor(policy:)` decides when to retry, while `URLSessionHTTPClient` performs the wait and re-issues the request:

    * Honors the policy's `maxAttempts` (default 3)
    * Retries transient transport errors: timeout, connection lost, host/DNS failures
    * Retries HTTP `408`, `425`, `429`, and `500–599`
    * Honors a server `Retry-After` header; otherwise falls back to backoff
    * Cancellation passes straight through (no retry)

    ```swift theme={null}
    let retryInterceptor = RetryInterceptor(policy: RetryPolicy(maxAttempts: 3))
    ```
  </Tab>

  <Tab title="HeadersInterceptor">
    **Standard app + telemetry headers**

    `HeadersInterceptor(appVersion:platform:deviceModel:extraHeaders:)` adds, only when not already present:

    * `User-Agent` (app version + platform + device model)
    * `X-App-Version`
    * `X-Platform` (default `"iOS"`)
    * `X-Device-Model` (auto-detected on iOS, optional elsewhere)
    * Any `extraHeaders` you pass

    Request-specific headers always take precedence over these defaults.
  </Tab>
</Tabs>

## RetryPolicy

`RetryPolicy` configures the backoff math used between attempts:

```swift theme={null}
public struct RetryPolicy: Sendable {
    public let maxAttempts: Int       // default 3
    public let baseDelay: TimeInterval // default 0.5s
    public let maxDelay: TimeInterval  // default 8.0s
    public let jitter: Double          // 0.0...1.0, default 0.2

    public func nextDelay(for attempt: Int) -> TimeInterval
}
```

Delay is `baseDelay * 2^(attempt-1)`, capped at `maxDelay`, then randomized by ±`jitter`.

## Configuration

The boilerplate wires the client in `CompositionRoot`. Interceptors run in array order (`headers → auth → retry`):

```swift theme={null}
let tokenProvider = KeychainTokenProvider(
    keychain: keychainStore,
    tokenKey: KeychainStore.Keys.authAccessToken
)

let httpClient = URLSessionHTTPClient(
    baseURL: proxyBaseURL,
    session: .shared,
    defaultHeaders: ["Accept": "application/json"],
    interceptors: [
        HeadersInterceptor(appVersion: "1.0.0", platform: "iOS"),
        AuthInterceptor(tokenProvider: tokenProvider),
        RetryInterceptor(policy: RetryPolicy(maxAttempts: 3))
    ]
)
```

When no proxy base URL is configured, the app falls back to an `UnconfiguredHTTPClient` that fails fast instead of silently hitting a placeholder host.

## Customization Examples

### Add a custom request

Because `HTTPRequest` is a value type, a "custom request" is just a factory that returns one:

```swift theme={null}
func createConversationRequest(title: String) throws -> HTTPRequest {
    let body = try JSONEncoder().encode(["title": title])
    return HTTPRequest(path: "/conversations", method: .post, body: body)
        .withHeader("Content-Type", "application/json")
}

let response = try await httpClient.send(createConversationRequest(title: "New Chat"))
let conversation = try JSONDecoder().decode(ConversationDTO.self, from: response.data)
```

### Add a custom interceptor

```swift theme={null}
struct AnalyticsInterceptor: HTTPInterceptor {
    let analytics: AnalyticsClient

    func adapt(_ request: inout URLRequest) {
        analytics.log(event: "api_call", properties: [
            "path": request.url?.path ?? "",
            "method": request.httpMethod ?? ""
        ])
    }

    func shouldRetry(
        response: HTTPURLResponse?,
        data: Data?,
        error: Error?,
        attempt: Int
    ) -> RetryDecision {
        .noRetry
    }
}

// Add it to the client's interceptor array
let interceptors: [any HTTPInterceptor] = [
    headersInterceptor,
    authInterceptor,
    analyticsInterceptor,
    retryInterceptor
]
```

## Error Handling

Transport failures and non-2xx responses are mapped to `Core.AppError` before they reach you:

```swift theme={null}
// Transport errors -> AppError.network(code:message:)
AppError.network(code: -1009, message: "Offline")
AppError.network(code: -1001, message: "Timed out")

// Cancellation
AppError.cancelled

// HTTP status (4xx/5xx) -> AppError.network with the status code,
// using the server's error/message/detail field when present
AppError.network(code: 500, message: "Server error")
```

## Key Files

| Component           | Location                                                            |
| ------------------- | ------------------------------------------------------------------- |
| HTTPClient protocol | `Packages/Networking/Sources/Networking/HTTPClient.swift`           |
| URLSession client   | `Packages/Networking/Sources/Networking/URLSessionHTTPClient.swift` |
| Interceptors        | `Packages/Networking/Sources/Networking/Interceptors/`              |
| Retry policy        | `Packages/Networking/Sources/Networking/Retry/RetryPolicy.swift`    |
| Caching             | `Packages/Networking/Sources/Networking/Caching/`                   |
| AppError mapping    | `Packages/Networking/Sources/Networking/AppError+Networking.swift`  |

## Dependencies

* **Core** — `AppError`, `AppLogger`

## Used By

* **Auth** — Supabase auth calls (`SupabaseAuthAPI`, `SessionManager`)
* **AI** — `ProxyLLMClient` proxy requests to the Supabase Edge Function
* **Your services** — any API client you build on top of `HTTPClient`

## Best Practices

<AccordionGroup>
  <Accordion title="Request Design">
    * Build `HTTPRequest` values with the `with…` helpers
    * Decode `response.data` at the call site
    * Encode bodies with `JSONEncoder` and set `Content-Type`
    * Clear naming (verb + noun) for request factories
  </Accordion>

  <Accordion title="Error Handling">
    * Catch `AppError` from `send(_:)`
    * Let `RetryInterceptor` handle idempotent/transient retries
    * Surface user-facing copy via `AppError.localizedUserMessage`
  </Accordion>

  <Accordion title="Interceptors">
    * Order matters — headers and auth before retry
    * Keep each interceptor focused on one concern
    * Test interceptors in isolation
    * Return `.noRetry` unless the interceptor owns retry logic
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Full Documentation" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/modules/Networking.md">
    Complete Networking guide
  </Card>

  <Card title="Auth Module" icon="shield" href="/pages/modules/auth">
    Uses HTTPClient for API calls
  </Card>

  <Card title="AI Module" icon="brain" href="/pages/modules/ai">
    Uses HTTPClient for the proxy
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    See the networking layer
  </Card>
</CardGroup>

## Test Coverage

The Networking package ships with its own `NetworkingTests` target (client, interceptor ordering, retry policy, caching, URL builder). It runs as one of the 12 package test targets in the suite of **\~598 tests across 12 package test targets + the app test suites**, executed in a single `Boilerplate.xctestplan` pass.


# Payments Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/payments

Production **subscription management** via RevenueCat with **reactive state**, **entitlement checking**, and **beautiful paywall UI**.

<Info>
  **Full technical details** in your project at `/docs/modules/Payments.md`
</Info>

## What You Get

* ✅ **RevenueCat wrapper** - Clean abstraction, no RC types leak
* ✅ **Reactive state** - AsyncStream for subscription changes
* ✅ **Purchase flows** - Buy, restore, cancel with full error handling
* ✅ **Entitlement system** - Single "pro" entitlement (expandable)
* ✅ **Paywall UI** - Beautiful, themeable subscription screen
* ✅ **Thread-safe** - Multi-subscriber support with state replay

**Time saved: 16-24 hours** of RevenueCat integration, state management, paywall UI, and testing.

## Key Components

### PaymentsClient Protocol

```swift theme={null}
public protocol PaymentsClient: Sendable {
    /// Configure the payments system. Call once at app start. Idempotent.
    func configure(_ config: PaymentsConfig) async

    /// Stream of subscription state changes
    func states() -> AsyncStream<PaymentsState>

    /// Get current subscription state immediately (cached)
    func currentState() async -> PaymentsState

    /// Purchase a product by ID
    func purchase(productID: String) async throws

    /// Restore previous purchases, returning the resulting state
    @discardableResult
    func restore() async throws -> PaymentsState

    /// Prefetch offerings for the paywall (optional optimization)
    func prefetchOfferings() async

    /// Get available product offerings with pricing
    func getOfferings() async throws -> [PaymentsOffering]
}
```

### PaymentsState

```swift theme={null}
public struct PaymentsState: Sendable, Equatable {
    public let isSubscribed: Bool
    public let activeEntitlementIDs: Set<String>
    public let expirationDate: Date?
    public let productID: String?
}
```

## Production Setup (From Real Code)

The app entry point builds a `PaymentsConfig` from the generated `AppConfiguration`
(produced at build time from `Config/Secrets.xcconfig`), then hands it to
`CompositionRoot`:

```swift theme={null}
// SwiftAIBoilerplatePro.swift — loadPaymentsConfig()
private func loadPaymentsConfig() throws -> PaymentsConfig {
    #if DEBUG
    // In DEBUG with AUTH_BYPASS=1, return a placeholder config (the mock client gets sample offerings)
    if ProcessInfo.processInfo.environment["AUTH_BYPASS"] == "1" {
        return PaymentsConfig(apiKey: "debug_mode_placeholder_key", entitlementID: "pro")
    }
    #endif

    guard !AppConfiguration.REVENUECAT_API_KEY.isEmpty else {
        throw AppError.validation(message: "Missing REVENUECAT_API_KEY. Add to Config/Secrets.xcconfig")
    }

    return PaymentsConfig(
        apiKey: AppConfiguration.REVENUECAT_API_KEY,
        entitlementID: AppConfiguration.RC_ENTITLEMENT_ID
    )
}
```

`CompositionRoot` constructs the client with that config. In DEBUG with
`AUTH_BYPASS` set, it swaps in `MockPaymentsClient` so the run-with-mocks
experience (and UI tests) works fully offline with sample offerings:

```swift theme={null}
// CompositionRoot.swift
#if DEBUG
if ProcessInfo.processInfo.environment["AUTH_BYPASS"] != "0" {
    self.paymentsClient = PreviewMocks.MockPaymentsClient()
} else {
    self.paymentsClient = Payments.RevenueCatClient(config: paymentsConfig)
}
#else
self.paymentsClient = Payments.RevenueCatClient(config: paymentsConfig)
#endif

// RevenueCatClient automatically:
// - Syncs with App Store
// - Tracks subscription status via the customer info stream
// - Maps RevenueCat receipts to PaymentsState
// - Emits state changes via states() (AsyncStream)
```

### Configuration Files

**Config/Secrets.xcconfig** (copy from `Config/Secrets.example.xcconfig`):

```bash theme={null}
# From RevenueCat Dashboard → Project Settings → API Keys
REVENUECAT_API_KEY = YOUR_RC_KEY

# Entitlement ID from RevenueCat Dashboard
RC_ENTITLEMENT_ID = pro
```

`scripts/update-config.sh` reads these values and regenerates
`SwiftAIBoilerplatePro/Generated/Configuration.swift` (`AppConfiguration`).

**Complete setup:** [RevenueCat Setup Guide](/pages/guides/revenuecat-setup)

## Subscription Flow

### Purchase

```swift theme={null}
// PaywallViewModel.purchase() buys the selected offering
public func purchase() async {
    guard let offering = selectedOffering else {
        errorMessage = "Please select a subscription plan"
        return
    }
    do {
        try await paymentsClient.purchase(productID: offering.id)
        // Success! State updates automatically via states()
    } catch let paymentsError as PaymentsError {
        errorMessage = paymentsError.asAppError().localizedUserMessage
    } catch {
        errorMessage = AppError.from(error).localizedUserMessage
    }
}
```

### Restore

```swift theme={null}
// PaywallViewModel.restore() returns the resulting state directly
public func restore() async {
    do {
        let restoredState = try await paymentsClient.restore()
        isSubscribed = restoredState.isSubscribed
        if !restoredState.isSubscribed {
            errorMessage = "No active subscription found to restore."
        }
    } catch let paymentsError as PaymentsError {
        errorMessage = paymentsError.asAppError().localizedUserMessage
    } catch {
        errorMessage = AppError.from(error).localizedUserMessage
    }
}
```

### Check Entitlement

```swift theme={null}
// Check if user has pro access
let state = await paymentsClient.currentState()
if state.isSubscribed {
    // Show premium features
} else {
    // Show paywall
}
```

## Paywall UI

Beautiful paywall included in FeatureSettings (`PaywallView`). Pass the shared
`PaymentsClient`; the view creates its own `PaywallViewModel`:

```swift theme={null}
// Illustrative paywall presentation — SettingsView triggers `showPaywall`
// and presents PaywallView in a sheet:
if !viewModel.isSubscribed {
    Button("Go Premium") {
        showPaywall = true
    }
}
.sheet(isPresented: $showPaywall) {
    PaywallView(paymentsClient: viewModel.paymentsClientAccessor) {
        showPaywall = false
    }
}
```

## Customization Examples

### Add New Subscription Tier

The paywall renders one `PlanOptionCard` per offering returned by
`getOfferings()`, so adding a tier is mostly a RevenueCat dashboard task — no UI
code needed for the option to appear:

```swift theme={null}
// 1. Create the product in App Store Connect
// 2. Add it to your RevenueCat offering / package
// 3. PaywallViewModel.offerings picks it up; PaywallView renders a
//    PlanOptionCard for it automatically:
ForEach(viewModel.offerings) { offering in
    PlanOptionCard(
        offering: offering,
        isSelected: viewModel.selectedOffering?.id == offering.id,
        onSelect: { viewModel.selectOffering(offering) }
    )
}
```

### Add Usage Limits

Gate free-tier usage on entitlement state. The daily-count check below is a sketch —
the boilerplate's `MessageRepository` does not ship a `todayCount()`; supply your own
counter (e.g. a `@AppStorage` tally or a `page(...)` query you filter by date):

```swift theme={null}
// Pattern: gate a free-tier limit behind the pro entitlement
func canSendMessage(todayCount: () async -> Int) async -> Bool {
    let state = await paymentsClient.currentState()

    if state.isSubscribed {
        return true  // Unlimited for pro
    } else {
        return await todayCount() < 20  // Your own free-tier limit
    }
}
```

### Custom Entitlements

```swift theme={null}
// Multiple entitlements
if state.activeEntitlementIDs.contains("pro") {
    // Pro features
}

if state.activeEntitlementIDs.contains("premium_support") {
    // Priority support
}
```

## Testing

### Sandbox Testing

1. **Create sandbox tester** in App Store Connect
2. **Sign in** on device with sandbox account
3. **Test purchases** - all free in sandbox
4. **Test restore** - verify works correctly

### Mock Client

`PreviewMocks.MockPaymentsClient` conforms to the full `PaymentsClient` protocol
and returns sample offerings, so previews and UI tests run with no App Store
Connect setup:

```swift theme={null}
final class MockPaymentsClient: PaymentsClient, @unchecked Sendable {
    func configure(_ config: PaymentsConfig) {}
    func states() -> AsyncStream<PaymentsState> { /* yields .free */ }
    func currentState() async -> PaymentsState { PaymentsState(isSubscribed: false) }
    func purchase(productID: String) async throws {}
    @discardableResult
    func restore() async throws -> PaymentsState { PaymentsState(isSubscribed: false) }
    func prefetchOfferings() async {}
    func getOfferings() async throws -> [PaymentsOffering] { /* sample monthly + annual */ }
}
```

## Key Files

| Component  | Location                                                                   |
| ---------- | -------------------------------------------------------------------------- |
| Protocol   | `Packages/Payments/Sources/Payments/Protocols/PaymentsClient.swift`        |
| RevenueCat | `Packages/Payments/Sources/Payments/RevenueCat/`                           |
| Paywall UI | `Packages/FeatureSettings/Sources/FeatureSettings/Views/PaywallView.swift` |

## Dependencies

* **Core** - Error handling, logging

## Used By

* **FeatureSettings** - `PaywallView` / `PaywallViewModel` and subscription management
* **App shell** - `ProfileView` reads subscription status
* **Any feature** - Entitlement checking via `currentState()` / `states()`

## Best Practices

<AccordionGroup>
  <Accordion title="Purchase Flow">
    * Show clear pricing
    * Include terms and privacy links
    * Handle cancellation gracefully
    * Provide restore option
    * Test thoroughly in sandbox
  </Accordion>

  <Accordion title="Entitlements">
    * Check server-side (if possible)
    * Cache locally for offline
    * Update on app launch
    * Observe state changes
  </Accordion>

  <Accordion title="UX">
    * Make paywall beautiful
    * Highlight value proposition
    * Show feature comparison
    * Easy to dismiss
    * Clear cancellation policy
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Full Documentation" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/modules/Payments.md">
    Complete Payments guide
  </Card>

  <Card title="RevenueCat Setup" icon="dollar" href="/pages/guides/revenuecat-setup">
    Configuration guide
  </Card>

  <Card title="Feature Settings" icon="gear" href="/pages/modules/feature-settings">
    See paywall UI
  </Card>

  <Card title="Building Guide" icon="hammer" href="/pages/guides/building-your-app">
    Customize subscriptions
  </Card>
</CardGroup>

## Test Coverage

**85%+** for the Payments package (payments are critical). The `PaymentsTests`
target runs as part of the full suite (**\~598 tests across 12 package test targets
plus the app test suites**, one `Boilerplate.xctestplan` run).

Tests include (`PaymentsFlowTests`, `RevenueCatClientTests`, `PaymentErrorScenarioTests`):

* Purchase flows
* Restore purchases
* Entitlement checking
* State management
* Error scenarios
* Subscription expiry

## Build with AI (fast)

You can customize this module in minutes using our ready-to-paste LLM prompts.

### Example Prompt

Context: `Packages/FeatureSettings/**`
Prompt:
"Add a toggle in Settings to show/hide a discounted annual plan on the paywall. Update tests to verify pricing visibility."

See in project: `docs/modules/Payments.md`


# Storage Module
Source: https://docs.swiftaiboilerplate.com/pages/modules/storage

Production-grade data layer with **SwiftData repositories**, **iOS Keychain** for secrets, and **optional cloud sync**.

<Info>
  **Full technical details** in your project at `/docs/modules/Storage.md`
</Info>

## Concurrency notes (v2.2.0)

* **`MessageRepositoryImpl`, `ConversationRepositoryImpl`, and `SettingsRepositoryImpl` are `@MainActor`-pinned.** If downstream code constructs these from a non-main actor, you need an `await` at the construction site. The public protocol API is unchanged.
* Swift 6 strict concurrency across the package.

<Warning>
  If you hit `MainActor-isolated` errors on `ModelContext` after upgrading, it's this change. Build the repository on the main thread or `await` it from a background context.
</Warning>

## What You Get

* ✅ **Repository pattern** - Never expose @Model types to Views
* ✅ **DTO pattern** - Lightweight, Sendable data transfer objects
* ✅ **Keychain wrapper** - Secure, tested token storage
* ✅ **Cursor pagination** - Efficient infinite scroll
* ✅ **Batch operations** - Optimized bulk updates/deletes
* ✅ **Migration framework** - Safe schema evolution
* ✅ **Optional cloud sync** - Supabase integration (feature-flagged)

**Time saved: 16-24 hours** of implementing and testing repositories, pagination, Keychain, and migrations.

## Production Setup (From Real Code)

Here's how the boilerplate **actually** sets up storage in `CompositionRoot.swift`:

```swift theme={null}
// 1. Define schema with all models
let schema = Schema([
    Conversation.self,
    Message.self,
    Settings.self
])

// 2. Create persistent container
let modelConfiguration = ModelConfiguration(
    schema: schema,
    isStoredInMemoryOnly: false  // Persists to disk
)

self.modelContainer = try ModelContainer(
    for: schema,
    configurations: [modelConfiguration]
)

// 3. Create repositories (not exposed directly to Views)
let mainContext = modelContainer.mainContext

self.conversationRepository = ConversationRepositoryImpl(
    modelContext: mainContext
)
self.messageRepository = MessageRepositoryImpl(
    modelContext: mainContext
)
self.settingsRepository = SettingsRepositoryImpl(
    modelContext: mainContext
)

// 4. Keychain for secure token storage
self.keychainStore = KeychainStore(accessGroup: nil)
```

### Key Architecture Decisions

* ✅ **@Model types stay in the data layer** - Views consume DTOs, never `@Model` objects
* ✅ **DTOs are public** - lightweight, Sendable structs
* ✅ **Repositories on @MainActor** - SwiftData requirement
* ✅ **Protocol-based** - easy to test with mocks
* ✅ **Single ModelContext** - thread-safe, no conflicts

## Repository Pattern (Production Implementation)

The boilerplate uses **protocol-based repositories** that return lightweight DTOs:

```swift theme={null}
// Protocol (public API)
public protocol ConversationRepository: Sendable {
    func create(title: String, personaName: String?) async throws -> ConversationDTO
    func rename(id: UUID, title: String) async throws
    func delete(id: UUID) async throws
    func list(limit: Int, after: Date?) async throws -> [ConversationDTO]
}

// DTO (lightweight, Sendable)
public struct ConversationDTO: Identifiable, Sendable, Equatable {
    public let id: UUID
    public let title: String
    public let personaName: String?
    public let createdAt: Date
    public let updatedAt: Date
}

// Implementation (public, @MainActor-isolated)
@MainActor
public final class ConversationRepositoryImpl: ConversationRepository {
    private let modelContext: ModelContext
    
    // Uses SwiftData internally, returns DTOs
    // Full error handling and logging
    // Tested comprehensively
}
```

**Why This Pattern:**

* Views never see @Model types (maintains MVVM boundaries)
* DTOs are Sendable (thread-safe)
* Easy to mock for testing
* Can swap implementations (local, cloud, hybrid)

## Optional Cloud Sync

<Tabs>
  <Tab title="Enable Chat Sync">
    Sync conversations and messages across devices:

    **Setup Guide:** [Chat Sync Setup](/pages/guides/chat-sync)

    1. Run SQL migration
    2. Enable feature flag
    3. Wire up hybrid repositories
    4. Test cross-device sync
  </Tab>

  <Tab title="Enable Photo Sync">
    Store profile photos in Supabase Storage:

    **Setup Guide:** [Profile Photos Setup](/pages/guides/profile-photos)

    1. Create storage bucket
    2. Set RLS policies
    3. Enable in CompositionRoot
    4. Test upload/download
  </Tab>
</Tabs>

## Keychain Storage (Real Implementation)

The boilerplate includes a **production-ready Keychain wrapper** used for all secure storage:

```swift theme={null}
// From actual code - secure token storage
let keychain = KeychainStore(accessGroup: nil)

// Save (used by Auth module for tokens)
try keychain.setString(accessToken, for: KeychainStore.Keys.authAccessToken)
try keychain.setString(refreshToken, for: KeychainStore.Keys.authRefreshToken)

// Retrieve (used by AuthInterceptor for requests)
let token = try? keychain.getString(KeychainStore.Keys.authAccessToken)

// Delete (on sign out)
try? keychain.delete(KeychainStore.Keys.authAccessToken)

// Standard keys (pre-defined)
KeychainStore.Keys.authAccessToken     // "auth_access_token"
KeychainStore.Keys.authRefreshToken    // "auth_refresh_token"
```

**Production Features:**

* ✅ iOS Security framework (kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly)
* ✅ Automatic PII redaction in logs
* ✅ Thread-safe operations
* ✅ Comprehensive error handling
* ✅ Works with AuthInterceptor via `KeychainTokenProvider`

## Customization Examples

### Add New SwiftData Model

```swift theme={null}
// 1. Create model
@Model
class SavedPrompt {
    @Attribute(.unique) var id: UUID
    var title: String
    var content: String
    var category: String?
    var createdAt: Date
}

// 2. Add DTO
struct SavedPromptDTO: Identifiable, Sendable {
    let id: UUID
    let title: String
    let content: String
    let category: String?
    
    init(_ model: SavedPrompt) {
        self.id = model.id
        self.title = model.title
        self.content = model.content
        self.category = model.category
    }
}

// 3. Create repository
protocol SavedPromptRepository: Sendable {
    func create(title: String, content: String) async throws -> SavedPromptDTO
    func list() async throws -> [SavedPromptDTO]
    func delete(id: UUID) async throws
}

// 4. Add to schema in CompositionRoot
let schema = Schema([
    Conversation.self,
    Message.self,
    Settings.self,
    SavedPrompt.self  // Add this
])
```

## Key Files

| Component           | Location                                                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Models              | `Packages/Storage/Sources/Storage/Models/`                                                                                                       |
| Repositories        | `Packages/Storage/Sources/Storage/Repositories/`                                                                                                 |
| Keychain            | `Packages/Storage/Sources/Storage/Keychain/`                                                                                                     |
| Cloud sync (chat)   | `Packages/Storage/Sources/Storage/Repositories/Supabase*Repository.swift`, `HybridConversationRepository.swift`, `HybridMessageRepository.swift` |
| Cloud sync (photos) | `Packages/Storage/Sources/Storage/SupabaseProfilePhotoStorageClient.swift`                                                                       |

## Dependencies

* **Core** - Error handling, logging
* **Networking** - For cloud sync (optional)

## Used By

* **FeatureChat** - Conversation and message storage
* **FeatureSettings** - Settings persistence
* **Auth** - Keychain for tokens
* **App target (profile)** - `ProfilePhotoStorageClient` for profile photos (optional)

## Best Practices

<AccordionGroup>
  <Accordion title="SwiftData">
    * Use DTOs for passing data
    * @MainActor for ModelContext
    * Sendable for repositories
    * Unique IDs with @Attribute(.unique)
  </Accordion>

  <Accordion title="Repositories">
    * Protocol-based design
    * Return DTOs (not @Model objects)
    * Async/await throughout
    * Comprehensive error handling
  </Accordion>

  <Accordion title="Cloud Sync">
    * Offline-first (local writes fast)
    * Background sync (non-blocking)
    * Graceful degradation
    * Optional (feature flag)
  </Accordion>
</AccordionGroup>

## Learn More

<CardGroup>
  <Card title="Full Documentation" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/modules/Storage.md">
    Complete Storage guide
  </Card>

  <Card title="Chat Sync" icon="cloud" href="/pages/guides/chat-sync">
    Enable cross-device sync
  </Card>

  <Card title="Photo Storage" icon="image" href="/pages/guides/profile-photos">
    Enable cloud photos
  </Card>

  <Card title="Building Guide" icon="hammer" href="/pages/guides/building-your-app">
    Add custom models
  </Card>
</CardGroup>

## Test Coverage

`StorageTests` runs as part of the workspace suite — **\~598 tests across 12 package test targets + the app test suites** in one `Boilerplate.xctestplan` pass.

Storage tests cover:

* CRUD operations
* Pagination
* Error scenarios
* Concurrent access
* Keychain operations


# Quick Start
Source: https://docs.swiftaiboilerplate.com/pages/quickstart

Go from zero to a running app in 10 minutes

<Info>
  This guide gets you running **fast**. For a full production setup with real backends, follow the step-by-step instructions in the setup guides.
</Info>

## 1. Prerequisites

Ensure you have:

* ✅ macOS 15+
* ✅ Xcode 26.2+ (iOS 26 SDK, Swift 6.0)
* ✅ 10 minutes

<Note>
  v2.2.0 ships with iOS 26 Liquid Glass. Runtime still supports iOS 17+ thanks to a Material fallback in `SAIGlass`, but the **build** requires Xcode 26.2+. Stuck on older Xcode? Pin the [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0) tag.
</Note>

## 2. Clone and Open

```bash theme={null}
git clone https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution.git
cd SwiftAIBoilerplatePro-Distribution
open SwiftAIBoilerplatePro.xcodeproj
```

<Note>
  Xcode will automatically resolve Swift Package dependencies. Wait \~30 seconds for this to complete.
</Note>

## 3. Run Immediately (No Configuration Needed!)

Press **⌘ + R** in Xcode - that's it!

<Tip>
  The app works immediately with placeholder configuration:

  * **MockAuthClient** - Sign in with any email/password
  * **EchoLLMClient** - AI echoes your messages back
  * All features work for exploration
  * No API keys or setup required
</Tip>

<Note>
  To use real services (Supabase, OpenRouter, RevenueCat), follow the [Production setup path](#production-setup-path) below.
</Note>

## 4. Explore the App

### What You'll See

<Steps>
  <Step title="Onboarding">
    Swipe through 3 onboarding pages → tap "Get Started"
  </Step>

  <Step title="Sign In">
    Tap "Debug Sign In" (or use any email/password in mock mode)
  </Step>

  <Step title="Home Screen">
    See feature cards, quick actions, and subscription status
  </Step>

  <Step title="Chat">
    Tap "Start Chat" → send a message → receive echo response
  </Step>
</Steps>

<Check>
  **Success!** If you can send chat messages, you have a working AI app foundation.
</Check>

## 5. Explore Features

### Try These Flows

**Chat UI Styles:**

* Tap the style switcher icon (top-right in chat)
* Switch between bubble style (WhatsApp) and centered style (ChatGPT)

**Profile:**

* Tap profile icon → edit display name
* Try uploading a photo (iOS 17+ PhotosPicker)
* Check subscription status

**Settings:**

* Open Settings tab
* Try different themes (5 included: System, Light, Dark, Aurora, Obsidian)
* Toggle preferences

**Chat Management:**

* Create multiple conversations
* Rename conversations (long press)
* Delete conversations (swipe left)
* Search conversations

## Verify Everything Works

<AccordionGroup>
  <Accordion title="✅ Authentication">
    * Sign in with any email/password (mock mode)
    * Sign out and sign back in
    * Profile persists across restarts
  </Accordion>

  <Accordion title="✅ Chat">
    * Create conversation
    * Send messages
    * Receive echo responses
    * Switch UI styles
    * Rename/delete conversations
  </Accordion>

  <Accordion title="✅ Profile">
    * Edit display name
    * Upload photo (compresses automatically)
    * View subscription status
  </Accordion>

  <Accordion title="✅ Settings">
    * Change themes (instant update)
    * Toggle preferences
    * All settings persist
  </Accordion>
</AccordionGroup>

## What's Running in Mock Mode

The app automatically detects missing backend configuration and uses mocks:

| Component    | Mock Behavior                           | Production                    |
| ------------ | --------------------------------------- | ----------------------------- |
| **Auth**     | `MockAuthClient` - any credentials work | `SupabaseAuthClient`          |
| **AI**       | `EchoLLMClient` - echoes messages       | `ProxyLLMClient` → OpenRouter |
| **Payments** | `MockPaymentsClient` - simulated states | `RevenueCatClient`            |
| **Storage**  | Local SwiftData                         | Local + optional cloud sync   |

<Info>
  Mock mode is **perfect for**:

  * Learning the codebase
  * UI development
  * Testing without API costs
  * Demo purposes
</Info>

## Next Steps

<Tabs>
  <Tab title="Customize Immediately">
    Jump straight to customization:

    **Change branding (5 minutes):**

    1. App display name: set `appDisplayName` in `Packages/DesignSystem/Sources/DesignSystem/Tokens/BrandConfig.swift` (and the target's Display Name under Xcode → General). Set the bundle ID via `APP_BUNDLE_ID` in `Config/App.xcconfig`.
    2. Colors: Edit `SwiftAIBoilerplatePro/Resources/DesignSystemColors.xcassets`
    3. Icon: Replace in `Assets.xcassets/AppIcon.appiconset`

    [Full customization guide in project →](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/BUILDING_YOUR_APP.md)
  </Tab>

  <Tab title="Understand Architecture">
    Learn how it's built:

    * [Architecture Overview](/pages/architecture)
    * [Module Documentation](/pages/modules/core)
    * [CLAUDE.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/CLAUDE.md) (for AI-assisted dev)
  </Tab>

  <Tab title="Setup Production Backends">
    Connect real services

    1. [Supabase Setup](/pages/guides/supabase-setup) - Auth + AI proxy
    2. [RevenueCat Setup](/pages/guides/revenuecat-setup) - Subscriptions
    3. [Crashlytics Setup](/pages/guides/crashlytics-setup) - Track crashes and bugs in prod
    4. [Chat Sync](/pages/guides/chat-sync) - Optional cloud sync for ChatSync
    5. [Photo Sync](/pages/guides/profile-photos) - Optional cloud sync for Profile Photo

    **Time needed:** \~2.5 hours for full backend setup
  </Tab>
</Tabs>

## Run Tests

Verify everything with the test suite:

```bash theme={null}
# In Xcode
⌘ + U

# Or command line — runs the Boilerplate.xctestplan in one pass
xcodebuild test \
  -scheme SwiftAIBoilerplatePro \
  -testPlan Boilerplate \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2'
```

**Expected:** \~598 tests pass across 12 package test targets + the app test suites (one `Boilerplate.xctestplan` run). ✅

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot find 'Glass' in scope on older Xcode">
    **Cause:** Liquid Glass APIs (`Glass`, `glassEffect`, `GlassEffectContainer`) are iOS 26 SDK symbols. Older toolchains cannot compile them, even behind `#available` checks.

    **Solution:** Upgrade to Xcode 26.2+ (the repo pins `26.3` via `.xcode-version`), or stay on the [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0) tag until you can upgrade.
  </Accordion>

  <Accordion title="Tab bar doesn't minimise on scroll">
    `.tabBarMinimizeBehavior(.onScrollDown)` is iOS 26 only. On iOS 17–25 the `saiTabBarMinimize(_:)` modifier is a no-op and returns the same view. No action needed; behaviour is progressive.
  </Accordion>

  <Accordion title="Dark blobs under my sheets / sheets look opaque">
    **Cause:** You (or downstream code) applied `DSColors.background.ignoresSafeArea()` or `.background(.black)` under the container. These block the Material SwiftUI already provides and fight Liquid Glass on iOS 26.

    **Solution:** Remove the manual background. SwiftUI handles sheet materials for you on iOS 26. See the [Migration Guide](/pages/migration/v1-9-to-v2-0) section "Fighting glass cleanup".
  </Accordion>

  <Accordion title="`any` keyword required everywhere">
    Swift 6 enforces explicit `any` on protocol-typed stored properties and parameters. The boilerplate has been audited for this already; your own types may need updates. See the [Migration Guide](/pages/migration/v1-9-to-v2-0).
  </Accordion>

  <Accordion title="MainActor-isolated error on ModelContext">
    **Cause:** `MessageRepositoryImpl`, `ConversationRepositoryImpl`, and `SettingsRepositoryImpl` are now `@MainActor`-pinned in v2.0.

    **Solution:** Create repositories from the main thread, or `await` when constructing them from a background context.
  </Accordion>

  <Accordion title="App won't build">
    **Solution:**

    ```bash theme={null}
    # Clean and rebuild
    ⌘ + Shift + K
    File → Packages → Reset Package Caches
    ⌘ + B
    ```
  </Accordion>

  <Accordion title="Debug sign-in not appearing">
    **Cause:** Running in Release mode

    **Solution:**

    1. Product → Scheme → Edit Scheme
    2. Run → Build Configuration → **Debug**
    3. Clean and rebuild
  </Accordion>

  <Accordion title="Dependencies won't resolve">
    **Solution:**

    ```bash theme={null}
    File → Packages → Resolve Package Versions
    # If still fails:
    File → Packages → Update to Latest Package Versions
    ```
  </Accordion>
</AccordionGroup>

## Production Setup Path

When you are ready to leave mock mode, set up real services in this order:

<Steps>
  <Step title="Configure Supabase">
    Create the Supabase project, copy `Config/Secrets.example.xcconfig` to `Config/Secrets.xcconfig`, and add your project URL and anon key.

    [Supabase setup guide](/pages/guides/supabase-setup)
  </Step>

  <Step title="Configure authentication providers">
    Keep mock auth while exploring. Set up Apple, Google, and email auth when you are ready for real accounts.

    [Authentication guide](/pages/guides/authentication)
  </Step>

  <Step title="Deploy the AI proxy">
    Add your OpenRouter key to the Supabase Edge Function and deploy the `ai` function so API keys stay server-side.

    [Deployment guide](/pages/guides/deployment#openrouter-setup)
  </Step>

  <Step title="Configure subscriptions">
    Set up RevenueCat products, entitlements, and API keys before testing paywalls.

    [RevenueCat setup guide](/pages/guides/revenuecat-setup)
  </Step>

  <Step title="Add optional production services">
    Add Crashlytics, OneSignal push notifications, chat sync, and profile photos only when your app needs them.

    [Crashlytics](/pages/guides/crashlytics-setup) · [OneSignal](/pages/guides/onesignal-setup) · [Chat Sync](/pages/guides/chat-sync) · [Profile Photos](/pages/guides/profile-photos)
  </Step>
</Steps>

## Quick Reference

### File Locations

```text theme={null}
Config/Secrets.xcconfig               # API keys (gitignored)
SwiftAIBoilerplatePro/AppShell/       # UI screens
SwiftAIBoilerplatePro/Composition/    # DI container
Packages/*/                           # 11 reusable Swift packages + TestSupport (test infra)
```

### Key Files for Customization

| What to Change   | File Location                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------- |
| App display name | `Packages/DesignSystem/Sources/DesignSystem/Tokens/BrandConfig.swift` (`appDisplayName`) |
| App bundle ID    | `Config/App.xcconfig` (`APP_BUNDLE_ID`)                                                  |
| Colors           | `SwiftAIBoilerplatePro/Resources/DesignSystemColors.xcassets/`                           |
| Onboarding       | `AppShell/OnboardingPage.swift`                                                          |
| Home screen      | `AppShell/HomeContent.swift`                                                             |

### Useful Commands

```bash theme={null}
# Run tests with coverage
./scripts/run-tests.sh --coverage --open

# Clean build
⌘ + Shift + K (in Xcode)

# Resolve packages
File → Packages → Resolve Package Versions
```

## What You've Learned

<Check>
  You now have:

  * ✅ A running AI chat app
  * ✅ Working authentication (mock mode)
  * ✅ Functional chat with dual UIs
  * ✅ Profile management
  * ✅ Theme system (5 themes)
  * ✅ Understanding of mock vs production
</Check>

## Ready to Build?

<CardGroup>
  <Card title="Customize" icon="palette" href="/pages/guides/customization">
    Change branding, features, and UI
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/pages/architecture">
    Learn the system design
  </Card>

  <Card title="Deploy" icon="rocket" href="/pages/guides/deployment">
    Ship to production
  </Card>
</CardGroup>

<Tip>
  **Pro tip:** Use the [Building Your App guide](/pages/guides/building-your-app) which includes ready-to-use **LLM prompts** for Cursor/Claude to speed up customization!
</Tip>

<Note>
  The **App Generator** — a standalone macOS app that drives your own coding-agent CLI (Claude Code, Codex, Gemini, or Cursor) to generate a differentiated app from this template — is a separate product (coming soon). See [pricing & license](/pages/reference/license) for details.
</Note>


# Changelog
Source: https://docs.swiftaiboilerplate.com/pages/reference/changelog

Version history and notable changes

All notable changes to SwiftAI Boilerplate Pro.

<Info>
  **Complete changelog:** [CHANGELOG.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/CHANGELOG.md) in the repo
</Info>

## Latest Version

### v2.2.0 - App Store 4.3 Hardening & Swift 6 Substrate - 2026-06-15

**Summary:** Ships a first-party App Store Guideline 4.3(a) playbook (audit gate + checklist + rebrand helper), a machine-readable `template.manifest.json` single source of truth, hero archetype recipes for differentiating apps, a new `TestSupport` package with a unified workspace test plan (\~598 tests in one run), a localized error surface (en + es), single-source app identity, and a production-hardening pass. Same toolchain floor as v2.0: **Xcode 26.2+** (iOS 26 SDK), iOS 17+ runtime.

<CardGroup>
  <Card title="App Store 4.3(a) playbook" icon="shield-check">
    * `scripts/appstore-43-audit.sh` — Release-binary `strings` audit gate; fails on un-rebranded production fingerprints
    * `docs/checklists/APP_STORE_4_3_HARDENING.md` — binary audit, branding map, metadata, Review Notes, module removal
    * `docs/prompts/AppStore4_3Hardening.prompts.md` — prompt packs incl. the must-run starter-fingerprint clearing prompt (`SwiftAI`, `Boilerplate`, `DesignSystem/SAI`)
    * `scripts/rebrand-design-system-prefix.sh` — swaps the `SAI` design-system prefix
  </Card>

  <Card title="template.manifest.json" icon="file-code">
    * Repo-root machine-readable single source of truth
    * Identity surface, module graph (removable packages + couplings), config schema, canonical fingerprint list
    * Differentiation rules, recipes, verification commands
    * Consumed by the audit script + CI; validated by `scripts/validate-template-manifest.sh`
  </Card>

  <Card title="Hero archetype recipes" icon="layout-template">
    * `docs/recipes/hero/`: DashboardGrid, FeedTimeline, MapCanvas, GuidedTaskFlow, ConversationalHome
    * Plus onboarding / paywall / feature recipes (`docs/recipes/onboarding|paywall|features/`)
    * 4.3 differentiation enforced by mandatory archetype selection, not randomness
  </Card>

  <Card title="TestSupport + single test plan" icon="flask">
    * New `TestSupport` package — unified lock-protected `URLProtocolStub`
    * `Boilerplate.xctestplan` rebuilt; scheme now references it
    * \~598 tests across 12 package test targets + the app test suites (one `xcodebuild test` run)
  </Card>

  <Card title="Localized error surface" icon="globe">
    * `AppError.localizedUserMessage` (en + es) in the Localization package
    * Localization now linked by the app target, FeatureSettings, and FeatureChat
    * All UI error call sites migrated
  </Card>

  <Card title="Single-source app identity" icon="fingerprint">
    * Every target's bundle ID + app-group entitlements derive from one `APP_BUNDLE_ID` in `Config/App.xcconfig`
    * Stale upstream fingerprints purged from project metadata
  </Card>
</CardGroup>

**Production hardening:**

* **No `https://api.example.com` fallback.** Production app-linked code fails through an explicit unconfigured-backend HTTP client path instead of a silent placeholder.
* **DEBUG-only mock auth.** `MockAuthClient` and its literals (`Debug User`, `debug-token`) are kept out of Release binaries.
* **Configurable legal URLs.** Legal views point at configured HTTPS legal URLs; `[DATE]` / `[CONTACT EMAIL]` placeholder bodies and generic legal markdown are excluded from the Release bundle.
* **Account deletion.** `AccountDeletionClient` plumbing plus a `supabase/functions/delete-account/` Edge Function template for authenticated deletion.
* **Bundle packaging fix.** The app target no longer copies local `Packages/` source directories or `Boilerplate.xctestplan` into the `.app` bundle as resources.

**Coupling gotcha:** `LLMClient` / `LLMMessage` live in **FeatureChat**, and the **AI** package re-exports FeatureChat. Removing chat without moving those types breaks `Packages/AI` — the 4.3 module-removal notes cover the safe path.

**Toolchain (unchanged from v2.0):** build with **Xcode 26.2+** (iOS 26 SDK / Liquid Glass symbols); `.xcode-version` pins `26.3`. Runtime supports iOS 17+ via the SwiftUI `Material` fallback. Stuck on older Xcode? Stay on [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0).

<Note>
  The macOS **App Generator** — which drives your own coding-agent CLI (Claude Code / Codex / Gemini / Cursor) to produce a differentiated, 4.3-safe app from this template — is now a **separate product with its own repository and license**. It is **not** bundled in the boilerplate and ships no LLM; the manifest, hero recipes, and single-source identity here are the template-side foundation it builds on. It is **coming soon**. See the [license & pricing](/pages/reference/license) page for the pricing model and grandfathered-buyer benefits.
</Note>

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v2.2.0)

***

## Previous Versions

### v2.0.0 - Swift 6 & iOS 26 Liquid Glass - 2026-04-12

**Summary:** Major release. The toolchain floor moves to Xcode 26.2+, the entire codebase builds under Swift 6 strict concurrency, and the DesignSystem ships a Liquid Glass primitive that uses the iOS 26 `Glass` material with an automatic SwiftUI `Material` fallback on iOS 17–25. Every file over 400 lines was split into extension siblings, public APIs intact.

<CardGroup>
  <Card title="iOS 26 Liquid Glass" icon="gem">
    * New `SAIGlass` primitive in DesignSystem
    * `SAIGlassStyle` (`.regular` / `.clear`), `.saiGlass(...)` modifier
    * `SAIGlassContainer` merges adjacent glass surfaces
    * `saiScrollEdgeGlass`, `saiSidebarAdaptable`, `saiTabBarMinimize`
    * Progressive: iOS 26 uses `Glass`, iOS 17–25 falls back to Material
  </Card>

  <Card title="Swift 6 Strict Concurrency" icon="shield-check">
    * `@MainActor`-pinned storage repositories
    * `@Observable` throughout (no `ObservableObject`, no `.onReceive`)
    * Explicit `any` on every protocol-typed property
    * Zero `DispatchQueue.main` in app code
    * Full build under strict concurrency checking
  </Card>

  <Card title="≤ 400-line file rule" icon="scissors">
    * `SessionManager` → `+SignIn`, `+Refresh`, `+Persistence`
    * `L10n.swift` → `L10n+<Namespace>.swift` per enum
    * `SettingsView` → ≤ 125-line root + `Views/Settings/*`
    * `ChatViewModel` → `ChatViewModel+Memory.swift`
    * Public API unchanged; no downstream breakage from the split
  </Card>

  <Card title="Backend + tooling" icon="wrench">
    * New Supabase migration: `20260408000000_fix_conversation_stats_auth`
    * `ai` edge function updated and ready to redeploy
    * Secrets pre-commit hook in `.githooks/`
    * `.xcode-version` pinned to `26.3`
  </Card>
</CardGroup>

**Breaking-ish changes (most have zero call-site impact):**

* **Xcode 26.2+ required.** v2.0 uses iOS 26 SDK symbols; older toolchains cannot compile, even behind `#available`. Stay on [`v1.9.0`](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.9.0) until you can upgrade.
* **Storage repositories are now `@MainActor`.** If downstream code built `MessageRepositoryImpl`, `ConversationRepositoryImpl`, or `SettingsRepositoryImpl` from a non-main actor, add an `await`.
* **`DeepLinkBus` and `ToastCenter` are `@Observable`.** Migrate any `.onReceive($center.currentToast)` to `.onChange(of: center.currentToast)`.
* **Paywall CTAs use standard `.borderedProminent` / `.bordered`.** If you themed them via `.background()`, switch to `.tint()` so Liquid Glass renders correctly.
* **Stop fighting glass.** Remove `.background(DSColors.background)` on SwiftUI containers and `DSColors.background.ignoresSafeArea()` under sheets.

**Upgrade path:** follow [Upgrading from v1.9 to v2.0](/pages/migration/v1-9-to-v2-0). It covers toolchain install, Supabase migration, edge function redeploy, hook setup, downstream customisation reapply, glass cleanup, and paywall theming.

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v2.0.0) | [Migration Guide](/pages/migration/v1-9-to-v2-0)

***

### v1.9.0 - Agent-Optimized Documentation - 2026-03-06

**Summary:** Every package in the boilerplate now has its own README and PROMPTS.md, and CLAUDE.md is environment-aware. Agents get different build instructions depending on whether they run through Xcode MCP or Claude Code in the terminal.

<CardGroup>
  <Card title="Environment-Aware CLAUDE.md" icon="robot">
    * Detects Xcode MCP vs Claude Code CLI automatically
    * Different build instructions per environment
    * File organization patterns and naming conventions
    * Supabase, RevenueCat, OpenRouter integration specifics
    * Expanded anti-patterns (no UIKit, no ObservableObject, no raw URLSession)
  </Card>

  <Card title="Per-Module Documentation" icon="book">
    * READMEs for all 11 packages (3 were missing)
    * PROMPTS.md in every package with 2-4 example prompts
    * Prompts reference actual types, protocols, and patterns
    * DesignSystem, FeatureRating, FeatureSettings now documented
  </Card>
</CardGroup>

**Bugfix:** EchoLLMClient now activates correctly in debug mode. The guard previously checked for "YOUR" in `PROXY_BASE_URL`, but the default placeholder value contains "placeholder" instead. Fixed in both `createLLMClient()` and the `proxyBaseURL` property.

**All tests pass.**

**Upgrade Notes:** Pull the latest and your coding agent will automatically pick up the improved context. No code changes required.

***

### v1.8.0 - Agentic Development - 2026-03-01

**Summary:** CLAUDE.md rewritten for agentic development with Claude Code. New distribution email infrastructure for notifying buyers about updates. Package count corrected to 11 across all files.

<CardGroup>
  <Card title="Agentic Development" icon="wand-magic-sparkles">
    * CLAUDE.md updated for Claude Code workflow
    * FeatureRating and Localization modules documented
    * New guide: Agentic Coding on iOS
    * Package count corrected to 11
  </Card>

  <Card title="Distribution Infrastructure" icon="envelope">
    * Email notification system for version updates
    * Buyer email list with manual and automated capture
    * Paddle webhook integration for new buyers
    * GitHub vs ZIP delivery routing
  </Card>
</CardGroup>

**Upgrade Notes:** Pull the latest to get the updated CLAUDE.md. No code changes required.

***

### v1.7.0 - Smart App Rating Prompts - 2026-02-10

**Summary:** New FeatureRating module for smart, sentiment-based app rating prompts. Track positive and negative user actions, automatically show a beautiful pre-prompt popup at the right moment, and trigger the native App Store review dialog when users are happiest. Includes a `stopAskingAfterRating` flag that permanently stops prompting once a user taps "Rate on App Store".

<CardGroup>
  <Card title="⭐ Smart Rating Engine" icon="star">
    * Sentiment-based scoring with configurable weights
    * Time-based decay for inactive users
    * Cooldowns (30-day default) and yearly limits (3/year)
    * `stopAskingAfterRating` flag (default: true)
    * 25+ unit tests with MockRatingStorage
  </Card>

  <Card title="🎨 Pre-Prompt Popup" icon="window-maximize">
    * Beautiful themed popup before native dialog
    * Fully customizable text, icon, and styling
    * Works across all 5 themes
    * Dark mode and VoiceOver support
    * One-line `.ratingPrompt()` modifier
  </Card>
</CardGroup>

**Quick Integration:**

```swift theme={null}
import FeatureRating

// Record positive actions at key moments
ratingClient.record(.positive("task_done", weight: 2.0))
ratingClient.record(.positive("milestone_reached", weight: 3.0))

// Pre-defined templates
ratingClient.record(.taskCompleted)
ratingClient.record(.purchaseCompleted)

// The system handles the rest: pre-prompt popup + native review dialog
```

**Upgrade Notes:** This feature is optional. Existing code works without changes. The package is already included; customize `RatingConfig` in `CompositionRoot.swift` and add `.record()` calls at key moments.

## [View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.7.0)

### v1.6.0 - Localization & Accessibility Modules - 2026-01-04

**Summary:** New Localization module and comprehensive Accessibility features. Type-safe localization with `L10n` enum and full accessibility support with `A11y` labels and modifiers for building inclusive apps.

<CardGroup>
  <Card title="🌍 Localization Module" icon="globe">
    * New `Localization` Swift Package
    * `L10n` enum with nested namespaces
    * Built-in pluralization via `.stringsdict`
    * English & Spanish included
    * Zero configuration required
  </Card>

  <Card title="♿ Accessibility Features" icon="universal-access">
    * `A11yLabel` struct for type-safe labels
    * `A11y` enum with pre-defined labels
    * 9 new accessibility modifiers
    * `A11yAudit` debug tool
    * Dynamic Type & Reduce Motion support
  </Card>
</CardGroup>

**Localization Usage:**

```swift theme={null}
import Localization

// Type-safe, organized string access
Text(L10n.Auth.tagline)
Text(L10n.Chat.sendButton)

// Pluralization support
Text(L10n.Chat.messagesRemaining(count))
```

**Accessibility Modifiers:**

```swift theme={null}
import DesignSystem

// Apply type-safe accessibility labels
Button("Send") { }
    .saiAccessible(A11y.Chat.sendButton)

// Dynamic Type support
Text("Title")
    .saiScaledFont(.title)

// Respect Reduce Motion
.saiMotionAwareAnimation(.spring())

// High Contrast mode
.saiHighContrastSupport(normal: .secondary, highContrast: .primary)
```

**New Accessibility Modifiers:**

* `.saiAccessible(_:)` - Apply type-safe accessibility labels
* `.saiAccessibilityHidden()` - Hide decorative elements
* `.saiAccessibilityGroup()` - Combine related elements
* `.saiAccessibilityValue(_:)` - Dynamic value announcements
* `.saiAccessibilitySortPriority(_:)` - Custom reading order
* `.saiScaledFont(_:)` - Dynamic Type support
* `.saiMotionAwareAnimation(_:)` - Respect Reduce Motion
* `.saiHighContrastSupport(normal:highContrast:)` - High Contrast mode
* `.saiFocusIndicator(_:)` - Visible focus rings for Switch Control

**Upgrade Notes:** Both features are optional - existing code works without changes. Just import and use when ready.

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.6.0) | [Localization Guide](/pages/modules/localization) | [Accessibility Guide](/pages/modules/accessibility)

***

### v1.5.0 - OneSignal Push Notifications & Session Fix - 2025-12-20

**Summary:** Complete OneSignal push notifications integration and critical fix for session management that was logging users out unexpectedly.

<CardGroup>
  <Card title="🔔 Push Notifications" icon="bell">
    * Complete OneSignal SDK integration
    * Rich notifications (images, buttons, badges)
    * Confirmed delivery analytics
    * Graceful degradation without config
  </Card>

  <Card title="🔴 Critical Session Fix" icon="shield-check">
    * Fixed unexpected logouts after \~1 hour
    * Proper token refresh with retry logic
    * Users stay logged in 7+ days
    * Shows refreshing state during refresh
  </Card>
</CardGroup>

**Session Management Fix:**

| Scenario                | Before (Bug) | After (Fixed)     |
| ----------------------- | ------------ | ----------------- |
| Open app after 2 hours  | ❌ Logged out | ✅ Silent refresh  |
| Open app after 3 days   | ❌ Logged out | ✅ Silent refresh  |
| Open app after 14+ days | ❌ Logged out | ✅ Graceful logout |

**Upgrade Notes:**

* Session fix is automatic - just update
* Push notifications are optional - add `ONESIGNAL_APP_ID` to `Secrets.xcconfig` if needed

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.5.0) | [OneSignal Setup Guide](/pages/guides/onesignal-setup)

***

### v1.4.0 - Bug Fixes & Profile/Settings Restructure - 2025-12-01

**Summary:** Profile is now the main tab with Settings as a sheet, plus critical validation fixes and enhanced RevenueCat error handling.

<CardGroup>
  <Card title="🏗️ UI Restructure" icon="table-layout">
    * Profile is now a main tab
    * Settings accessible via gear icon
    * New 'Already Subscribed' Paywall UI
    * Better subscription status display
  </Card>

  <Card title="🐛 Critical Fixes" icon="wrench">
    * Fixed Sign In/Sign Up validation deadlock
    * Enhanced RevenueCat error handling
    * Better StoreKit error messages
    * Comprehensive purchase flow logging
  </Card>
</CardGroup>

**Sign In/Sign Up Fix:**
Users could get stuck with a disabled submit button due to validation errors that weren't cleared when editing. Now all fields properly clear errors on change.

**Payment Improvements:**

* PaywallViewModel catches `PaymentsError` explicitly
* Better messages for receipt issues, invalid purchases, config problems
* Comprehensive logging for debugging purchase issues

**New Paywall 'Already Subscribed' UI:**

* Success state showing Pro status with checkmark
* Feature list of what Pro users have access to
* `Continue` and `Manage Subscription` buttons

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.4.0)

***

### v1.3.0 - AI-Assisted Development Configurations - 2025-11-18

**Summary:** Comprehensive Cursor AI and Bolt AI configurations for accelerated development with consistent, high-quality code generation.

<CardGroup>
  <Card title="Cursor AI Rules" icon="wand-magic-sparkles">
    * 4 comprehensive `.mdc` rule files
    * Automatic code quality enforcement
    * DesignSystem usage enforced
    * Protocol-based dependencies
    * MVVM architecture patterns
  </Card>

  <Card title="Bolt AI Chat Modes" icon="robot">
    * 12 specialized AI assistants
    * Context-aware development
    * Domain-specific expertise
    * From architecture to deployment
    * Instant mode switching
  </Card>
</CardGroup>

**Key Features:**

* **Cursor Rules (`.cursor/rules/`)**: Architecture enforcement, SwiftUI patterns, DesignSystem usage, modular design
* **Bolt Chat Modes (`.bolt/`)**: iOS Developer, Architecture, SwiftUI, Feature Dev, Integration, Testing, Debug, Performance, Package, Deploy, Accessibility, Documentation
* **Zero Setup**: Works automatically when you open the project
* **SEO Optimized**: Cursor AI, Bolt AI, .MDC rules, AI-assisted iOS development

**Benefits:**

* ✅ Consistent code quality across AI-generated code
* ✅ Automatic adherence to architecture patterns
* ✅ Proper DesignSystem usage (DSColors, DSFonts, DSSpacing)
* ✅ Protocol-based dependencies for testability
* ✅ Comprehensive error handling
* ✅ Swift best practices (async/await, @MainActor, Sendable)

**Example AI Prompts That Work Perfectly:**

```text theme={null}
"Create a new settings view using DesignSystem components"
"Add a profile ViewModel following MVVM pattern"
"Create a new feature package for Notifications"
"Refactor this to use repository pattern"
```

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.3.0) | [Read AI Development Guide](/pages/guides/ai-assisted-development)

***

### v1.2.1 - Device & Archive Build Fixes - 2025-11-18

**Summary:** Critical bug fix for device and App Store archive builds.

<Card title="Bug Fix" icon="wrench">
  Fixed build failures when building for physical devices or creating App Store archives. Preview code now properly excluded from release builds.
</Card>

**Issues Fixed:**

* **Preview Code Errors:** `#Preview` blocks now properly wrapped in `#if DEBUG`
* **Bundle Extension Error:** Moved Bundle extension outside debug block
* **Device Builds:** Can now build for physical devices
* **Archive Builds:** Can now archive for App Store submission

**Files Fixed:**

* `ChatGPTStyleView.swift` - Preview blocks wrapped
* `DualStyleChatView.swift` - Preview blocks wrapped
* `SettingsView.swift` - Bundle extension moved

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.2.1)

***

### v1.2.0 - Authentication & Payments Improvements - 2025-11-17

**Summary:** Enhanced authentication error handling and added RevenueCat StoreKit Configuration support for simulator testing.

<CardGroup>
  <Card title="Authentication" icon="shield">
    * Fixed misleading error messages
    * Improved sign-out navigation
    * Better error context
    * Email confirmation support
  </Card>

  <Card title="RevenueCat" icon="credit-card">
    * StoreKit Configuration added
    * Simulator testing fixed
    * Integration checklist created
    * Comprehensive troubleshooting
  </Card>
</CardGroup>

**Key Changes:**

* **Auth Error Messages:** More specific and helpful error messages instead of generic "Network error occurred"
* **Sign-Out Fix:** Users now immediately return to auth screen when signing out
* **Simulator Testing:** Added StoreKit Configuration file with correct Xcode scheme path
* **Product ID Guidance:** Clear documentation on matching product IDs across all systems
* **Integration Checklist:** New step-by-step verification checklist for RevenueCat setup

**Files Changed:**

* Enhanced error handling in Auth package
* Added `StoreKitConfiguration.storekit` for simulator testing
* Created `REVENUECAT_INTEGRATION.md` checklist
* Updated RevenueCat documentation with new Step 11

[View Release Notes](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/releases/tag/v1.2.0)

***

### v1.1.0 - Documentation & Testing Overhaul - 2025-10-13

**Summary:** Complete documentation restructure with a comprehensive test suite achieving 85-90% coverage.

<CardGroup>
  <Card title="Documentation" icon="book">
    * Single-path approach
    * 60KB+ of guides
    * Example-first
    * LLM-friendly
  </Card>

  <Card title="Testing" icon="flask">
    * Comprehensive test suite added
    * 85-90% coverage
    * CI enforcement
    * Comprehensive error scenarios
  </Card>
</CardGroup>

### Added

**Core Documentation:**

* `README.md` - 10-minute Quick Start
* `docs/INDEX.md` - Central documentation hub
* `docs/foundations/Architecture.md` - System design
* `BUILDING_YOUR_APP.md` - 60KB customization guide with LLM prompts
* `docs/testing-guide.md` - Comprehensive testing guide

**Module Documentation (12 modules):**

* Core, Networking, Storage, Auth, Payments, AI
* FeatureChat, FeatureSettings, DesignSystem
* Composition, plus 3 feature-specific docs

**Migration Guides:**

* Supabase setup (auth + AI proxy)
* RevenueCat setup (subscriptions)
* Chat sync setup (22KB guide)
* Profile photo setup (12KB guide)

**Testing Infrastructure:**

* Comprehensive unit, integration, and UI test coverage across the modules
* CI/CD with coverage enforcement

### Changed

* Documentation structure: Single-path, example-first
* Quick Start reduced from 30 to 10 minutes
* All module docs follow consistent template
* Test coverage increased from \~60% to 85-90%

### Removed

* 18 legacy/duplicate documentation files
* Scattered guides consolidated
* Outdated status tracking docs

## Earlier Versions

### Initial Release - 2024

**Complete boilerplate with:**

* 9 Swift Package modules (now 11 with Localization & FeatureRating; accessibility lives in DesignSystem)
* MVVM architecture
* Dual-style chat UI
* Supabase + RevenueCat integration
* 5 built-in themes
* Comprehensive error handling
* Mock implementations
* Production-ready patterns

## Version Format

We use **semantic versioning**: `MAJOR.MINOR.PATCH`

* **MAJOR** - Incompatible API changes
* **MINOR** - New features (backward compatible)
* **PATCH** - Bug fixes (backward compatible)

## Release Notes

<AccordionGroup>
  <Accordion title="Documentation Overhaul (Oct 2025)">
    **Focus:** Developer experience

    **Key improvements:**

    * 60KB customization guide with LLM prompts
    * Comprehensive test suite with 85-90% coverage
    * CI enforcement prevents regressions
    * Single-path documentation
    * Example-first approach

    **Time saved:** 30+ hours of documentation reading time
  </Accordion>

  <Accordion title="Initial Release (2024)">
    **Focus:** Production-ready foundation

    **Key features:**

    * Complete iOS app architecture
    * AI chat with 500+ models
    * Authentication (Supabase + Apple)
    * Subscriptions (RevenueCat)
    * Design system with 5 themes
    * Testing infrastructure
    * Comprehensive documentation

    **Time saved:** 400+ hours of development
  </Accordion>
</AccordionGroup>

## Upcoming

<Note>
  The macOS **App Generator** is the next product on the roadmap — a separate, standalone tool that drives your own coding-agent CLI to produce a differentiated, App Store Guideline 4.3-safe app from this template. It is **coming soon** with its own repository and license. See the [license & pricing](/pages/reference/license) page for details and grandfathered-buyer benefits.
</Note>

## Migration Guides

When upgrading between versions:

<Steps>
  <Step title="Read Changelog">
    Check what changed in the new version.
  </Step>

  <Step title="Update Dependencies">
    In Xcode: **File → Packages → Update to Latest Package Versions**.
  </Step>

  <Step title="Run Tests">
    One pass covers the whole workspace via `Boilerplate.xctestplan`:

    ```bash theme={null}
    ./scripts/run-tests.sh
    ```
  </Step>

  <Step title="Fix Breaking Changes">
    Follow the migration notes for your version.
  </Step>
</Steps>

## View Complete Changelog

<Card title="View Complete Changelog" icon="book" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/CHANGELOG.md">
  Complete version history with detailed change notes
</Card>

## Related

<CardGroup>
  <Card title="Features" href="/pages/reference/features">
    Complete feature list
  </Card>

  <Card title="Architecture" href="/pages/architecture">
    System design
  </Card>

  <Card title="Building Guide" href="/pages/guides/building-your-app">
    Customization guide
  </Card>

  <Card title="Testing" href="/pages/guides/testing">
    Testing guide
  </Card>
</CardGroup>


# Configuration Reference
Source: https://docs.swiftaiboilerplate.com/pages/reference/config

Config keys, secrets files, and the generated Configuration.swift for SwiftAI Boilerplate Pro v2.2.0

The full config schema is machine-readable in `template.manifest.json` (repo root) under `configSchema`. The keys below are the authoritative source consumed by the app and the `scripts/appstore-43-audit.sh` gate.

## Config Keys

| Key                  | Type   | Required | Secret | Purpose                                               |
| -------------------- | ------ | -------- | ------ | ----------------------------------------------------- |
| `SUPABASE_URL`       | url    | Yes      | No     | Supabase project URL (auth + backend)                 |
| `SUPABASE_ANON_KEY`  | string | Yes      | Yes    | Supabase anonymous key                                |
| `REVENUECAT_API_KEY` | string | No       | Yes    | RevenueCat public SDK key                             |
| `RC_ENTITLEMENT_ID`  | string | No       | No     | RevenueCat entitlement identifier                     |
| `PROXY_BASE_URL`     | url    | No       | No     | AI proxy base URL; `EchoLLMClient` is used when empty |
| `PROXY_PATH`         | string | No       | No     | AI proxy path                                         |
| `ONESIGNAL_APP_ID`   | string | No       | Yes    | OneSignal push app ID                                 |

## Configuration Files

### Config/Secrets.xcconfig

**Location:** `Config/Secrets.xcconfig` (gitignored)

<Warning>
  This file contains API keys and secrets. Never commit it to git.
</Warning>

**Template:** `Config/Secrets.example.xcconfig` (copy this to get started)

```bash theme={null}
# Supabase Configuration
SUPABASE_URL = https://YOUR-PROJECT-REF.supabase.co
SUPABASE_ANON_KEY = YOUR_PUBLIC_ANON_KEY

# Google Sign In (Optional)
# GOOGLE_CLIENT_ID = YOUR_IOS_CLIENT_ID.apps.googleusercontent.com

# RevenueCat Configuration
REVENUECAT_API_KEY = YOUR_RC_KEY
RC_ENTITLEMENT_ID = pro

# AI Proxy Configuration (Supabase Edge Function)
PROXY_BASE_URL = https://YOUR-PROJECT-REF.supabase.co/functions/v1
PROXY_PATH = /ai

# OneSignal Push Notifications (Optional)
ONESIGNAL_APP_ID = YOUR_ONESIGNAL_APP_ID
```

**Generate Configuration.swift:**

```bash theme={null}
# After filling in Config/Secrets.xcconfig, run:
bash scripts/update-config.sh
```

This regenerates `SwiftAIBoilerplatePro/Generated/Configuration.swift` (the `AppConfiguration` enum) with your values. Keys whose value still contains a `YOUR` placeholder are written as a comment and treated as "not configured" at runtime.

### Config/App.xcconfig

**Location:** `Config/App.xcconfig`

General app-level build settings, including the single source of truth for app identity. Every target's bundle ID and the app-group entitlements derive from `APP_BUNDLE_ID`.

```bash theme={null}
PRODUCT_NAME = $(TARGET_NAME)

# Single source of truth for app identity. Test, UI-test, and extension
# bundle IDs plus the app-group entitlements all derive from this value.
APP_BUNDLE_ID = com.berkin.SwiftAIBoilerplatePro
SWIFT_VERSION = 6.0
IPHONEOS_DEPLOYMENT_TARGET = 17.0
ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor

# Include secrets if present (local only)
#include? "Config/Secrets.xcconfig"
```

## Environment Variables

Set in **Xcode Scheme** → Edit Scheme → Run → Arguments → Environment Variables.

| Variable                | Reads in   | Default behavior            | Purpose                                                                                                        |
| ----------------------- | ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `AUTH_BYPASS`           | DEBUG only | Mock used unless set to `0` | Set `0` to use the real Supabase auth client (and `MockPaymentsClient` is also swapped for `RevenueCatClient`) |
| `DIAGNOSTICS_ENABLED`   | RELEASE    | `false`                     | Set `true` to enable diagnostics in Release                                                                    |
| `CRASHLYTICS_ENABLED`   | RELEASE    | `false`                     | Set `true` to enable Firebase Crashlytics in Release                                                           |
| `CHAT_SYNC_ENABLED`     | RELEASE    | `false`                     | Set `true` to enable Supabase chat history sync in Release                                                     |
| `PROXY_DEFAULT_HEADERS` | Any        | none                        | Optional JSON string of extra headers for the AI proxy                                                         |

The mock-vs-real auth decision is made in `CompositionRoot.swift` from `AUTH_BYPASS`, not in `FeatureFlags`. In RELEASE the app always uses real auth; the `MockAuthClient` is DEBUG-only.

## Feature Flags

**Location:** `SwiftAIBoilerplatePro/Composition/FeatureFlags.swift`

```swift theme={null}
import Foundation

/// Feature flags for optional capabilities
public struct FeatureFlags {
    /// Master switch for diagnostics (MetricKit always enabled)
    public static var diagnosticsEnabled: Bool {
        #if DEBUG
        return true
        #else
        return ProcessInfo.processInfo.environment["DIAGNOSTICS_ENABLED"] == "true"
        #endif
    }

    /// Enable Firebase Crashlytics
    public static var crashlyticsEnabled: Bool {
        #if DEBUG
        return false // Off by default in debug
        #else
        return ProcessInfo.processInfo.environment["CRASHLYTICS_ENABLED"] == "true"
        #endif
    }

    /// Enable Supabase chat history sync
    /// When false (default), chat data stays local-only in SwiftData.
    /// See docs/CHAT_SYNC_SETUP.md for setup instructions.
    public static var chatSyncEnabled: Bool {
        #if DEBUG
        return false // Off by default in debug
        #else
        return ProcessInfo.processInfo.environment["CHAT_SYNC_ENABLED"] == "true"
        #endif
    }
}
```

## Backend Configuration

### Supabase

<Tabs>
  <Tab title="Development">
    ```bash theme={null}
    SUPABASE_URL = https://dev-project.supabase.co
    SUPABASE_ANON_KEY = dev_anon_key
    PROXY_BASE_URL = https://dev-project.supabase.co/functions/v1
    ```
  </Tab>

  <Tab title="Production">
    ```bash theme={null}
    SUPABASE_URL = https://prod-project.supabase.co
    SUPABASE_ANON_KEY = prod_anon_key
    PROXY_BASE_URL = https://prod-project.supabase.co/functions/v1
    ```
  </Tab>
</Tabs>

**Get credentials:** [Supabase Dashboard](https://app.supabase.com) → Project Settings → API

### OpenRouter

**Set as Supabase secret:**

```bash theme={null}
supabase secrets set OPENROUTER_API_KEY=sk-or-v1-YOUR_KEY
```

**Get key:** [OpenRouter Dashboard](https://openrouter.ai/keys)

### RevenueCat

```bash theme={null}
REVENUECAT_API_KEY = appl_YOUR_PUBLIC_KEY
RC_ENTITLEMENT_ID = pro
```

**Get key:** [RevenueCat Dashboard](https://app.revenuecat.com) → Settings → API Keys

## CompositionRoot Configuration

**Location:** `SwiftAIBoilerplatePro/Composition/CompositionRoot.swift`

The DI container reads configuration from the generated `AppConfiguration` enum and chooses real or mock implementations. The LLM client is selected by `createLLMClient(...)` in `LLMClientFactory.swift`:

```swift theme={null}
// Auth: real Supabase + Apple + Email, or MockAuthClient in DEBUG (CompositionRoot.swift)
#if DEBUG
let shouldUseMock = ProcessInfo.processInfo.environment["AUTH_BYPASS"] != "0"
if shouldUseMock {
    self.sessionManager = Auth.MockAuthClient()
} else {
    self.sessionManager = SessionManagerWrapper(/* Supabase SessionManager */)
}
#endif

// LLM: ProxyLLMClient when PROXY_BASE_URL is real, EchoLLMClient otherwise (LLMClientFactory.swift)
guard let baseURL = URL(string: AppConfiguration.PROXY_BASE_URL),
      !AppConfiguration.PROXY_BASE_URL.contains("YOUR"),
      !AppConfiguration.PROXY_BASE_URL.contains("placeholder") else {
    return EchoLLMClient()
}
return ProxyLLMClient(baseURL: baseURL, httpClient: httpClient, path: AppConfiguration.PROXY_PATH)
```

When `PROXY_BASE_URL` is unconfigured the app also wires an `UnconfiguredHTTPClient` instead of a real `URLSessionHTTPClient`, so unconfigured backends fail explicitly rather than calling a placeholder host.

## Xcode Build Configuration

### Debug vs Release

**Debug (default):**

* Mock auth enabled by default
* Detailed logging
* Crashlytics disabled
* No optimization

**Release:**

* Real auth required
* Production logging
* Crashlytics opt-in (requires `CRASHLYTICS_ENABLED=true` and a `GoogleService-Info.plist`)
* Full optimization

**Switch configuration:**

```text theme={null}
Product → Scheme → Edit Scheme → Run → Build Configuration
```

## Quick Reference

<AccordionGroup>
  <Accordion title="Enable Real Auth in DEBUG">
    1. Edit Scheme → Run → Environment Variables
    2. Set `AUTH_BYPASS` = `0`
    3. Fill in `Config/Secrets.xcconfig` with real Supabase credentials
    4. Run `bash scripts/update-config.sh`
    5. Clean and rebuild
  </Accordion>

  <Accordion title="Enable Chat Sync">
    1. Run SQL migration
    2. Set `chatSyncEnabled = true` in FeatureFlags
    3. Uncomment Supabase repositories
    4. Wire up in CompositionRoot
  </Accordion>

  <Accordion title="Switch to Production Backend">
    1. Update `Config/Secrets.xcconfig` with production URLs/keys
    2. Run `bash scripts/update-config.sh` to regenerate Configuration.swift
    3. Verify in RELEASE build configuration
    4. Archive and test
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup>
  <Card title="Installation" href="/pages/installation">
    Initial configuration
  </Card>

  <Card title="Supabase Setup" href="/pages/guides/supabase-setup">
    Backend configuration
  </Card>

  <Card title="Building Guide" href="/pages/guides/building-your-app">
    Production configuration
  </Card>

  <Card title="Architecture" href="/pages/architecture">
    How config flows through app
  </Card>
</CardGroup>


# Features Overview
Source: https://docs.swiftaiboilerplate.com/pages/reference/features

Complete inventory of what's included in SwiftAI Boilerplate Pro v2.2.0.

## Quick Stats

* **Swift 6 + iOS 26 Liquid Glass**: v2.2.0 builds under strict concurrency with the iOS 26 SDK (Xcode 26.2+)
* **276+ hours** of development already done
* **\~598 tests** across 12 package test targets + the app test suites, run in one pass
* **11 Swift Packages** cleanly separated for reuse in any iOS project
* **AI-Assisted Development** with Claude Code CLAUDE.md, Cursor AI rules, and Bolt AI chat modes
* **Comprehensive docs** with examples and LLM prompt packs
* **2 chat UIs** (bubble and centered styles)
* **Localization & Accessibility** built-in for global, inclusive apps

## New in v2.2

The v2.2.0 release is built around shipping a *differentiated* app from the template — getting past App Store Review Guideline 4.3(a) ("spam"/duplicate apps) and hardening the codebase for production.

* ✅ **App Store 4.3(a) playbook** — `scripts/appstore-43-audit.sh` runs a Release-binary `strings` audit that fails the build while un-rebranded starter fingerprints (`SwiftAI`, `Boilerplate`, the `SAI` design-system prefix), the starter `BrandConfig.appDisplayName`, placeholder legal URLs, or the starter bundle ID remain. Paired with `docs/checklists/APP_STORE_4_3_HARDENING.md` and prompt packs in `docs/prompts/AppStore4_3Hardening.prompts.md`.
* ✅ **`template.manifest.json`** (repo root) — machine-readable single source of truth for the identity surface, module graph (which packages are removable and their couplings), config schema, canonical fingerprint list, differentiation rules, and verification commands. Consumed by the audit script + CI; validated by `scripts/validate-template-manifest.sh`.
* ✅ **Hero archetype recipes** — `docs/recipes/hero/` ships DashboardGrid, FeedTimeline, MapCanvas, GuidedTaskFlow, and ConversationalHome, plus onboarding/paywall/feature recipes. 4.3 differentiation comes from mandatory archetype selection, not randomness.
* ✅ **`TestSupport` package + single workspace test plan** — a test-only infrastructure package (`URLProtocolStub`) feeds `Boilerplate.xctestplan`, which runs **\~598 tests across 12 package test targets + the app test suites** in one `xcodebuild test`.
* ✅ **Localized error surface** — `AppError.localizedUserMessage` (English + Spanish) in Localization, now linked by the app target, FeatureSettings, and FeatureChat; every UI error call site migrated.
* ✅ **Single-source app identity** — every target's bundle ID and app-group entitlements derive from one `APP_BUNDLE_ID` in `Config/App.xcconfig`; stale upstream fingerprints purged.
* ✅ **Production hardening** — DEBUG-only `MockAuthClient`, configurable HTTPS legal URLs (no placeholder bodies in Release), an explicit unconfigured-backend failure path (no `https://api.example.com` fallback), and account deletion via `AccountDeletionClient` + a `supabase/functions/delete-account/` Edge Function template.

### Still current from v2.0

* ✅ **iOS 26 Liquid Glass** via `SAIGlass` primitive, with automatic `Material` fallback on iOS 17–25
* ✅ **Swift 6 strict concurrency** across every package
* ✅ **`@MainActor`-pinned storage repositories** and `@Observable` view models throughout
* ✅ **≤ 400-line file rule** enforced across the codebase (extension-split siblings)
* ✅ **Secrets pre-commit hook** in `.githooks/`
* ✅ **Xcode 26.3 pin** via `.xcode-version`

See the [v1.9 → v2.0 migration guide](/pages/migration/v1-9-to-v2-0) and the [full changelog](/pages/reference/changelog).

<Note>
  The **App Generator** is a separate, standalone macOS product (coming soon) that drives your own coding-agent CLI to generate a differentiated, 4.3-safe app from this template — it is not bundled in the boilerplate. See the [license & pricing reference](/pages/reference/license) for the full model.
</Note>

## Core Features

### AI-Assisted Development

* ✅ Production-tested `CLAUDE.md` for agentic development with Claude Code
* ✅ 6 comprehensive Cursor AI `.mdc` rule files
* ✅ 12 specialized Bolt AI chat modes
* ✅ Per-module PROMPTS.md with ready-to-paste prompts
* ✅ DesignSystem usage enforced by AI
* ✅ Protocol-based dependencies automatically
* ✅ MVVM architecture patterns followed
* ✅ Swift best practices (async/await, @MainActor, Sendable)
* ✅ Zero setup for all three tools

**Time saved:** 2-3x faster development with consistent quality

### Authentication

* ✅ Email/password via Supabase
* ✅ Sign in with Apple and/or Google, via Supabase
* ✅ Automatic token refresh
* ✅ Secure Keychain storage
* ✅ DEBUG-only `MockAuthClient` for development

**Time saved:** 20-32 hours

### AI Integration

* ✅ Streaming chat responses
* ✅ 500+ models via OpenRouter
* ✅ Secure Edge Function proxy (`ProxyLLMClient` → `supabase/functions/ai/`; key stays server-side)
* ✅ Cancellable requests
* ✅ `EchoLLMClient` dev fallback when `PROXY_BASE_URL` is empty
* ✅ Easily replaceable with your own APIs

**Time saved:** 24-40 hours

### Chat UI

* ✅ Dual UI styles (bubble + centered)
* ✅ Real-time streaming
* ✅ Infinite scroll pagination
* ✅ Conversation management
* ✅ Search and filter

**Time saved:** 40-60 hours

### Subscriptions

* ✅ RevenueCat integration
* ✅ Beautiful paywall UI
* ✅ Monthly and annual plans
* ✅ Entitlement checking
* ✅ Restore purchases

**Time saved:** 16-24 hours

### Design System

* ✅ 5 built-in themes
* ✅ Design tokens (colors, spacing, typography)
* ✅ 10+ UI components
* ✅ Dark mode support
* ✅ Accessibility built-in

**Time saved:** 20-32 hours

### Localization

* ✅ Type-safe strings with compile-time safety
* ✅ Automatic pluralization support
* ✅ 100+ pre-localized strings included
* ✅ English & Spanish out of the box
* ✅ Easy to add new languages

**Time saved:** 12-16 hours

### Accessibility

* ✅ 50+ pre-defined VoiceOver labels
* ✅ Dynamic Type support utilities
* ✅ Reduce Motion helpers
* ✅ High Contrast mode support
* ✅ Debug audit tools

**Time saved:** 14-18 hours

### Data Persistence

* ✅ SwiftData models (iOS 17+)
* ✅ Repository pattern
* ✅ Keychain for secrets
* ✅ Optional cloud sync
* ✅ Offline-first

**Time saved:** 16-24 hours

### Networking

* ✅ HTTP client with interceptors
* ✅ Automatic retry logic
* ✅ Auth token injection
* ✅ Request/response logging
* ✅ Error handling

**Time saved:** 12-20 hours

## Architecture

<CardGroup>
  <Card title="MVVM" icon="diagram-project">
    Clean separation of concerns
  </Card>

  <Card title="Dependency Injection" icon="plug">
    CompositionRoot pattern
  </Card>

  <Card title="Protocol-Oriented" icon="swap">
    Swappable implementations
  </Card>

  <Card title="Async/Await" icon="bolt">
    Modern concurrency
  </Card>

  <Card title="Modular" icon="cubes">
    11 Swift Packages
  </Card>

  <Card title="Testable" icon="flask">
    \~598 tests, CI-enforced coverage
  </Card>
</CardGroup>

**Time saved:** 30-40 hours

## Developer Experience

### Testing

* ✅ \~598 tests across 12 package test targets + the app test suites
* ✅ One `Boilerplate.xctestplan` run covers the whole workspace
* ✅ `TestSupport` package with shared infrastructure (`URLProtocolStub`)
* ✅ CI/CD with GitHub Actions and coverage enforcement
* ✅ Mock implementations throughout

**Time saved:** 32-40 hours

### Documentation

* ✅ 60KB+ of guides
* ✅ 11 module docs
* ✅ Step-by-step setup & integration guides
* ✅ LLM prompts library
* ✅ Troubleshooting sections

### Code Quality

* ✅ SwiftLint configured
* ✅ No force unwraps
* ✅ Files ≤ 400 lines
* ✅ Consistent patterns
* ✅ Comprehensive error handling

## Optional Features

<Tabs>
  <Tab title="Chat Sync">
    **Cross-device conversation sync**

    * Offline-first
    * Background sync
    * Conflict resolution
    * 22KB setup guide

    **Enable when needed** - feature flag controlled
  </Tab>

  <Tab title="Profile Photos">
    **Cloud photo storage**

    * Supabase Storage
    * Automatic compression
    * Cross-device sync
    * 12KB setup guide

    **Enable when needed** - optional configuration
  </Tab>

  <Tab title="Crashlytics">
    **Error reporting**

    * Firebase integration
    * User opt-in
    * Protocol-based
    * Privacy-first

    **Enable when needed** - optional dependency
  </Tab>
</Tabs>

## Value Breakdown

### Time Saved by Category

| Category       | Hours       | What's Included                               |
| -------------- | ----------- | --------------------------------------------- |
| Architecture   | 20-32       | Modular packages, DI, MVVM                    |
| Authentication | 20-32       | Supabase + Apple Sign In                      |
| AI Integration | 24-40       | Streaming, proxy, 500+ models                 |
| Chat UI        | 40-60       | Two interfaces, pagination                    |
| Subscriptions  | 16-24       | RevenueCat, paywall UI                        |
| Design System  | 20-32       | Tokens, components, themes                    |
| Localization   | 12-16       | Type-safe strings, pluralization, 2 languages |
| Accessibility  | 14-18       | VoiceOver, Dynamic Type, Reduce Motion        |
| Data Layer     | 16-24       | SwiftData, repositories                       |
| Networking     | 12-20       | HTTP client, interceptors                     |
| Testing        | 20-32       | \~598 tests, single test plan, CI/CD          |
| Backend        | 20-32       | Edge Function, migrations                     |
| Best Practices | 32-40       | Patterns, security, performance               |
| **TOTAL**      | **276-390** | **Complete production app**                   |

### Cost Savings

**At \$100/hour:**

* Low: 276 hours × $100 = **$27,600\*\*
* High: 390 hours × $100 = **$39,000\*\*

## What Makes This Special

<AccordionGroup>
  <Accordion title="AI-First Design">
    * Architected for AI from day one
    * Streaming (not batch)
    * 500+ models (not locked in)
    * Secure proxy included
  </Accordion>

  <Accordion title="Production-Ready">
    * Not a demo
    * \~598 tests with CI-enforced coverage
    * Professional, localized error handling
    * Security best practices and a Release-binary 4.3 audit gate
  </Accordion>

  <Accordion title="Best Practices">
    * MVVM done right
    * Proper DI (not singletons)
    * Protocol-oriented
    * Modern concurrency
  </Accordion>

  <Accordion title="Documentation">
    * Comprehensive documentation
    * Step-by-step setup instructions
    * LLM prompts included
    * Code examples everywhere
  </Accordion>

  <Accordion title="Modular">
    * 11 independent packages
    * Clear boundaries
    * No circular dependencies
    * Easy to extend
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup>
  <Card title="Architecture" href="/pages/architecture">
    System design overview
  </Card>

  <Card title="Modules" href="/pages/modules/core">
    Module documentation
  </Card>

  <Card title="Building Guide" href="https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/BUILDING_YOUR_APP.md">
    Customization guide, included in your boilerplate
  </Card>

  <Card title="Changelog" href="/pages/reference/changelog">
    Version history
  </Card>
</CardGroup>

## Quick Links

<CardGroup>
  <Card title="Core" href="/pages/modules/core">
    Foundation utilities
  </Card>

  <Card title="Networking" href="/pages/modules/networking">
    HTTP client
  </Card>

  <Card title="Storage" href="/pages/modules/storage">
    SwiftData + Keychain
  </Card>

  <Card title="Auth" href="/pages/modules/auth">
    Authentication
  </Card>

  <Card title="Payments" href="/pages/modules/payments">
    Subscriptions
  </Card>

  <Card title="AI" href="/pages/modules/ai">
    LLM integration
  </Card>

  <Card title="FeatureChat" href="/pages/modules/feature-chat">
    Chat UI
  </Card>

  <Card title="Settings" href="/pages/modules/feature-settings">
    Settings + Paywall
  </Card>

  <Card title="DesignSystem" href="/pages/modules/design-system">
    UI tokens
  </Card>

  <Card title="Localization" href="/pages/modules/localization">
    i18n + Type-safe strings
  </Card>

  <Card title="Accessibility" href="/pages/modules/accessibility">
    VoiceOver + Dynamic Type
  </Card>
</CardGroup>


# License & Pricing
Source: https://docs.swiftaiboilerplate.com/pages/reference/license

SwiftAI Boilerplate Pro licensing, the $99 single-download and $199 lifetime tiers, lifetime-update policy, grandfathered-buyer benefits, and the separate App Generator product (coming soon).

SwiftAI Boilerplate Pro is sold as a **commercial source-code license** — you buy it once, build unlimited apps with it, and ship them commercially. There are no subscriptions or per-seat fees for the boilerplate itself.

<Note>
  Prices and checkout live on the product site. This page documents *what each tier includes* so you can pick the right one. To purchase, use **[swiftaiboilerplate.com/checkout](https://www.swiftaiboilerplate.com/checkout)**.
</Note>

## Choose your tier

<CardGroup>
  <Card title="Single download — $99" icon="download">
    A one-time download link delivered to your email inbox.

    * Full source of the **current** release
    * Commercial use, unlimited apps
    * **No** future versions or update access

    Best for a one-off build where you don't need ongoing updates.
  </Card>

  <Card title="Lifetime — $199" icon="infinity">
    **Most popular.** Buy once, keep getting everything.

    * Full source via private GitHub repo
    * **All future versions**, forever
    * **Lifetime updates** (features, fixes, new modules)
    * App Generator access when it ships

    Best value — the updates and future versions are the whole point.
  </Card>

  <Card title="App Generator — $399" icon="wand-magic-sparkles">
    **Coming soon — separate product.** A standalone macOS app that drives *your own* coding-agent CLI to generate a differentiated, App-Store-4.3-safe app from the template.

    * Ships **no LLM** — it orchestrates Claude Code / Codex / Gemini / Cursor
    * Sold separately from the boilerplate
    * [Join the waitlist](https://www.swiftaiboilerplate.com)
  </Card>
</CardGroup>

## $99 vs $199 — what's the difference?

The code you receive on day one is identical. The difference is **time**:

|                                                  | Single download (\$99) | Lifetime (\$199)    |
| ------------------------------------------------ | ---------------------- | ------------------- |
| Current release source                           | ✅                      | ✅                   |
| Commercial use, unlimited apps                   | ✅                      | ✅                   |
| Delivery                                         | Email download link    | Private GitHub repo |
| Future versions (e.g. the next major release)    | ❌                      | ✅                   |
| Ongoing updates (fixes, new modules, new guides) | ❌                      | ✅                   |
| App Generator access when it ships               | ❌                      | ✅                   |

If you expect to maintain the app past one release cycle, **Lifetime pays for itself** the first time a new version lands.

## Already a customer? You're grandfathered

<Note>
  **Existing and past buyers keep lifetime access** to the boilerplate, including **all new versions (v2.2.0 and beyond) at no new charge** — even if you bought before these tiers existed. You will **also get access to the App Generator when it ships**, as a thank-you. No action needed; pull from your private repo as usual.
</Note>

## The App Generator is a separate product

The App Generator is **not bundled** in the boilerplate and is **not in this repository**. It is a separate, upcoming macOS product. What ships *in the boilerplate today* is the template-side foundation it builds on:

* `template.manifest.json` — the machine-readable identity/module/config map
* the [App Store 4.3(a) audit gate and hardening playbook](/pages/guides/app-store-4-3-hardening)
* the hero archetype recipes that drive differentiation

You can ship a fully differentiated, 4.3-safe app **today** by following the [App Store 4.3 Hardening guide](/pages/guides/app-store-4-3-hardening) — the App Generator will simply automate that workflow.

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between the $99 and $199 tiers?">
    Same source code on day one. The $99 single download is a one-time snapshot of the current release with no future-version or update access. The $199 lifetime license includes all future versions and lifetime updates via a private GitHub repo, plus App Generator access when it ships.
  </Accordion>

  <Accordion title="Do I get future versions?">
    With the **$199 lifetime** license, yes — every future version, forever, at no extra cost. With the **$99 single download**, no — you receive the current release only.
  </Accordion>

  <Accordion title="I bought earlier — am I grandfathered in?">
    Yes. All existing and past buyers keep lifetime access to new versions at no new charge, and will receive App Generator access when it launches.
  </Accordion>

  <Accordion title="When is the App Generator available?">
    It's coming soon as a separate \$399 macOS product. It isn't purchasable yet — [join the waitlist](https://www.swiftaiboilerplate.com) to be notified, and watch the [changelog](/pages/reference/changelog) for the announcement.
  </Accordion>

  <Accordion title="Does the boilerplate help me pass App Store review?">
    Yes. v2.2.0 ships a first-party App Store Guideline 4.3(a) playbook: a Release-binary audit gate (`scripts/appstore-43-audit.sh`) that fails the build on un-rebranded fingerprints, a branding/identity map, an App Review Notes template, and per-module removal guidance. See [App Store 4.3 Hardening](/pages/guides/app-store-4-3-hardening). Note that differentiation comes from your product, listing, and binary — shared architecture alone does not guarantee approval.
  </Accordion>

  <Accordion title="Can I use it for client work and commercial apps?">
    Yes — build unlimited apps, including paid and client apps. For the full legal terms, see the [license page on the product site](https://www.swiftaiboilerplate.com/legal/license).
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="Changelog" href="/pages/reference/changelog">
    What shipped in v2.2.0 and earlier
  </Card>

  <Card title="App Store 4.3 Hardening" href="/pages/guides/app-store-4-3-hardening">
    Ship a differentiated, review-safe app today
  </Card>
</CardGroup>


# Scripts Reference
Source: https://docs.swiftaiboilerplate.com/pages/reference/scripts

Helper scripts shipped in scripts/ for testing, App Store 4.3 hardening, rebranding, config generation, and manifest validation (v2.2.0).

The boilerplate ships five helper scripts in `scripts/`. Each is listed below with its real flags and behavior, verified against the script source.

| Script                            | Purpose                                                            |
| --------------------------------- | ------------------------------------------------------------------ |
| `run-tests.sh`                    | Test runner with coverage measurement                              |
| `appstore-43-audit.sh`            | App Store Guideline 4.3(a) Release-binary audit gate (new in v2.2) |
| `rebrand-design-system-prefix.sh` | Rename the `SAI` design-system prefix (new in v2.2)                |
| `update-config.sh`                | Generate `Configuration.swift` from `Secrets.xcconfig`             |
| `validate-template-manifest.sh`   | Validate `template.manifest.json` against the repo (new in v2.2)   |

## run-tests.sh

**Location:** `scripts/run-tests.sh`

Test runner with optional coverage measurement. Run from the project root. With no flags it runs the app test target via `xcodebuild test` against the `SwiftAIBoilerplatePro` scheme; with `--package NAME` it runs `swift test` inside `Packages/NAME` instead.

<Tabs>
  <Tab title="Basic Usage">
    ```bash theme={null}
    # Run the app test target
    ./scripts/run-tests.sh

    # Run with coverage
    ./scripts/run-tests.sh --coverage

    # Run and open the HTML report
    ./scripts/run-tests.sh --coverage --open
    ```
  </Tab>

  <Tab title="Package Testing">
    ```bash theme={null}
    # Test a specific package (swift test in Packages/NAME)
    ./scripts/run-tests.sh --package Core
    ./scripts/run-tests.sh --package Networking
    ./scripts/run-tests.sh --package Storage

    # With coverage
    ./scripts/run-tests.sh --package Core --coverage
    ```
  </Tab>

  <Tab title="Verbose">
    ```bash theme={null}
    # Show full xcodebuild output (skips xcpretty)
    ./scripts/run-tests.sh --verbose

    # Print usage
    ./scripts/run-tests.sh --help
    ```
  </Tab>
</Tabs>

**Flags:**

* `--coverage` — Enable code coverage and generate the report
* `--open` — Open the HTML coverage report in the browser
* `--package NAME` — Test a single package via `swift test`
* `--verbose` — Show detailed `xcodebuild` output (otherwise piped through `xcpretty` when available)
* `--help` — Show usage and exit

**Output (with `--coverage`, full-app run only):**

* Console test results
* `coverage-report.txt` — text summary
* `coverage-report.html` — detailed HTML report

<Note>
  The script's internal `COVERAGE_THRESHOLD` (85%) only prints a pass/warn line; it does not fail the run. The enforced gate lives in CI (see [CI/CD Commands](#cicd-commands)). The full app run uses the `Boilerplate.xctestplan` workspace test plan, which executes \~598 tests across the 12 package test targets plus the app unit and UI test suites in one pass.
</Note>

## appstore-43-audit.sh

**Location:** `scripts/appstore-43-audit.sh`

New in v2.2. Builds the app in **Release** configuration, then runs a `strings` audit over the main executable and the app-owned bundle, failing the build if any un-rebranded production fingerprint survives. This is the headline App Store Guideline 4.3(a) gate: it stops you from shipping a binary that still looks like the starter template.

The risky-string patterns (`SwiftAI`, `Boilerplate`, `api.example.com`, `DesignSystem/SAI`, and more) are loaded from `template.manifest.json` so the script, CI, and agent prompts never diverge; an inline fallback list is used only for detached copies.

```bash theme={null}
# Run the full Release-binary audit from the project root
bash scripts/appstore-43-audit.sh
```

Beyond the binary scan, it also checks **configuration readiness** and fails until you:

* replace the starter `BrandConfig.appDisplayName` (`"App Name"`),
* set production `privacyPolicyURLString`, `termsOfServiceURLString`, and `subscriptionTermsURLString` in `BrandConfig`,
* rename the starter app bundle ID by editing `APP_BUNDLE_ID` (`com.berkin.SwiftAIBoilerplatePro`) in `Config/App.xcconfig` — every target's `PRODUCT_BUNDLE_IDENTIFIER` derives from it — and
* remove bundled generic/demo legal/showcase markdown.

It exits non-zero on any blocking app-owned hit and prints `PASS:` when clean. Override the scheme, destination, or derived-data paths via `AUDIT_SCHEME`, `AUDIT_DESTINATION`, `AUDIT_DERIVED_DATA`, and `AUDIT_PACKAGE_CACHE` env vars.

<Note>
  The deeper hardening workflow (binary audit, branding/identity map, App Review Notes template, per-module removal) lives in `docs/checklists/APP_STORE_4_3_HARDENING.md`, with prompt packs in `docs/prompts/AppStore4_3Hardening.prompts.md`. The matching standalone **App Generator** that produces a 4.3-safe app from this template is a separate product (coming soon) — see the [License & Updates](/pages/reference/license) page.
</Note>

## rebrand-design-system-prefix.sh

**Location:** `scripts/rebrand-design-system-prefix.sh`

New in v2.2. Renames the `SAI` design-system prefix throughout `Packages/DesignSystem` — both textual occurrences in `.swift`/`.md` files and the `SAI*`-named source files themselves. Useful for clearing the `DesignSystem/SAI` fingerprint flagged by the 4.3 audit.

```bash theme={null}
# Dry run (default): list textual matches and the files that would be renamed
bash scripts/rebrand-design-system-prefix.sh SAI YourPrefix

# Apply the rename after committing or stashing your work
bash scripts/rebrand-design-system-prefix.sh SAI YourPrefix --apply
```

**Arguments:** `OLD_PREFIX` (default `SAI`), `NEW_PREFIX` (required), `MODE` (`--dry-run` default, or `--apply`). The new prefix must be a Swift-style identifier starting with an uppercase letter.

<Warning>
  `--apply` rewrites files in place. Commit or stash first, then re-run tests and `scripts/appstore-43-audit.sh` before submitting.
</Warning>

## update-config.sh

**Location:** `scripts/update-config.sh`

Generates `SwiftAIBoilerplatePro/Generated/Configuration.swift` from `Config/Secrets.xcconfig`. Run it manually after filling in your keys. Placeholder values containing `YOUR` are skipped, so a fresh clone still builds and runs with `MockAuthClient` and `EchoLLMClient`.

```bash theme={null}
# Generate Configuration.swift from Config/Secrets.xcconfig
bash scripts/update-config.sh
```

The generated `AppConfiguration` enum exposes a `static let` for each configured key and an `isConfigured(_:)` helper. Recognized keys: `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `REVENUECAT_API_KEY`, `RC_ENTITLEMENT_ID`, `PROXY_BASE_URL`, `PROXY_PATH`, `ONESIGNAL_APP_ID`. See the [Configuration reference](/pages/reference/config) for details.

<Warning>
  This writes real API keys into a committed-by-default path. Do NOT commit `Configuration.swift` after running it. Install the pre-commit hook to block accidental commits: `git config core.hooksPath .githooks`.
</Warning>

## validate-template-manifest.sh

**Location:** `scripts/validate-template-manifest.sh`

New in v2.2. Validates `template.manifest.json` (the machine-readable single source of truth for identity surface, module graph, config schema, fingerprints, and recipes) against the actual repository.

```bash theme={null}
# Validate the manifest from the project root
bash scripts/validate-template-manifest.sh
```

It checks that:

* every path referenced by the manifest exists,
* each module's manifest-declared dependencies match its `Package.swift`,
* the manifest fingerprint list is a superset of the audit script's fallback list, and
* each brand anchor resolves to exactly one marked line.

It prints `template.manifest.json OK` on success or one `FAIL:` line per problem (exit 1). This runs as the `Template Manifest` job in CI.

## Supabase Scripts

### Deploy Edge Function

```bash theme={null}
# Login
supabase login

# Link project
cd supabase
supabase link --project-ref YOUR_REF

# Set secrets
supabase secrets set OPENROUTER_API_KEY=sk-or-v1-YOUR_KEY

# Deploy
supabase functions deploy ai

# Test
curl https://YOUR_PROJECT.supabase.co/functions/v1/ai
```

### Run Migrations

```bash theme={null}
# Push all migrations
supabase db push

# Create new migration
supabase migration new your_migration_name

# Reset database (DANGER!)
supabase db reset
```

### Local Development

```bash theme={null}
# Start local Supabase
supabase start

# Run functions locally
supabase functions serve

# Stop local Supabase
supabase stop
```

## Xcode Build Scripts

### Clean Build

```bash theme={null}
# In Xcode
⌘ + Shift + K

# Or terminal
xcodebuild clean \
  -scheme SwiftAIBoilerplatePro \
  -configuration Debug
```

### Archive

```bash theme={null}
# Terminal archive
xcodebuild archive \
  -scheme SwiftAIBoilerplatePro \
  -archivePath ./build/SwiftAIBoilerplatePro.xcarchive
```

### Run Tests

One `xcodebuild test` against the scheme runs the whole `Boilerplate.xctestplan` (all 12 package test targets + the app suites, \~598 tests):

```bash theme={null}
xcodebuild test \
  -project SwiftAIBoilerplatePro.xcodeproj \
  -scheme SwiftAIBoilerplatePro \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2' \
  -enableCodeCoverage YES
```

## Git Workflows

### Pre-commit Checks

The repo ships a pre-commit hook that blocks committing a generated `Configuration.swift`. Install it once:

```bash theme={null}
git config core.hooksPath .githooks
```

Run the same checks CI runs before pushing:

```bash theme={null}
# Lint (strict)
swiftlint lint --strict

# Tests with coverage
./scripts/run-tests.sh --coverage

# Validate the template manifest
bash scripts/validate-template-manifest.sh
```

Before an App Store submission, also run the 4.3 audit gate:

```bash theme={null}
bash scripts/appstore-43-audit.sh
```

### Branch Management

```bash theme={null}
# Create feature branch
git checkout -b feature/your-feature

# Commit with message
git commit -m "feat: your feature description"

# Push and create PR
git push origin feature/your-feature
```

## Package Management

### Update Dependencies

```bash theme={null}
# In Xcode
File → Packages → Update to Latest Package Versions

# Or terminal
xcodebuild -resolvePackageDependencies
```

### Reset Package Cache

```bash theme={null}
# In Xcode
File → Packages → Reset Package Caches

# Or terminal
rm -rf ~/Library/Caches/org.swift.swiftpm
rm -rf ~/Library/Developer/Xcode/DerivedData
```

## Common Commands

### Development

```bash theme={null}
# Open project
open SwiftAIBoilerplatePro.xcodeproj

# Run app (requires Xcode)
xcodebuild -scheme SwiftAIBoilerplatePro

# Build only
xcodebuild build -scheme SwiftAIBoilerplatePro
```

### Configuration

```bash theme={null}
# Copy config template
cp Config/Secrets.example.xcconfig Config/Secrets.xcconfig

# Edit config
nano Config/Secrets.xcconfig
# or
open -a Xcode Config/Secrets.xcconfig
```

### Cleaning

```bash theme={null}
# Clean derived data
rm -rf ~/Library/Developer/Xcode/DerivedData

# Clean build folder
xcodebuild clean

# Reset simulators
xcrun simctl erase all
```

## CI/CD Commands

### GitHub Actions

Workflows in `.github/workflows/`:

**Main CI (`ci.yml`)** — runs on push and pull request:

```text theme={null}
- Template Manifest    validate-template-manifest.sh
- Secret Scan          Gitleaks
- Build & Test (iOS 26.2)   xcodebuild test (iPhone 17 Pro, OS=26.2) + coverage gate
- Build & Test (iOS 18.6 fallback path)   pre-iOS-26 compile/run, no coverage gate
- SwiftLint             swiftlint lint --strict
```

The coverage gate enforces the `MINIMUM_COVERAGE` env value (currently `25`) and fails the build below it; it is computed over product targets only.

**Coverage Report (`coverage-report.yml`)** — runs weekly (Mondays 09:00 UTC) and on manual dispatch:

```text theme={null}
- Generate detailed coverage (text + JSON)
- Build an HTML coverage report
- Open a GitHub issue if coverage is low
```

**Trigger manually:**

```text theme={null}
GitHub UI → Actions → Select workflow → Run workflow
```

## Quick Reference

<AccordionGroup>
  <Accordion title="Run Tests Locally">
    ```bash theme={null}
    ./scripts/run-tests.sh --coverage --open
    ```
  </Accordion>

  <Accordion title="Deploy Backend">
    ```bash theme={null}
    cd supabase
    supabase functions deploy ai
    ```
  </Accordion>

  <Accordion title="Clean Everything">
    ```bash theme={null}
    xcodebuild clean
    rm -rf ~/Library/Developer/Xcode/DerivedData
    rm -rf ~/Library/Caches/org.swift.swiftpm
    ```
  </Accordion>

  <Accordion title="Check Coverage">
    ```bash theme={null}
    ./scripts/run-tests.sh --coverage
    open coverage-report.html
    ```
  </Accordion>

  <Accordion title="App Store 4.3 Pre-submission Audit">
    ```bash theme={null}
    bash scripts/appstore-43-audit.sh
    ```
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup>
  <Card title="Testing Guide" href="/pages/guides/testing">
    Testing strategies
  </Card>

  <Card title="Deployment" href="/pages/guides/deployment">
    Production deployment
  </Card>

  <Card title="Supabase Setup" href="/pages/guides/supabase-setup">
    Backend deployment
  </Card>

  <Card title="Configuration" href="/pages/reference/config">
    Config reference
  </Card>

  <Card title="License & Updates" href="/pages/reference/license">
    Pricing, lifetime updates, and the App Generator (coming soon)
  </Card>
</CardGroup>