# CLAUDE.md

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

## Build Commands

```bash
# Build
./gradlew build                    # Full build
./gradlew assembleDebug            # Debug APK
./gradlew assembleRelease          # Release APK

# Test
./gradlew test                     # Run unit tests
./gradlew connectedAndroidTest     # Run instrumented tests (requires device/emulator)
./gradlew :app:testDebugUnitTest   # Run tests for specific module/variant

# Lint
./gradlew lint                     # Run Android Lint
./gradlew lintDebug                # Lint specific variant

# Clean
./gradlew clean
```

## Architecture

This is a **Kotlin Android application** using Jetpack Compose and Material 3.

### Module Structure

- **`:app`** - Main Android application entry point
- **`:core:ui`** - Shared design system library with theming components
- **`:feature:orb`** - Orb feature with Compose UI and WebGPU rendering

### Dependency Injection (Koin)

Uses Koin 4.1.1 for dependency injection. Modules are defined in `app/src/main/java/io/visus/orbis/di/AppModule.kt`.

```kotlin
// Define dependencies using autowire DSL (constructor params resolved automatically)
val appModule = module {
    singleOf(::MyRepository)          // Singleton
    factoryOf(::MyUseCase)            // New instance each time
    viewModelOf(::MyViewModel)        // ViewModel scoped to lifecycle
}

// Inject in Android classes via delegate
class MyActivity : ComponentActivity() {
    private val viewModel: MyViewModel by viewModel()
}
```

### Design System (core/ui)

The `core/ui` module provides a custom theme system (`OrbisTheme`) with:

- **Color.kt** - Color palette with light/dark mode support (grayscale, red, blue, green schemes with 10 variants each)
- **Typography.kt** - 12 text styles (h1-h4, body1-3, label1-3, button, input)
- **Theme.kt** - Composable theme wrapper that provides colors and typography via CompositionLocal
- **foundation/** - Elevation animations and custom ripple effects

### Theme Usage

```kotlin
OrbisTheme {
    // Access theme values via:
    OrbisTheme.colors.primary
    OrbisTheme.typography.h1
}
```

## Key Configuration

- **Min SDK:** 24 | **Target SDK:** 36
- **Kotlin:** 2.3.0 with Compose plugin
- **Compose BOM:** 2026.01.00
- **Koin:** 4.1.1 (dependency injection)
- **Lumo Plugin:** 1.2.5 (theme/component generation, configured in `lumo.properties`)
- **Java Compatibility:** Java 17