From 6f3dfee0dd277587fb73603a7008ba12ce138456 Mon Sep 17 00:00:00 2001 From: Aniket Indulkar Date: Tue, 19 May 2026 22:05:03 +0000 Subject: [PATCH] Add CLAUDE.md with project architecture, build system, test docs, and Android guidelines --- CLAUDE.md | 178 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..98d6929 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,178 @@ +# CLAUDE.md — TestAndroidApp + +## Project overview + +TestAndroidApp is a Kotlin Android application built with Jetpack Compose and Material 3, owned by ComplyCube. It is a minimal Compose scaffold serving as a starting point for Android development. + +**Package name:** `com.complycube.testandroidapp` + +--- + +## Project architecture + +``` +/workspace/ +├── app/ +│ ├── build.gradle.kts # App-level build config +│ ├── proguard-rules.pro +│ └── src/ +│ ├── main/ +│ │ ├── AndroidManifest.xml +│ │ ├── java/com/complycube/testandroidapp/ +│ │ │ ├── MainActivity.kt # Single activity, Compose entry point +│ │ │ └── ui/theme/ +│ │ │ ├── Color.kt # Material 3 color tokens +│ │ │ ├── Theme.kt # App theme (light/dark/dynamic) +│ │ │ └── Type.kt # Typography scale +│ │ └── res/ +│ │ ├── values/ +│ │ │ ├── strings.xml # All user-facing strings live here +│ │ │ ├── colors.xml +│ │ │ └── themes.xml +│ │ └── xml/ +│ │ ├── backup_rules.xml +│ │ └── data_extraction_rules.xml +│ ├── test/ # JVM unit tests +│ │ └── java/com/complycube/testandroidapp/ +│ │ └── ExampleUnitTest.kt +│ └── androidTest/ # Instrumented tests (device/emulator) +│ └── java/com/complycube/testandroidapp/ +│ └── ExampleInstrumentedTest.kt +├── build.gradle.kts # Root build config (plugin versions) +├── gradle/ +│ ├── libs.versions.toml # Centralized version catalog +│ └── wrapper/ # Gradle wrapper distribution +└── settings.gradle.kts +``` + +### Architecture patterns + +- **UI:** Jetpack Compose only — no XML layouts, no View-based screens. +- **State management:** `StateFlow` + `ViewModel` (use these; do not introduce LiveData). +- **Theme:** Material 3 (`MaterialTheme` from `androidx.compose.material3`). +- **Single activity:** `MainActivity` is the sole entry point; new screens are composables, not activities/fragments. +- No dependency injection framework is currently in use. + +--- + +## Build system + +### SDK versions + +| Property | Value | +|---------------|-------| +| Compile SDK | 36 | +| Target SDK | 36 | +| Min SDK | 24 (Android 7.0) | +| Java compatibility | 11 | +| Kotlin | 2.0.21 | +| AGP | 9.0.1 | +| Compose BOM | 2024.09.00 | +| Gradle | 9.2.1 | + +### Key dependencies (from `gradle/libs.versions.toml`) + +| Dependency | Purpose | +|-----------|---------| +| `androidx.core:core-ktx` | Kotlin extensions for Android core APIs | +| `androidx.lifecycle:lifecycle-runtime-ktx` | Lifecycle-aware coroutines | +| `androidx.activity:activity-compose` | Compose integration for activities | +| `androidx.compose.ui:ui` | Compose UI fundamentals | +| `androidx.compose.material3:material3` | Material 3 components | +| `junit:junit` | Unit test framework | +| `androidx.test.ext:junit` | AndroidX JUnit extensions | +| `androidx.test.espresso:espresso-core` | UI interaction testing | + +All versions are managed centrally in `gradle/libs.versions.toml`. Do not hardcode version strings in `build.gradle.kts` files; add new entries to the version catalog instead. + +### Building + +```bash +# Assemble debug APK +./gradlew assembleDebug + +# Assemble release APK +./gradlew assembleRelease + +# Run all checks (lint + unit tests) +./gradlew check +``` + +--- + +## Tests + +### Unit tests (`app/src/test/`) + +- Run on the **JVM** — no device or emulator required. +- Framework: JUnit 4 (`@Test`, `@Before`, etc.). +- Runner: default Gradle test runner. + +```bash +./gradlew test +``` + +Place unit tests under `app/src/test/java/com/complycube/testandroidapp/`. Mirror the production package structure. + +### Instrumented tests (`app/src/androidTest/`) + +- Run on a **connected device or emulator**. +- Framework: AndroidJUnit4 (`@RunWith(AndroidJUnit4::class)`). +- Runner: `androidx.test.runner.AndroidJUnitRunner` (configured in `build.gradle.kts`). +- Use `InstrumentationRegistry.getInstrumentation().targetContext` for Android context. + +```bash +./gradlew connectedAndroidTest +``` + +Place instrumented tests under `app/src/androidTest/java/com/complycube/testandroidapp/`. + +### Compose UI tests + +Use the Compose testing APIs (`createComposeRule`, `onNodeWithText`, semantic matchers) for Compose screen tests. Add the `androidx.compose.ui:ui-test-junit4` dependency when writing Compose UI tests. + +--- + +## Android development guidelines + +### Language & UI + +- **Kotlin only.** No Java source files. +- **Compose for all UI.** Do not add XML layouts or View-based screens. +- Use `Material3` components (`Button`, `Text`, `Scaffold`, etc.) from `androidx.compose.material3`. + +### Strings + +- All user-facing strings must live in `app/src/main/res/values/strings.xml`. +- Never hardcode display strings inside Kotlin or Compose source files. + +### State & ViewModels + +- Expose UI state via `StateFlow` from `ViewModel`. +- Collect state in composables with `collectAsStateWithLifecycle()` (requires `lifecycle-runtime-compose`). +- Do not use `LiveData` for new code. + +### Visibility & scope + +- Keep declarations `private` by default; only widen visibility when strictly required. +- Prefer `internal` over `public` for module-level helpers not part of a public API. + +### Imports & formatting + +- Use named imports; remove unused imports before committing. +- Follow the existing brace style and indentation (4-space indentation, opening brace on same line). +- Prefer expression bodies and trailing lambdas where they read naturally. + +### Dependencies + +- Do not introduce new third-party libraries unless the task explicitly requires it. +- When a new dependency is needed, add it to `gradle/libs.versions.toml` and reference it via the version catalog alias. + +### Do not modify + +Unless a ticket explicitly requires it, leave the following files untouched: +- `build.gradle.kts` / `settings.gradle.kts` +- `gradle/wrapper/` +- `AndroidManifest.xml` +- Pre-existing test files +- `.github/`