## Architecture Rules

- MVVM architecture: View → ViewModel → Repository → Service/SwiftData. Views observe ViewModels. ViewModels coordinate data access.
- SwiftUI-only UI. No UIKit views. No UIHostingController wrapping. No storyboards. No XIBs.
- Observation framework: `@Observable` macro on ViewModels (not `ObservableObject` protocol). Views access properties directly — no `@Published` wrappers needed.
- SwiftData for persistence: `@Model` macro on data classes. `ModelContainer` configured in `@main` app struct. `@Query` in views for fetched results.
- NavigationStack (not `NavigationView`): value-based navigation with `NavigationPath`. Type-safe `.navigationDestination(for:)`.
- Structured concurrency: `async/await` for all async operations. No completion handlers. No Combine for new code. `Task {}` in view lifecycle, `TaskGroup` for parallel work.
- Actor isolation: `@MainActor` on ViewModels and Views. Isolate data access with custom actors when needed.
- Dependency injection: use `@Environment` for framework-provided dependencies. Protocol-based DI for services. Pass via initializer or environment.
- Single source of truth: state owned by one entity. Views derive display from ViewModel state. No duplicate state.
- Feature-based folder structure: each feature has its own Views, ViewModel, and components subdirectory.

## Coding Conventions

- Swift 6 strict concurrency. No data races. All shared mutable state isolated to actors or marked `@Sendable`.
- Naming: types PascalCase, properties/methods camelCase, constants camelCase (Swift convention, not SCREAMING_SNAKE).
- View naming: `NounView` (`UsersListView`, `UserDetailView`). Modifier views: `NounModifier`.
- ViewModel naming: `NounViewModel` (`UsersViewModel`). One ViewModel per screen.
- Protocol naming: adjective or noun (`Fetchable`, `UserRepository`). No `Protocol` suffix.
- File naming: one primary type per file. File name matches type name.
- Access control: explicit `private`, `internal`, `public`. Default to most restrictive. `private(set)` for read-only from outside.
- Properties order in structs/classes: stored properties, computed properties, initializer, methods.
- Prefer value types (struct, enum) over reference types (class). Use class only when identity semantics or inheritance is required.
- Guard statements for early exits. `guard let value = optional else { return }`.
- SwiftUI view body: max 30 lines. Extract subviews into separate computed properties or child views.
- View modifiers: extract reusable modifier chains into custom `ViewModifier` structs.
- Trailing closure syntax for single-closure APIs. Labeled closures when multiple closures.
- String interpolation with `\()`. No `String(format:)` for simple interpolation.
- Collections: use `.map`, `.filter`, `.compactMap`, `.flatMap`. Avoid manual index-based loops.
- Comments: `///` documentation comments on public APIs. `//` for implementation notes. `// MARK:` for section organization.

## Error Handling

- ViewModel error state: `var error: AppError? = nil`. Views show error overlay when non-null.
- `AppError` enum conforming to `LocalizedError`. Variants: `.network(NetworkError)`, `.storage(StorageError)`, `.auth(AuthError)`, `.unknown(Error)`.
- Async function errors: throw `AppError` from service/repository methods. ViewModel catches and maps to UI state.
- Network errors: map `URLError` codes to user-friendly messages. `.notConnectedToInternet` → "No internet connection".
- SwiftData errors: catch `SwiftDataError` in repository. Map to domain-specific errors.
- Alert presentation: `.alert("Error", isPresented: $showError)`. One-time error display with automatic dismissal.
- Retry: expose `retry()` method on ViewModel. `ErrorView` composable includes retry button.
- Logging: `os.Logger` with subsystem and category. Log errors at `.error` level with context.
- Crash reporting: [Firebase Crashlytics / Sentry]. Non-fatal errors reported separately.
- Never force-unwrap optionals with `!` in production code. Use `guard let`, `if let`, or nil coalescing `??`.

## Testing Conventions

- Swift Testing framework for new tests (`@Test`, `#expect`, `@Suite`). XCTest for legacy tests and UI tests.
- ViewModel tests: test state transitions. Create ViewModel with mock dependencies, trigger action, assert state.
- Service tests: mock `URLProtocol` for network tests. Assert request format and response parsing.
- Repository tests: use in-memory `ModelContainer` for SwiftData tests. Assert CRUD operations.
- UI tests: XCUITest for critical user flows. Test navigation, form submission, error states.
- Preview tests: ensure all views have `#Preview` macros that compile and render correctly.
- Test naming: `@Test func fetchUsers_withValidResponse_updatesState()` or descriptive string: `@Test("Users load successfully from API")`.
- Mock pattern: protocol-based. `MockNetworkService: NetworkService` with configurable responses.
- Async test: `@Test func fetchUsers() async throws { ... }`. Swift Testing supports async natively.
- Test data: `PreviewData` struct with static sample instances for both previews and tests.
- Coverage: 90% for ViewModels, 80% for Services/Repositories, 50% for Views (tested via UI tests).

## Data & Persistence Patterns

- SwiftData `@Model` on model classes. Properties are automatically persisted. Use `@Attribute(.unique)` for unique constraints.
- ModelContainer: configured in `@main` app struct with `modelContainer(for: [User.self, Post.self])`.
- `@Query` in views: `@Query(sort: \User.name) var users: [User]` for automatic fetching and UI updates.
- ModelContext: accessed via `@Environment(\.modelContext) var context`. Use for insert, delete operations.
- Relationships: use plain Swift references. `var posts: [Post] = []` on User. SwiftData infers the relationship.
- Migration: SwiftData handles lightweight migrations automatically. For complex migrations, use `SchemaMigrationPlan`.
- Predicate: `#Predicate<User> { $0.name.contains(searchText) }` for type-safe filtering.
- Background operations: create separate `ModelContext` for background work. Merge changes to main context.
- CloudKit sync: enable iCloud container in capabilities. SwiftData syncs automatically with `cloudKitDatabase: .automatic`.

## Networking

- URLSession for API calls. Async/await: `let (data, response) = try await URLSession.shared.data(for: request)`.
- Request building: `URLRequest` with proper headers, HTTP method, and body. JSONEncoder for encoding.
- Response decoding: `JSONDecoder` with configured date strategy. Decode into response DTOs, map to domain models.
- Authentication: Bearer token in `Authorization` header. Refresh token flow in `AuthService`.
- Error responses: decode server error body. Map HTTP status codes to `NetworkError` enum.
- No third-party networking libraries unless specific features needed (multipart upload, certificate pinning).
- Request timeout: configure `URLSessionConfiguration` with `timeoutIntervalForRequest = 30`.
- Caching: use `URLCache` for GET requests. Configure cache policy per request.
- Pagination: generic `PaginatedResponse<T>` struct. Fetch next page with cursor or offset.

## Security

- Keychain: store auth tokens in Keychain via Keychain Services or a wrapper. Never use `UserDefaults` for secrets.
- App Transport Security: enforce HTTPS. No `NSAllowsArbitraryLoads` exceptions without justification.
- Biometric auth: `LAContext` for Face ID / Touch ID. Gate sensitive operations behind biometric check.
- Certificate pinning: use `URLSessionDelegate` `didReceive challenge:` for SSL pinning on critical API endpoints.
- Data protection: enable `FileProtectionType.complete` for sensitive local files.
- Input validation: validate all user input before sending to API. Sanitize strings to prevent injection.

## Deployment

- Xcode Cloud or Fastlane for CI/CD. Run tests and SwiftLint before archive.
- TestFlight for internal and external beta distribution.
- App Store Connect: manage app metadata, screenshots, and pricing.
- Versioning: semantic versioning in Xcode target. Increment build number automatically in CI.
- App Clips: use for lightweight entry points. Share code with main app target.
- Widgets: WidgetKit with SwiftUI. Share data via App Group container.

## What Claude Should Never Do

- Never create UIKit code (UIViewController, UITableView, UICollectionView). This project uses SwiftUI exclusively.
- Never use `ObservableObject` and `@Published`. Use `@Observable` macro from the Observation framework.
- Never use `NavigationView`. Use `NavigationStack` with `NavigationPath` for type-safe navigation.
- Never use completion handlers for async operations. Use `async/await` and structured concurrency.
- Never use Combine for new code. Use `AsyncSequence`, `AsyncStream`, or Observation framework.
- Never force-unwrap optionals with `!`. Use `guard let`, `if let`, optional chaining, or nil coalescing.
- Never use `AnyView` to erase view types. Use `@ViewBuilder`, conditional views, or `some View` return types.
- Never use storyboards, XIBs, or Interface Builder. All UI is code-based SwiftUI.
- Never use CoreData for new persistence. Use SwiftData (`@Model`).
- Never use `DispatchQueue.main.async`. Use `@MainActor` and structured concurrency.
- Never hardcode strings. Use String Catalogs (`Localizable.xcstrings`) and `String(localized:)`.
- Never use `UserDefaults` directly. Use `@AppStorage` in views or `UserDefaults` wrapped in a DataStore service.

## Project-Specific Context

- [YOUR APP NAME] — update with your project details
- iOS deployment target: 17.0 (supports @Observable, SwiftData, NavigationStack)
- Backend: [REST API URL / Firebase / Supabase / CloudKit]
- Analytics: [Firebase Analytics / Mixpanel / TelemetryDeck]
- Crash reporting: [Firebase Crashlytics / Sentry]
- Push notifications: APNs via [Firebase Cloud Messaging / direct APNs]
- Distribution: TestFlight → App Store Connect