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
9 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 and components
- ✅ No circular dependencies
- ✅ Core has no dependencies
- ✅ Features depend on services
- ✅ Services depend on infrastructure
Data Flow
Chat Message Flow
Authentication Flow
Concurrency Model
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 ≤ 300 lines (extract components 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
