From 0611ec0e089f01554b6f07967916012a3723391c Mon Sep 17 00:00:00 2001
From: darken <darken@darken.eu>
Date: Sat, 30 Aug 2025 16:42:14 +0200
Subject: [PATCH] Add CLAUDE.md to guide AI code generation

This commit introduces a `CLAUDE.md` file.
This file contains instructions and context for the Claude AI to assist with development in this repository. It includes:
- Common build, test, and code quality commands.
- An overview of the project's multi-module architecture, core patterns (MVVM, DI with Hilt, Coroutines, Repository), and key components like `PodMonitor` and the reaction system.
- Details on build flavors (FOSS, Google Play) and build types (debug, beta, release).
- A description of the data flow architecture.
- Information on the testing strategy and key dependencies.
- Development notes regarding Bluetooth LE implementation and multi-platform considerations for phone and Wear OS.
---
 CLAUDE.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 144 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..ebe0a5ac
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,144 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Build Commands
+
+```bash
+# Build debug version
+./gradlew assembleDebug
+
+# Build all variants (FOSS and Google Play flavors)
+./gradlew assemble
+
+# Build specific flavor and type
+./gradlew assembleFossDebug
+./gradlew assembleGplayRelease
+
+# Build app bundles for Play Store
+./gradlew bundleGplayRelease
+```
+
+### Testing Commands
+
+```bash
+# Run all unit tests
+./gradlew test
+
+# Run unit tests for specific variant
+./gradlew testFossDebugUnitTest
+
+# Run instrumentation tests (requires connected device/emulator)
+./gradlew connectedAndroidTest
+./gradlew connectedFossDebugAndroidTest
+
+# Run all checks (lint + tests)
+./gradlew check
+```
+
+### Code Quality Commands
+
+```bash
+# Run lint for all variants
+./gradlew lint
+
+# Run lint for specific variant
+./gradlew lintFossDebug
+
+# Auto-fix lint issues where possible
+./gradlew lintFix
+
+# Update lint baseline
+./gradlew updateLintBaseline
+```
+
+### Release Commands
+
+```bash
+./gradlew assembleFossRelease assembleGplayRelease
+```
+
+## Architecture Overview
+
+### Multi-Module Structure
+
+- **app/**: Main Android application with FOSS and Google Play flavors
+- **app-common/**: Shared code between main app and Wear OS
+- **app-wear/**: Dedicated Wear OS companion application
+
+### Core Architecture Patterns
+
+- **MVVM**: ViewModels with LiveData/StateFlow for UI state management
+- **Dependency Injection**: Hilt/Dagger for dependency management
+- **Coroutines**: Extensive use of Kotlin coroutines for async operations
+- **Repository Pattern**: Data layer abstraction for monitoring and settings
+
+### Key Components
+
+#### PodMonitor System
+
+- `PodMonitor`: Core service that detects and tracks AirPods via Bluetooth LE
+- `MonitorControl`: Manages background monitoring worker lifecycle
+- `MonitorWorker`: Background worker that continuously scans for AirPods
+- `BluetoothEventReceiver`: Handles system Bluetooth events
+
+#### Reaction System
+
+- `ReactionSettingsFragment`: Configuration for popup notifications
+- `PopUpWindow`: Displays AirPods status when case is opened
+- `PopUpPodViewFactory`: Creates UI components for different pod models
+
+#### Common Utilities
+
+- `EdgeToEdgeHelper`: Handles Android edge-to-edge display insets
+
+### Build Configuration
+
+#### Flavors
+
+- **FOSS**: Open-source version without Google Play dependencies
+- **Google Play**: Version with billing client for in-app purchases
+
+#### Build Types
+
+- **debug**: Unobfuscated, full logging, no minification
+- **beta**: Obfuscated, production-ready with strict lint checks
+- **release**: Fully optimized for production distribution
+
+### Data Flow Architecture
+
+The app follows a unidirectional data flow:
+
+1. `BluetoothEventReceiver` detects Bluetooth events
+2. `MonitorWorker` scans for AirPods beacon data
+3. `PodMonitor` processes and stores device information
+4. ViewModels observe monitor data via repositories
+5. UI components react to ViewModel state changes
+6. `ReactionSystem` triggers popups and notifications
+
+### Testing Strategy
+
+- **Unit Tests**: Located in `app-common/src/test/` for shared logic
+- **Test Flavors**: Separate test configurations for FOSS and Google Play variants
+
+### Key Dependencies
+
+- **Hilt**: Dependency injection framework
+- **AndroidX Navigation**: Fragment navigation with SafeArgs
+- **WorkManager**: Background task scheduling for monitoring
+- **Moshi**: JSON serialization for configuration and debugging
+- **Material Design**: UI components following Material Design guidelines
+
+## Development Notes
+
+### Bluetooth LE Implementation
+
+The app uses Android's Bluetooth LE APIs to scan for Apple device advertisements. The core scanning logic is in
+`MonitorWorker` which runs as a long-lived background task.
+
+### Multi-Platform Considerations
+
+Code shared between phone and Wear OS apps is placed in `app-common`. When modifying shared functionality, ensure
+compatibility across both platforms.
\ No newline at end of file