# CLAUDE.md

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

## Build Commands

```powershell
# Build debug APK
./gradlew assembleDebug

# Build release APK
./gradlew assembleRelease

# Run unit tests
./gradlew test

# Run instrumented tests (requires connected device/emulator)
./gradlew connectedAndroidTest

# Run a single unit test class
./gradlew :app:test --tests "com.mob.utsmyammer.ExampleUnitTest"

# Clean build
./gradlew clean assembleDebug
```

## Architecture Overview

**MOBPOS** is a mobile Point-of-Sale system for Myanmar, targeting Sunmi hardware devices (card readers, PIN pads, thermal printers). It processes EMV card transactions (sale, void, refund, settlement) and QR payments (MMQR, Wave Pay).

### Single-Activity Compose App

`MainActivity` hosts the entire app. Navigation is handled by Compose Navigation (`AppNavGraph.kt`) with typed routes defined in a sealed `Routes` object.

### MVVM with Shared State

- Each screen has a dedicated `ViewModel` (Hilt-injected)
- `SharedViewModel` in `viewmodel/` is the central state holder for cross-screen transaction data (card info, amount, transaction type, approval codes)
- Hardware interaction is abstracted into `CardReaderViewModel` and `EmvTransactionProcessViewModel`
- State is a mix of `LiveData` (older screens) and `StateFlow` (newer screens like card reading)

### Screen Structure Pattern

Every feature follows: `ui/<feature>/` containing:
- `*Screen.kt` — Composable UI
- `*ViewModel.kt` — business logic and state

### Key Transaction Flow

Dashboard → InputAmount → CardWaiting → ProcessingCard → SendingToHost → TransactionResult → PrintReceipt

### Local Modules

The app depends on several local library modules (in `settings.gradle.kts`):
- `:baselib` — Room DB, Retrofit, Hilt base setup
- `:paylibs` / `:paysdk-lib` — Payment SDK wrappers
- `:ecr` / `:ecr-service-lib` — Electronic Cash Register integration
- `:mpulib` / `:mpu-lib` — Mini POS Unit hardware
- `:sunmiui-lib` — Sunmi device UI components
- `:qrgen-lib` — QR code generation

### Key Dependencies

- **UI:** Jetpack Compose + Material 3, Compose Navigation
- **DI:** Hilt 2.59.2 with KSP
- **Async:** RxJava 3 + RxAndroid (primary async pattern)
- **Network:** Retrofit 3 + OkHttp 4 + GSON
- **DB:** Room 2.4.3 with RxJava 3 support
- **Hardware:** Sunmi SDK (card reader, PIN pad, printer APIs)

### Package Layout

```
com.mob.utsmyammer/
├── config/          # Constants, SunmiPayManager
├── model/           # Data models (CardTransactionType, ProcessCode, TransactionStatus)
│   └── ecr/         # ECR-specific models
├── ui/              # All Compose screens (one subdir per feature)
│   ├── components/  # Shared reusables (NumericEntryScreen, SquareButton, AppBar)
│   ├── navigation/  # AppNavGraph, Routes
│   └── theme/       # Compose theme and colors
├── utils/           # Utility functions
└── viewmodel/       # Shared ViewModels (SharedViewModel, CardReaderViewModel, etc.)
```

## Hardware Integration Notes

Sunmi device permissions are declared in `AndroidManifest.xml` (LED, MSR, ICC, PINPAD, PRINTER). When modifying card reading or PIN entry flows, be aware that `CardReaderViewModel` and the Sunmi ECR service handle hardware callbacks via RxJava subjects. Hardware callbacks arrive on background threads — always observe on the main thread before updating UI state.

## Build Configuration

- `compileSdk 36`, `minSdk 24`, `targetSdk 36`
- Java 11 toolchain, Kotlin 2.2.10
- Compose BOM 2026.02.01
- ProGuard/minification is **disabled** for all build types
- Application ID: `com.mob.ustmm`