# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Kotlin Multiplatform project using Compose Multiplatform, targeting Android, iOS, and Desktop (JVM). The project is called "The Abstraction Engine" with the package namespace `coffee.liz.abstractionengine`.

## Build Commands

### Building
- **Android Debug Build**: `./gradlew :composeApp:assembleDebug`
- **Android Release Build**: `./gradlew :composeApp:assembleRelease`
- **Desktop Build**: `./gradlew :composeApp:packageDistributionForCurrentOS`

### Running
- **Desktop App**: `./gradlew :composeApp:run`
- **iOS App**: Open `iosApp/` directory in Xcode and run from there
- **Android App**: Use Android Studio run configurations or `./gradlew :composeApp:installDebug`

### Testing
- **Run Common Tests**: `./gradlew :composeApp:testDebugUnitTest`
- **Run All Tests**: `./gradlew test`

### Clean
- **Clean Build**: `./gradlew clean`

## Architecture

### Source Structure

The project follows Kotlin Multiplatform's platform-specific source set structure:

- **composeApp/src/commonMain/kotlin**: Shared code for all platforms
  - Contains the main `App.kt` composable and shared business logic
  - Uses Compose Multiplatform for cross-platform UI
  - Platform-agnostic interface definitions (e.g., `Platform.kt`)

- **composeApp/src/androidMain/kotlin**: Android-specific implementations
  - `MainActivity.kt`: Android app entry point
  - `Platform.android.kt`: Android platform implementations

- **composeApp/src/iosMain/kotlin**: iOS-specific implementations
  - `MainViewController.kt`: iOS app entry point
  - `Platform.ios.kt`: iOS platform implementations

- **composeApp/src/jvmMain/kotlin**: Desktop (JVM) specific implementations
  - `main.kt`: Desktop app entry point with window configuration
  - `Platform.jvm.kt`: JVM platform implementations

- **iosApp/**: Native iOS app wrapper that hosts the Compose Multiplatform framework

### Platform Abstraction Pattern

The codebase uses the expect/actual pattern for platform-specific implementations:
1. Define an `expect` declaration in `commonMain` (e.g., `Platform.kt`)
2. Provide `actual` implementations in each platform source set (androidMain, iosMain, jvmMain)

### Key Dependencies

- **Compose Multiplatform 1.9.0**: UI framework
- **Kotlin 2.2.20**: Language version
- **AndroidX Lifecycle 2.9.4**: ViewModel and lifecycle support
- **Compose Hot Reload**: Development feature for faster iteration

### Build Configuration

- Uses Gradle version catalogs (`gradle/libs.versions.toml`) for dependency management
- Android targets API 36, minimum API 24
- JVM target is Java 11
- iOS targets arm64 and simulator arm64
- Desktop distribution formats: DMG (macOS), MSI (Windows), DEB (Linux)

## Development Notes

### Entry Points
- **Desktop**: `coffee.liz.abstractionengine.MainKt` (composeApp/src/jvmMain/kotlin/coffee/liz/abstractionengine/main.kt:6)
- **Android**: `MainActivity` (composeApp/src/androidMain/kotlin/coffee/liz/abstractionengine/MainActivity.kt)
- **iOS**: `MainViewController` (composeApp/src/iosMain/kotlin/coffee/liz/abstractionengine/MainViewController.kt)

### Adding Platform-Specific Code
When adding functionality that requires platform APIs:
1. Add the interface/expect declaration in `commonMain/kotlin/coffee/liz/abstractionengine`
2. Implement actual platform-specific versions in the corresponding platform source sets
3. Platform implementations can use native APIs (Android SDK, iOS UIKit, JVM Swing)

### Resource Management
Compose resources are stored in `composeApp/src/commonMain/composeResources/` and are accessible via the generated `Res` object.