nowinandroid/AGENTS.md

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

# 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