Documentation Index
Fetch the complete documentation index at: https://docs.swiftaiboilerplate.com/llms.txt
Use this file to discover all available pages before exploring further.
Architecture Overview
SwiftAI Boilerplate Pro uses modern iOS development patterns with clean separation of concerns.Full technical details: See
/docs/foundations/Architecture.md in your project for complete technical coverage.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 withCompositionRoot:
- ✅ No global singletons
- ✅ Easy to mock for testing
- ✅ Clear dependency graph
- ✅ Compile-time safety
3. Protocol-Oriented Design
All external dependencies use protocols:- ✅ Swappable implementations
- ✅ Easy testing with mocks
- ✅ No vendor lock-in
- ✅ Clear contracts
Module Structure
11 Swift Packages
Core
Foundation utilities, errors, logging
Networking
HTTP client with interceptors
Storage
SwiftData models, repositories
Auth
Authentication clients
Payments
Subscription management
AI
LLM client protocol
FeatureChat
Chat UI and ViewModels
FeatureSettings
Settings and paywall
DesignSystem
UI tokens, components, and accessibility
Localization
Type-safe strings, pluralization, i18n
Accessibility
VoiceOver, Dynamic Type, Reduce Motion
- ✅ No circular dependencies
- ✅ Core has no dependencies
- ✅ Features depend on services
- ✅ Services depend on infrastructure
Data Flow
Chat Message Flow
Authentication Flow
iOS 26 Liquid Glass Layer
v2.0 introduces a dedicated Liquid Glass primitive inside the DesignSystem package. 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.
- iOS 26+: uses the native
Glassmaterial,glassEffect, andGlassEffectContainer. - iOS 17–25: falls back to SwiftUI
Materialautomatically. Same call sites, progressive enhancement at runtime.
saiScrollEdgeGlass(_:), saiSidebarAdaptable(), saiTabBarMinimize(_:), and SAITabBarMinimizeStyle for shell-level polish.
See Design System Module 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, andSettingsRepositoryImplare all main-actor-isolated.@Observablethroughout: view models and observable stores use the@Observablemacro. NoObservableObject, no@Published, no.onReceive.- No
DispatchQueue.mainin app code: all main-thread work goes through@MainActororMainActor.run. - Explicit
any: every protocol-typed property and parameter uses theanykeyword, as Swift 6 requires. - Async/await throughout: no completion handlers, structured concurrency for cancellation,
Sendablewhere crossing actor boundaries.
Architecture Rule: ≤ 400 Lines Per File
v2.0 enforces a hard ceiling: no Swift file exceeds 400 lines. When a type grows past that, it moves into extension-split siblings in the same folder. Examples from the v2.0 refactor:SessionManager.swift→+SignIn,+Refresh,+PersistenceL10n.swift→L10n+<Namespace>.swiftper nested enumSettingsView.swift→ ≤ 125-line composition root with sections inViews/Settings/*.swiftChatViewModel.swift→ChatViewModel+Memory.swift
git log for the full rewrite.
Concurrency Primitives
Async/Await Throughout
- ✅ No completion handlers
- ✅ Structured concurrency
- ✅ MainActor for UI updates
- ✅ Sendable for thread safety
Testing Strategy
Unit Tests
Test ViewModels and repositories in isolation:Integration Tests
Test component interaction:UI Tests
Test end-to-end flows:Customization Entry Points
Add New Feature
- Create package (if needed):
Packages/FeatureX/ - Create models: Define SwiftData models in
Storage - Create repository: Data access layer
- Create ViewModel: Business logic
- Create View: SwiftUI interface
- Wire in CompositionRoot: Add factory method
Replace Backend
Implement the protocol:Add UI Components
- Create component in
DesignSystem/Components/ - Use design tokens (DSColors, DSSpacing, etc.)
- Add preview
- Add snapshot test
- Use in features
Best Practices Applied
Code Organization
Code Organization
- Files ≤ 400 lines (extension-split when larger)
- One type per file
- MARK comments for navigation
- Grouped by responsibility
Error Handling
Error Handling
- All errors mapped to
AppError - User-friendly messages
- Technical details logged
- Never swallow errors silently
Naming
Naming
- Clear, explicit names
- No abbreviations in public API
- Consistent conventions
- Self-documenting code
Performance
Performance
- Lazy loading (messages, images)
- Cursor-based pagination
- Image compression
- Offline-first data access
- Background sync
Security
Security
- Tokens in Keychain (never UserDefaults)
- API keys server-side only
- PII redacted in logs
- Row Level Security (Supabase)
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
Core Module
Error handling, logging, utilities
Networking
HTTP client architecture
Storage
SwiftData and repositories
CLAUDE.md
Guidelines for AI-assisted development
Find full technical documentation in your project: architecture-overview.md
