# RewardFlow Terminal — Android Setup

## Prerequisites

### 1. Install Android Studio

```bash
# Download Android Studio (Xubuntu/Ubuntu)
sudo snap install android-studio --classic

# Or via apt (if snap not available)
# Download from https://developer.android.com/studio
# Extract and run: ./android-studio/bin/studio.sh
```

Android Studio bundles:
- JDK 17 (no need to install separately)
- Android SDK
- Gradle
- Android Emulator

### 2. First-time Android Studio setup

1. Open Android Studio
2. Choose "Standard" installation
3. Accept SDK licenses: `Tools → SDK Manager → SDK Platforms → Android 15 (API 35)`
4. Install: `Tools → SDK Manager → SDK Tools`:
   - Android SDK Build-Tools
   - Android SDK Platform-Tools
   - Android Emulator
   - Google Play services (for ML Kit barcode scanning)

### 3. Open the project

1. `File → Open` → navigate to `clients/terminal-android/`
2. Wait for Gradle sync (first time downloads ~500MB of dependencies)
3. If prompted about Gradle JDK, select the bundled JDK 17

### 4. Create a tablet emulator

1. `Tools → Device Manager → Create Virtual Device`
2. Category: **Tablet** → pick **Pixel Tablet** or **Nexus 10**
3. System image: **API 35** (download if needed)
4. Finish

### 5. Run the app

1. Select the tablet emulator in the device dropdown
2. Click ▶️ Run
3. The app opens in landscape fullscreen

## Project structure

```
clients/terminal-android/
├── app/
│   ├── build.gradle.kts          # App dependencies (like requirements.txt)
│   ├── src/main/
│   │   ├── AndroidManifest.xml   # App permissions & config
│   │   ├── java/lu/rewardflow/terminal/
│   │   │   ├── RewardFlowApp.kt  # Application entry point
│   │   │   ├── MainActivity.kt   # Single activity (Compose)
│   │   │   ├── ui/               # Screens (Setup, PIN, Terminal)
│   │   │   ├── data/             # API, DB, models, sync
│   │   │   └── di/               # Dependency injection (Hilt)
│   │   └── res/                  # Resources (strings, themes, icons)
│   └── proguard-rules.pro        # Release build obfuscation rules
├── gradle/
│   ├── libs.versions.toml        # Version catalog (all dependency versions)
│   └── wrapper/                  # Gradle wrapper (pinned version)
├── build.gradle.kts              # Root build file
├── settings.gradle.kts           # Project settings
└── .gitignore
```

## Key dependencies (in gradle/libs.versions.toml)

| Library | Purpose |
|---------|---------|
| Jetpack Compose | UI framework (declarative, like SwiftUI) |
| Retrofit + Moshi | HTTP client + JSON parsing (calls the Orion API) |
| Room | SQLite ORM (offline transaction queue) |
| WorkManager | Background sync (retry pending transactions) |
| Hilt | Dependency injection |
| CameraX + ML Kit | Camera preview + QR/barcode scanning |
| DataStore | Key-value persistence (device config, auth token) |

## API connection

- **Debug builds**: connect to `http://10.0.2.2:8000` (Android emulator's localhost alias)
- **Release builds**: connect to `https://rewardflow.lu`
- Configure in `app/build.gradle.kts` → `buildConfigField("DEFAULT_API_URL", ...)`

## Building a release APK

```bash
cd apps/terminal-android
./gradlew assembleRelease
# APK at: app/build/outputs/apk/release/app-release.apk
```