AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to WARP (warp.dev) when working with code in this repository.
4 
5## Project Overview
6 
7Komi Store is a cross-platform app store for GitHub releases built with **Kotlin Multiplatform (KMP)** and **Compose Multiplatform**. It targets **Android** (min API 26, target 36) and **Desktop** (Windows, macOS, Linux via JVM).
8 
9Package: `zed.rainxch.githubstore`
10 
11## Build & Run Commands
12 
13```bash
14# Android debug build
15./gradlew :composeApp:assembleDebug
16 
17# Desktop (run in dev mode)
18./gradlew :composeApp:run
19 
20# Full build check (both platforms)
21./gradlew build
22 
23# Lint (ktlint auto-formats on preBuild/compileKotlin* tasks automatically)
24./gradlew ktlintFormat           # manual format all modules
25./gradlew ktlintCheck            # check without fixing
26 
27# Desktop installers
28./gradlew :composeApp:packageDmg    # macOS
29./gradlew :composeApp:packageExe    # Windows
30./gradlew :composeApp:packageDeb    # Linux
31```
32 
33**Requirements:** JDK 21+ (Temurin recommended), Android SDK for Android builds.
34 
35**Setup:** Create a GitHub OAuth App and put `GITHUB_CLIENT_ID=<your_id>` in `local.properties` (root). Callback URL: `githubstore://callback`.
36 
37## Architecture
38 
39**Clean Architecture + MVVM** with strict layer separation:
40 
41- **Domain** — Repository interfaces, models, use cases. No framework dependencies.
42- **Data** — Repository implementations, Ktor API clients, Room DAOs, DTOs, mappers. Each feature's DI module lives in `data/di/SharedModule.kt`.
43- **Presentation** — ViewModels with `StateFlow`/`Channel`, Compose screens.
44 
45### State Management Pattern (every screen)
46 
47Every ViewModel follows the same State/Action/Event pattern:
48 
49- `State` — data class holding all UI state, exposed via `StateFlow`
50- `Action` — sealed interface for user input (clicks, refreshes)
51- `Event` — sealed interface for one-off effects (navigation, toasts), sent via `Channel.receiveAsFlow()`
52 
53### Module Layout
54 
55```text
56composeApp/          # App entry points, navigation, DI wiring
57  src/commonMain/    # Shared UI & wiring
58  src/androidMain/   # Android entry (MainActivity)
59  src/jvmMain/       # Desktop entry (DesktopApp.kt)
60core/
61  domain/            # Shared interfaces, models, use cases
62  data/              # Networking (Ktor), database (Room), DI, platform impls
63  presentation/      # Material 3 theming, reusable UI components, localized strings (13 languages)
64feature/<name>/
65  domain/            # Feature-specific interfaces & models
66  data/              # Feature-specific implementations & Koin DI module
67  presentation/      # Feature ViewModel + Compose screens
68build-logic/convention/  # Custom Gradle convention plugins
69```
70 
71Some features (favourites, starred, recently-viewed, tweaks) are **presentation-only** — they use core repositories directly and register ViewModels in `composeApp/.../di/ViewModelsModule.kt` instead of having a `data/di/` layer.
72 
73### Convention Plugins (build-logic)
74 
75| Plugin ID | Use For |
76| :--- | :--- |
77| `convention.kmp.library` | KMP shared library modules (domain, data) |
78| `convention.cmp.library` | Compose Multiplatform library modules |
79| `convention.cmp.feature` | Feature presentation modules (auto-adds Compose + Koin + core:presentation) |
80| `convention.cmp.application` | Main app module |
81| `convention.room` | Room database modules |
82| `convention.buildkonfig` | Build-time config (reads from local.properties) |
83 
84### Navigation
85 
86Type-safe navigation using `@Serializable` sealed interface `GithubStoreGraph` in `composeApp/.../navigation/GithubStoreGraph.kt`. Routes are wired in `AppNavigation.kt`. Parameterized routes: `DetailsScreen(repositoryId, owner, repo, isComingFromUpdate)`, `DeveloperProfileScreen(username)`.
87 
88### Dependency Injection
89 
90**Koin** — each feature's data layer defines a module in `data/di/SharedModule.kt`. All modules are registered in `composeApp/.../di/initKoin.kt`. ViewModels injected via `koinViewModel()`. `DetailsViewModel` and `MirrorPickerViewModel` use manual Koin `viewModel { }` with `parametersOf()` for constructor args; all others use `viewModelOf(::ClassName)`.
91 
92### Key Cross-Cutting Concerns
93 
94- **Auth flow:** GitHub device-flow OAuth. Primary path goes through backend proxy (`/v1/auth/device/start`, `/v1/auth/device/poll`); falls back to direct GitHub only on infrastructure errors (5xx, timeouts). HTTP 4xx and GitHub's negative 200-bodies never trigger fallback. Backend rate limits (10 starts/hr, 200 polls/hr per IP) are hard — do not add retry loops.
95- **`X-GitHub-Token` header:** Forwarded on every backend passthrough route — `/v1/search`, `/v1/search/explore`, `/v1/repo/{owner}/{name}`, `/v1/releases/{owner}/{name}`, `/v1/readme/{owner}/{name}`, `/v1/user/{username}`. Backend re-sends as `Authorization: token $token` so upstream GitHub calls run under the user's 5000/hr OAuth quota; without it the request falls back to the shared 60/hr anonymous bucket and a single 4xx can poison the backend's 15-min negative cache for everyone. DB-only routes (`/v1/categories`, `/v1/topics`, `/v1/events`, `/v1/auth/device/*`, `/v1/badge/*`) never get the header. Sourced via `BackendApiClient.currentUserGithubToken()` (`private`), never logged. 401 from passthrough routes ≠ session expired — `AuthenticationStateImpl` debounces consecutive 401s under the same token before clearing the session.
96- **Platform branching:** Source sets are `commonMain` (shared), `androidMain` (Android), `jvmMain` (Desktop). Some features (apps, installation, Shizuku) are Android-only.
97- **Shizuku (Android):** Optional silent install via AIDL service. Falls back to standard installer on failure.
98 
99## Coding Conventions
100 
101- Packages: `zed.rainxch.{module}.{layer}` (e.g. `zed.rainxch.home.data.repository`)
102- Private state: underscore prefix `_state`, `_events`
103- Sealed classes/interfaces for type-safe routes, actions, events
104- Repository pattern: interface in `domain/`, implementation in `data/`
105- Ktlint auto-runs on `preBuild`/`compileKotlin*` tasks; `ignoreFailures = true`
106- Ktlint rules: wildcard imports allowed, filename rule disabled, `@Composable` functions exempt from function naming rule (see `.editorconfig`)
107 
108## Adding a New Feature
109 
1101. Create `feature/<name>/domain/`, `feature/<name>/data/`, `feature/<name>/presentation/`
1112. Add `build.gradle.kts` in each using the appropriate convention plugin
1123. Add `include` entries in `settings.gradle.kts`
1134. Define domain interfaces/models in `domain/`
1145. Implement repository + Koin DI module in `data/di/SharedModule.kt`
1156. Create ViewModel (State/Action/Event pattern) and Screen in `presentation/`
1167. Add navigation route to `GithubStoreGraph.kt` and wire in `AppNavigation.kt`
1178. Register the Koin module in `initKoin.kt`
118 
119## Feature-Level Documentation
120 
121Each `feature/` directory contains its own `CLAUDE.md` with module structure, key interfaces, navigation routes, and implementation notes. Read those for feature-specific guidance.
122 
123## Versions
124 
125All library versions managed in `gradle/libs.versions.toml`. Key versions: Kotlin 2.3.10, Compose Multiplatform 1.10.3, Ktor 3.4.0, Room 2.8.4, Koin 4.1.1.
126