# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

Heimdall is an Android password manager (Jetpack Compose, Kotlin) that also acts as a
system **Autofill service**. Users register/login against a remote backend, then store and
retrieve credentials locally in an encrypted vault.

## Build & Test

```bash
./gradlew assembleDebug          # build debug APK
./gradlew installDebug           # build + install on connected device/emulator
./gradlew test                   # JVM unit tests (src/test)
./gradlew connectedAndroidTest   # instrumented tests on device (src/androidTest)
./gradlew lint                   # Android lint

# single unit test class / method:
./gradlew test --tests "com.longnh15.heimdall.SomeTest"
./gradlew test --tests "com.longnh15.heimdall.SomeTest.someMethod"
```

- Single-module project (`:app`). Dependencies are managed via the version catalog
  `gradle/libs.versions.toml` — add/upgrade libraries there, not inline in `build.gradle.kts`.
- minSdk 26, targetSdk/compileSdk 37, Java 11.

## Architecture

Clean-architecture-style layering under `app/src/main/java/com/longnh15/heimdall/`:

- **`domain/`** — interfaces + models, no Android/framework deps. `repository/` holds repo
  interfaces, `model/` holds domain types (`ApiResult`, `AuthInfo`, `Credential`), `vault/`
  holds the session abstraction.
- **`data/`** — implementations. `repository/*Impl` implement domain interfaces; `source/remote`
  is Retrofit (`ApiService` + `dto/`); `source/local` is Room (`HeimdallDatabase`, `CredentialDao`,
  `entity/` + mappers) plus DataStore; `preferences/` and `vault/` hold other impls.
- **`ui/`** — Compose screens grouped by feature (`auth/login`, `auth/register`, `onboarding`,
  `vault`, `vault/edit`). Each feature follows MVVM: `*Screen` (Compose) + `*ViewModel` +
  `*State` + `*Event` (user intents). State is exposed as `StateFlow` via `stateIn`.
- **`navigation/`** — `Screen` is a `@Serializable sealed class`; routes are type-safe Compose
  Navigation destinations wired in `HeimdallNavGraph`.

Key cross-cutting flows:

- **Network**: repositories extend `BaseRepository` and wrap calls in `safeApiCall { ... }`,
  which converts a Retrofit `Response` into `ApiResult.Success`/`ApiResult.Error`. Error bodies
  are parsed by `ErrorBodyParser.toApiError()`. JSON config lives in `common/GlobalConfig.json`.
  Base URL is hardcoded in `di/NetworkModule`.
- **Auth tokens**: on login, the token is encrypted with `common/TokenCrypto` (AES/GCM key in
  the Android Keystore, IV prepended) and persisted in the `"terces"` DataStore via
  `LocalDataSource`. Never store the token in plaintext.
- **Vault locking**: `VaultSessionManager` (impl in `data/vault`) holds an in-memory
  `Locked`/`Unlocked(expiredAt)` `StateFlow`. `HeimdallApplication` observes
  `ProcessLifecycleOwner` and calls `refreshSession()` on app foreground, re-locking after the
  timeout. ViewModels read `sessionState` to gate access. (Timeout is currently 5 seconds —
  `TIMEOUT_DURATION` in `VaultSessionManagerImpl`.)
- **Autofill**: `HeimdallAutofillService` (registered in the manifest, BIND_AUTOFILL_SERVICE)
  receives an `AssistStructure`; `StructureParser` classifies username/password fields using a
  layered heuristic (autofillHints → inputType → htmlInfo → text/hint keyword matching). The
  fill values in `buildFillResponse` are currently **hardcoded placeholders**, not yet wired to
  the vault.
- **First launch / onboarding**: `MainViewModel` reads `PreferenceDataSource` (`"settings"`
  DataStore) to decide the nav start destination (Onboarding vs Login); the splash screen is held
  until that flag resolves to avoid a flicker.

## Dependency Injection (Koin) — note the inconsistency

DI is **mid-migration between two Koin styles**, and only one is actually loaded:

- `HeimdallApplication.startKoin` loads **only** the manual `appModule` (`di/AppModule.kt`),
  which uses the DSL (`single<Impl>() bind Interface::class`, `viewModel<...>()`).
- Other files use **Koin annotations** (`@Module`, `@Single` in `NetworkModule`/`DatabaseModule`,
  `@KoinViewModel`, `@Singleton`) which require the KSP-generated module to be included to take
  effect. These are **not currently passed to `startKoin`**.

When adding a dependency, prefer registering it in `appModule` so it is actually wired, or
explicitly include the annotation-generated modules in `startKoin`. Don't assume an `@Single`
annotation alone makes a class injectable here.

## Conventions

- Room schemas are exported to `app/schemas/`; bump the DB version and commit the new schema JSON
  when changing entities.
- DTOs (`data/source/remote/dto`) use `kotlinx.serialization` (`@Serializable`); domain models are
  separate types — map between them in the repository.
- Validation lives in `common/ValidationHelper`.