docs: add AGENTS.md with build commands, architecture, and conventions

2026-07-09 16:07:30 +02:00
parent de107a4295
commit 64ba5aea5d
1 changed files with 82 additions and 0 deletions
@@ -0,0 +1,82 @@
+# AGENTS.md
+
+## Project
+
+MyIce — Kotlin Multiplatform ice hockey schedule/convocation viewer (Android, iOS, Desktop).
+Port of the Flutter app at `~/work/gitea.parano.ch/herel/myice/myice_mobile/`.
+
+## Build Commands
+
+```bash
+# Compile (desktop)
+./gradlew composeApp:compileKotlinDesktop
+
+# Run desktop app
+./gradlew composeApp:run
+
+# Tests (desktop target — KMP has no commonTest task)
+./gradlew composeApp:desktopTest
+
+# Android debug APK
+./gradlew composeApp:assembleDebug
+
+# Android release APK (requires keystore.properties at project root)
+./gradlew composeApp:assembleRelease
+
+# macOS DMG
+./gradlew composeApp:packageDistributionForCurrentOS
+```
+
+## Lint / Typecheck
+
+There is no separate lint task. Compilation is the type check:
+
+```bash
+./gradlew composeApp:compileKotlinDesktop
+```
+
+## Tech Stack
+
+- Kotlin 2.3.20, Compose Multiplatform 1.11.1, Material 3
+- Ktor 3.5.1 (CIO on Android/Desktop, Darwin on iOS)
+- kotlinx.serialization 1.11.0
+- multiplatform-settings 1.3.0
+- lifecycle-viewmodel-compose 2.10.0
+- Gradle 9.5.1, AGP 8.13.2
+
+## Architecture
+
+Layered: `models → network → cache → filter → viewmodel → ui`
+
+- **commonMain**: all shared code (models, networking, caching, filtering, viewmodels, UI)
+- **androidMain**: Android OAuth (Custom Tabs), MainActivity, CIO engine
+- **iosMain**: iOS OAuth (ASWebAuthenticationSession), MainViewController, Darwin engine
+- **desktopMain**: Desktop OAuth (local HTTP server), Main.kt, CIO engine
+
+Package: `ch.parano.myice`
+
+## Conventions
+
+- Single `composeApp` module, shared UI approach (not per-platform UI)
+- French UI strings (matching the Flutter app)
+- TDD: write tests in `commonTest`, run via `desktopTest` target
+- `expect/actual` for platform-specific code (HttpClient engine, OAuth)
+- No comments in code unless explicitly requested
+- Follow existing file structure: one class per file, organized by layer
+
+## Backend
+
+API at `https://myice.parano.ch` (hardcoded in `network/ApiConfig.kt`).
+Endpoints: `/login`, `/userinfo`, `/accounts`, `/schedule?account=`, `/game/{id}?account=`
+
+## Secrets
+
+- `keystore.properties` and `*.keystore` are gitignored — never commit
+- OAuth tokens stored via multiplatform-settings (plaintext, same as Flutter app)
+
+## Known Limitations
+
+- iOS `.xcodeproj` must be created manually in Xcode (Swift files exist in `iosApp/`)
+- ViewModels use `remember{}` instead of `viewModel()` (state lost on Android rotation)
+- No URL-decoding in token parser (JWT tokens don't need it)
+- `AuthViewModel.init()` logs out on any network error, not just 401