# Repository Guidelines

## Project Structure & Module Organization

Yorvana is a single-module Android app. Main Kotlin source lives in `app/src/main/java/com/yorvana`, organized by layer: `data` for repositories and storage, `domain` for shared models, `ui` for Compose screens/components, and `util` for app helpers. Android resources are in `app/src/main/res`. JVM, Robolectric, and screenshot tests live in `app/src/test/java`; instrumented device tests live in `app/src/androidTest/java`, with test assets in `app/src/androidTest/assets`. Project docs are in `docs/`, build configuration is in `build.gradle.kts`, `app/build.gradle.kts`, `gradle/libs.versions.toml`, and quality rules are in `config/detekt/`.

## Build, Test, and Development Commands

- `./gradlew assembleDebug`: build a debug APK.
- `./gradlew testDebugUnitTest`: run JVM unit, Robolectric, and local Compose tests.
- `./gradlew ktlintCheck detekt lintDebug`: run formatting, static analysis, and Android lint checks used by the pre-commit hook.
- `./gradlew verifyRoborazziDebug`: verify screenshot baselines.
- `./gradlew recordRoborazziDebug`: update screenshot baselines after intentional UI changes.
- `./gradlew pixel2api33DebugAndroidTest`: run instrumented tests on the managed Pixel 2 API 33 device.
- `./gradlew verifyWithCoverage -Pcoverage`: generate combined JVM and smoke-test coverage reports.

## Coding Style & Naming Conventions

Use Kotlin with Java 17 targets and Jetpack Compose Material 3. Follow ktlint defaults and the detekt rules in `config/detekt/detekt.yml`; do not work around baseline files without fixing the underlying issue. Keep package paths under `com.yorvana`. Name Compose screen files `FeatureScreen.kt`, ViewModels `FeatureViewModel.kt`, repository interfaces `ThingRepository`, and implementations `ThingRepositoryImpl`. Prefer immutable UI state exposed through `StateFlow`.

## Testing Guidelines

Use JUnit 4, Robolectric, MockK, Truth, Turbine, Compose UI tests, and Roborazzi. Name fast JVM tests `*Test.kt`, local integration tests `*IT.kt`, and screenshot tests `*ScreenshotTest.kt`. Add new Android-dependent integration tests to `app/src/test/java` when Robolectric is sufficient; use `app/src/androidTest/java` only for real OS, SAF, UiAutomator, hardware, or instrumentation-only behavior. Refresh `app/coverage-baselines/gmd_smoke.ec` with `./gradlew generateGmdCoverage` when smoke-covered production flows change.

## Commit & Pull Request Guidelines

Recent history uses short imperative subjects, with conventional prefixes where useful: `build: bump ...`, `docs: add ...`, or plain feature summaries such as `Add contact option to settings (#102)`. Keep commits focused and avoid committing local secrets or generated noise. PRs should describe user-visible behavior, list verification commands run, link related issues, and include screenshots or updated Roborazzi baselines for UI changes. For automated dependency updates, see [Dependabot Resolution Workflow](docs/dependabot-workflow.md).

## Security & Configuration Tips

Do not commit `local.properties` or real signing credentials. Use `app/keystore.properties.template` for release signing setup and local `sentry.dsn.*` values for Sentry configuration. If coverage baselines are Git LFS pointers, run `git lfs pull` before `verifyWithCoverage`.