You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
100 lines
4.5 KiB
100 lines
4.5 KiB
# AGENTS.md
|
|
|
|
This file provides guidance to AI coding agents when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Now in Android (KMP edition) — a Kotlin Multiplatform fork of Google's Now in Android reference app. Targets Android, iOS, Desktop (JVM), macOS, and experimental Web (WASM). Uses Compose Multiplatform for shared UI.
|
|
|
|
## Build Commands
|
|
|
|
```bash
|
|
# Format code (must pass before merge)
|
|
./gradlew spotlessApply
|
|
./gradlew spotlessCheck --init-script gradle/init.gradle.kts --no-configuration-cache
|
|
|
|
# Build
|
|
./gradlew :app:assemble # main app (all variants)
|
|
./gradlew :app-nia-catalog:assemble # design system catalog app
|
|
|
|
# Run desktop app
|
|
# Gradle run config task: desktopRun -DmainClass=MainKt --quiet
|
|
|
|
# Unit tests
|
|
./gradlew testDebugUnitTest # all module tests
|
|
./gradlew :feature:foryou:testDebugUnitTest # single module test
|
|
./gradlew :lint:test # lint rule tests
|
|
|
|
# Instrumented tests (requires a connected Android emulator)
|
|
./gradlew connectedDebugAndroidTest
|
|
|
|
# Screenshot tests (Roborazzi — CI only, do NOT run locally)
|
|
# CI records/verifies screenshots and auto-commits updates via PR
|
|
# ./gradlew verifyRoborazziDebug # verify against baselines (CI only)
|
|
# ./gradlew recordRoborazziDebug # record new baselines (CI only)
|
|
|
|
# Lint
|
|
./gradlew :app:lintRelease :app-nia-catalog:lintRelease :lint:lint
|
|
|
|
# Dependency guard
|
|
./gradlew dependencyGuard # check
|
|
./gradlew dependencyGuardBaseline # update baseline
|
|
|
|
# Build-logic check
|
|
./gradlew :build-logic:convention:check
|
|
|
|
# Badging check
|
|
./gradlew :app:checkReleaseBadging
|
|
```
|
|
|
|
## Architecture
|
|
|
|
**Three-layer architecture** with unidirectional data flow (UDF):
|
|
- **UI Layer** (`feature:*`) — Compose screens + ViewModels. Each feature module is independent; no inter-feature dependencies.
|
|
- **Domain Layer** (`core:domain`) — Use cases combining data from multiple repositories.
|
|
- **Data Layer** (`core:data`, `core:database`, `core:datastore`, `core:network`) — Offline-first repositories backed by SQLDelight + Proto DataStore, synced via Ktor/Ktrofit.
|
|
|
|
### Module Structure
|
|
|
|
- **`app`** — Main KMP application with app-level navigation (NiaNavHost, TopLevelDestination). WIP for full multiplatform.
|
|
- **`app-nia-catalog`** — Standalone design system showcase. Fully multiplatform including WASM.
|
|
- **`feature:*`** — Feature modules (foryou, interests, bookmarks, topic, search, settings). Depend only on `core:*` modules.
|
|
- **`core:*`** — Shared libraries. Key ones: `designsystem` (Material 3 components), `ui` (reusable composables), `model` (data types), `data` (repositories), `database` (SQLDelight), `network` (Ktor), `datastore` (Proto DataStore).
|
|
- **`shared`** — Aggregates features and core for the main app.
|
|
- **`sync:work`** — WorkManager-based sync (Android-only).
|
|
- **`build-logic/convention`** — Custom Gradle convention plugins.
|
|
|
|
### Convention Plugins
|
|
|
|
All modules use convention plugins from `build-logic/convention/` (plugin IDs prefixed `nowinandroid.*`):
|
|
- `nowinandroid.kmp.library` — KMP library: configures Android library + KMP targets (JVM, Android, iOS, macOS) + common test deps
|
|
- `nowinandroid.cmp.application` — Compose Multiplatform app (Android, Desktop, iOS, macOS)
|
|
- `nowinandroid.cmp.feature` — Feature module (inherits kmp.library + adds Compose, Koin, core:ui, core:designsystem)
|
|
- `nowinandroid.di.koin` — Koin DI with KSP annotation processing
|
|
- `nowinandroid.sqldelight` — SQLDelight database
|
|
- `nowinandroid.kmp.inject` — kotlin-inject DI via KSP
|
|
|
|
### Key Technology Choices
|
|
|
|
- **DI:** Koin (primary, KMP-friendly service locator) + kotlin-inject (compile-time alternative)
|
|
- **Database:** SQLDelight (multiplatform)
|
|
- **Preferences:** Proto DataStore
|
|
- **Networking:** Ktor client via Ktrofit
|
|
- **Image loading:** Coil 3
|
|
- **Serialization:** kotlinx-serialization
|
|
- **Testing:** No mocking libraries — use test doubles. Roborazzi for screenshot tests (CI only), Turbine for Flow testing.
|
|
|
|
### Build Variants
|
|
|
|
Two build types: `debug` and `release`. No flavor dimensions (demo/prod flavors were removed during KMP migration).
|
|
|
|
### KMP Source Set Layout
|
|
|
|
Modules use Kotlin Multiplatform default hierarchy: `commonMain`/`commonTest`, `androidMain`/`androidUnitTest`/`androidInstrumentedTest`, `jvmMain`/`jvmTest`, `iosMain`, `macosMain`, etc. Android resource prefixes are auto-derived from module path (e.g., `core_model_`).
|
|
|
|
## Requirements
|
|
|
|
- JDK 17+
|
|
- Gradle uses 4GB heap (`-Xmx4g`)
|
|
- Configuration cache and parallel builds enabled
|