From 3834c4fc8e80055c1607f85bb980b8c20df857b1 Mon Sep 17 00:00:00 2001 From: shahondin1624 Date: Fri, 13 Mar 2026 11:11:03 +0100 Subject: [PATCH] Add CLAUDE.md with project guidance for Claude Code Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ab21da7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,78 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Build & Run Commands + +| Platform | Command | +|----------|---------| +| Desktop | `./gradlew :desktopApp:run` | +| Desktop (hot reload) | `./gradlew :desktopApp:hotRun --auto` | +| Android APK | `./gradlew :androidApp:assembleDebug` | +| Web (JS) | `./gradlew :webApp:jsBrowserDevelopmentRun` | +| Web (WASM) | `./gradlew :webApp:wasmJsBrowserDevelopmentRun` | +| Web distribution | `./gradlew :webApp:composeCompatibilityBrowserDistribution` | +| iOS | Open `iosApp/iosApp.xcodeproj` in Xcode | + +## Testing + +Tests live in `sharedUI/src/commonTest/`. Run with: +``` +./gradlew :sharedUI:allTests +``` + +Single test class: +``` +./gradlew :sharedUI:jvmTest --tests "org.shahondin1624.ComposeTest" +``` + +Uses `androidx.compose.ui.test.runComposeUiTest` for Compose UI testing. + +## Architecture + +Kotlin Multiplatform project using Compose Multiplatform. All shared logic and UI lives in `sharedUI`; platform modules are thin entry points. + +### Modules + +- **sharedUI** — Shared business logic and Compose UI (targets: Android, JVM, JS, WASM, iOS) +- **androidApp** — Android entry point (`AppActivity`) +- **desktopApp** — Desktop JVM entry point (supports hot reload) +- **webApp** — Web entry point (JS + WASM targets) +- **iosApp** — iOS entry point (Xcode project, not in Gradle) + +### Shared Code Layout (`sharedUI/src/commonMain/kotlin/org/shahondin1624/`) + +- `App.kt` — Root composable. Scaffold with navigation drawer, top bar, theme toggle. +- `model/` — Domain model implementing Shadowrun 5e rules: + - `charactermodel/ShadowrunCharacter` — Top-level aggregate: CharacterData + Attributes + Talents + DamageMonitor + - `attributes/Attributes` — 8 core attributes + Edge. Calculates derived values (initiative, limits, composure, carry, etc.) + - `attributes/AttributeType` — Enum with per-attribute color coding + - `talents/` — 60+ predefined talents via `ProvidedTalentName`, sealed `TalentDefinition` with polymorphic serialization, custom talent support + - `modifier/` — `SRModifier` interface for composable modifiers on attributes, talents, and dice rolls. `ModifierCache` provides LRU caching (max 5). + - `characterdata/CharacterData` — Name, metatype (Human/Elf/Dwarf/Ork/Troll), karma, nuyen, essence, etc. + - `charactermodel/DamageMonitor` — Stun/physical/overflow damage tracking derived from attributes + - `Defaults.kt` — `EXAMPLE_CHARACTER` used for development + - `Versionable` — Interface for schema versioning (current: "v0.1") +- `lib/functions/` — Dice rolling system (`DiceRoll`, `rollDice`, `countSuccesses`) and `DataLoader` (JSON serialization via kotlinx.serialization) +- `lib/components/` — Compose UI components: + - `charactermodel/attributespage/` — `AttributesPage` (grid layout), `Attribute` card, `Talent` card + - `settings/Settings` — Placeholder +- `theme/` — Material 3 theme with MaterialKolor seed color `#1D3557`, dark/light mode via `LocalThemeIsDark` CompositionLocal + +### Key Patterns + +- **Modifier system**: `SRModifier.apply(value)` + `accumulateModifiers()` fold for dice roll modifications +- **Serialization**: All model classes are `@Serializable`. `DataLoader` provides `serialize`/`deserialize` for `ShadowrunCharacter`. +- **Platform callbacks**: `App(onThemeChanged)` lets platform entry points react to theme changes (e.g., status bar styling) +- **Compose resources**: Drawables, fonts, and strings in `sharedUI/src/commonMain/composeResources/` + +## Key Dependencies + +- **Compose Multiplatform** 1.9.0 — UI framework +- **kotlinx.serialization** — JSON serialization for all model types +- **MaterialKolor** — Dynamic Material 3 color scheme generation +- **KStore** — Multiplatform key-value persistence +- **Ktor** — HTTP client (platform-specific engines) +- **Coil** — Image loading + +Version catalog: `gradle/libs.versions.toml`