Skip to main content
This guide gets you running fast. For a full production setup with real backends, follow the step-by-step instructions in the setup guides.

​
1. Prerequisites

Ensure you have:
  • ✅ macOS 14+
  • ✅ Xcode 15+
  • ✅ 10 minutes

​
2. Clone and Open

git clone https://github.com/BerkinSi/SwiftAIBoilerplatePro-Distribution.git
cd SwiftAIBoilerplatePro
open SwiftAIBoilerplatePro.xcodeproj
Xcode will automatically resolve Swift Package dependencies. Wait ~30 seconds for this to complete.

​
3. Configure (Optional for Mock Mode)

cp Config/Secrets.example.xcconfig Config/Secrets.xcconfig
Leave the default values! The app works immediately with:
  • MockAuthClient - Sign in with any email/password
  • EchoLLMClient - AI echoes your messages back
  • No payment setup needed

​
4. Run the App

Press ⌘ + R in Xcode.

​
What You’ll Experience

1

Onboarding

Swipe through 3 onboarding pages → tap “Get Started”
2

Sign In

Tap “Debug Sign In” (or use any email/password in mock mode)
3

Home Screen

See feature cards, quick actions, and subscription status
4

Chat

Tap “Start Chat” → send a message → receive echo response
Success! If you can send chat messages, you have a working AI app foundation.

​
5. Explore the 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

  • Sign in with any email/password (mock mode)
  • Sign out and sign back in
  • Profile persists across restarts
  • Create conversation
  • Send messages
  • Receive echo responses
  • Switch UI styles
  • Rename/delete conversations
  • Edit display name
  • Upload photo (compresses automatically)
  • View subscription status
  • Change themes (instant update)
  • Toggle preferences
  • All settings persist

​
What’s Running in Mock Mode

The app automatically detects missing backend configuration and uses mocks:
ComponentMock BehaviorProduction
AuthMockAuthClient - any credentials workSupabaseAuthClient
AIEchoLLMClient - echoes messagesProxyLLMClient → OpenRouter
PaymentsMockPaymentsClient - simulated statesRevenueCatClient
StorageLocal SwiftDataLocal + optional cloud sync
Mock mode is perfect for:
  • Learning the codebase
  • UI development
  • Testing without API costs
  • Demo purposes

​
Next Steps

  • Customize Immediately
  • Understand Architecture
  • Setup Production Backends
Jump straight to customization:Change branding (5 minutes):
  1. App name: Edit Config/App.xcconfig
  2. Colors: Edit DesignSystemColors.xcassets
  3. Icon: Replace in Assets.xcassets/AppIcon.appiconset
Full customization guide in project →

​
Run Tests

Verify everything with the test suite: 
# In Xcode
⌘ + U

# Or command line
xcodebuild test \
  -scheme SwiftAIBoilerplatePro \
  -destination 'platform=iOS Simulator,name=iPhone 15'
Expected: 338+ tests pass ✅

​
Troubleshooting

Solution:
# Clean and rebuild
⌘ + Shift + K
File → Packages → Reset Package Caches
⌘ + B
Cause: Running in Release modeSolution:
  1. Product → Scheme → Edit Scheme
  2. Run → Build Configuration → Debug
  3. Clean and rebuild
Solution:
File → Packages → Resolve Package Versions
# If still fails:
File → Packages → Update to Latest Package Versions

​
Quick Reference

​
File Locations

Config/Secrets.xcconfig               # API keys (gitignored)
SwiftAIBoilerplatePro/AppShell/       # UI screens
SwiftAIBoilerplatePro/Composition/    # DI container
Packages/*/                           # 9 Swift Packages

​
Key Files for Customization

What to ChangeFile Location
App nameConfig/App.xcconfig
ColorsResources/DesignSystemColors.xcassets/
OnboardingAppShell/OnboardingPage.swift
Home screenAppShell/HomeContent.swift

​
Useful Commands

# 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

You now have:
  • ✅ A running AI chat app
  • ✅ Working authentication (mock mode)
  • ✅ Functional chat with dual UIs
  • ✅ Profile management
  • ✅ Crashlytics seyup
  • ✅ Theme system (5 themes)
  • ✅ Understanding of mock vs production

​
Ready to Build?

Customize

Change branding, features, and UI

Architecture

Learn the system design

Deploy

Ship to production
Pro tip: Use the Building Your App guide which includes ready-to-use LLM prompts for Cursor/Claude to speed up customization!
⌘I