## Architecture Rules

- Single Activity architecture. One `MainActivity` hosts `AppNavHost` for all Compose navigation. No Fragments.
- Clean Architecture layers: Data → Domain → UI. Domain layer has no Android dependencies. Data layer implements domain interfaces.
- Unidirectional data flow: UI observes state from ViewModel. User actions trigger ViewModel methods. ViewModel updates state via StateFlow.
- Compose-only UI. No XML layouts. No Fragment-based navigation. No `findViewById`. No Data Binding.
- State hoisting: Composable screens are stateless. They receive state and callbacks from ViewModel via the screen-level composable. State lives in ViewModel.
- ViewModel per screen. ViewModel exposes `StateFlow<UiState>` for UI state and `SharedFlow<UiEvent>` for one-time events (navigation, toast).
- Repository pattern: repositories coordinate between local (Room) and remote (Retrofit) data sources. Domain layer depends on repository interfaces, not implementations.
- Use Cases: optional for simple CRUD. Required when business logic involves multiple repositories or complex transformations.
- Hilt for dependency injection: `@HiltAndroidApp` on Application, `@AndroidEntryPoint` on Activity, `@HiltViewModel` on ViewModels.
- Offline-first: Room as source of truth. Network calls update Room. UI observes Room via Flow. `NetworkBoundResource` pattern for sync.

## Coding Conventions

- Kotlin 2.1 features: data classes, sealed classes/interfaces, extension functions, scope functions (let, also, apply, run).
- Null safety: no `!!` operator in production code. Use `?.let {}`, `?: return`, or explicit null checks.
- Coroutines: `viewModelScope` in ViewModels. `withContext(Dispatchers.IO)` for database and network calls. Never use `GlobalScope`.
- StateFlow: prefer `StateFlow<UiState>` over `LiveData` for Compose. Use `MutableStateFlow` internally, expose as `StateFlow`.
- Compose state: use `remember`, `rememberSaveable`, `derivedStateOf`. Never store state in global variables.
- Composable naming: PascalCase. Stateless composables receive all data as parameters. Annotate with `@Composable`.
- Compose preview: `@Preview` annotation on composable functions. Provide sample data. Preview composables in separate `Preview` functions.
- Modifier parameter: every composable accepts `modifier: Modifier = Modifier` as the first optional parameter.
- Theme: use `MaterialTheme.colorScheme`, `.typography`, `.shapes`. Never hardcode colors or text styles.
- String resources: all user-visible text in `strings.xml`. Use `stringResource(R.string.key)` in Compose. No hardcoded strings.
- Sealed classes for navigation routes: `sealed class Screen(val route: String)`. Type-safe navigation with arguments.
- Data classes for state: `data class UsersUiState(val users: List<User> = emptyList(), val isLoading: Boolean = false, val error: String? = null)`.
- Extension functions: for domain logic on models. Keep in the model's companion or in a separate extensions file.
- Lambda trailing syntax: `Button(onClick = { viewModel.onAction() }) { Text("Click") }`.
- Collection operations: use `.map`, `.filter`, `.groupBy` instead of manual loops.
- Imports: auto-organized by IDE. No wildcard imports.

## Error Handling

- UI state includes error field: `data class UiState(val error: UiError? = null)`. Display error composable when non-null.
- ViewModel catches exceptions from use cases/repositories. Maps to user-friendly `UiError` sealed class variants.
- Network errors: `IOException` → offline message. `HttpException` → server error with status code mapping.
- Room errors: catch `SQLiteConstraintException` for unique violations. Wrap in domain-specific exceptions.
- Coroutine exception handling: `CoroutineExceptionHandler` on `viewModelScope` for uncaught exceptions. Log and update UI state.
- Retry mechanism: expose `retry()` function in ViewModel. UI shows retry button on error state.
- One-time events: `SharedFlow<UiEvent>` for navigation, snackbar, toast. `UiEvent.ShowError(message)`.
- Crash reporting: Firebase Crashlytics. Non-fatal errors reported with `Firebase.crashlytics.recordException(e)`.
- Never catch `CancellationException`. It is used by coroutines for job cancellation. Always rethrow if caught.
- Structured error logging: include screen name, user action, and error details in crash reports.

## Testing Conventions

- Unit tests (JVM): test ViewModels, Use Cases, Repositories, Mappers. No Android framework dependencies.
- ViewModel tests: use `Turbine` library to test StateFlow emissions. Use `TestDispatcher` for coroutine control.
- Repository tests: mock API and DAO. Test data coordination logic. Use `kotlinx-coroutines-test` `runTest`.
- Use Case tests: mock repository. Test business logic transformations.
- Instrumented tests: Compose testing with `createComposeRule()`. Test UI interactions and state rendering.
- Compose tests: `composeTestRule.onNodeWithText("Submit").performClick()`. Assert state changes.
- Hilt testing: `@HiltAndroidTest` on test classes. Use `@UninstallModules` to replace real modules with test modules.
- Test doubles: interfaces for all repositories and data sources. Fake implementations for testing.
- Naming: `fun \`should show users when loaded successfully\`()` using backtick syntax.
- Mocking: MockK library for Kotlin-friendly mocking. `coEvery { repo.getUsers() } returns flowOf(users)`.
- Coverage: 90% for ViewModels and Use Cases, 80% for Repositories, 50% for Compose UI.

## Database & Room Patterns

- Room database: single `@Database` class. Version-managed with `autoMigrations`.
- Entity naming: `@Entity(tableName = "users")`. Columns with `@ColumnInfo(name = "first_name")`.
- DAO pattern: `@Dao` interface with `@Query`, `@Insert(onConflict = OnConflictStrategy.REPLACE)`, `@Delete`.
- DAO returns: `Flow<List<Entity>>` for observable queries. `suspend fun` for one-shot operations.
- Type converters: `@TypeConverter` for Date, Enum, List<String> → JSON. Register with `@TypeConverters`.
- Migrations: explicit `Migration(from, to)` for schema changes. Test migrations with `MigrationTestHelper`.
- Prepopulate: `createFromAsset("database/seed.db")` for initial data.
- Indices: `@Entity(indices = [Index("email", unique = true)])` for query optimization.
- Relations: `@Embedded`, `@Relation(parentColumn, entityColumn)` for one-to-many. Return with `@Transaction` annotated DAO methods.

## Networking & API Patterns

- Retrofit: interface-based API definitions. `@GET`, `@POST`, `@PUT`, `@DELETE` annotations.
- Request/Response DTOs: separate from domain models. `@Serializable` with kotlinx-serialization.
- OkHttp interceptors: auth token interceptor, logging interceptor, network connectivity interceptor.
- Error handling: `Response<T>` wrapper. Check `isSuccessful`. Parse error body for API error messages.
- Paging: Paging 3 library with `PagingSource` for paginated API responses.
- Image loading: Coil `AsyncImage` composable for Compose. Configure caching in `ImageLoader`.

## What Claude Should Never Do

- Never create XML layout files. This project uses Jetpack Compose exclusively for UI.
- Never use `LiveData` for new code. Use `StateFlow` and `SharedFlow` for Compose state observation.
- Never use `GlobalScope` for coroutines. Use `viewModelScope` in ViewModels, `lifecycleScope` in Activity/Fragment.
- Never use `!!` (non-null assertion) in production code. Handle nullability with safe calls, Elvis operator, or explicit checks.
- Never use `findViewById`. This project uses Compose — there are no View references.
- Never store state in global variables or companion objects. State lives in ViewModel via StateFlow.
- Never access database or network on the Main thread. Use `withContext(Dispatchers.IO)` or `suspend` functions.
- Never hardcode strings, colors, or dimensions. Use resources (`strings.xml`, `MaterialTheme`).
- Never create Fragments. Single Activity + Compose Navigation handles all screen transitions.
- Never use Java code in this Kotlin project. All new code must be Kotlin.
- Never use `Thread()` or `AsyncTask`. Use Kotlin Coroutines for all async work.
- Never use `SharedPreferences` directly. Use Jetpack DataStore for key-value storage.

## Project-Specific Context

- [YOUR APP NAME] — update with your project details
- Min SDK: 26 (Android 8.0), Target SDK: 35 (Android 15)
- Backend API: [REST API URL / Firebase / Supabase]
- Analytics: [Firebase Analytics / Amplitude]
- Crash reporting: Firebase Crashlytics
- CI/CD: [GitHub Actions / Bitrise / CircleCI] → Google Play Console
- Distribution: [Google Play / Firebase App Distribution for testing]