Samir Boulahtit
1df1b2bfca
Some checks failed
Native Android tablet app for loyalty POS terminal. Replaces web terminal for merchants who need device lockdown, camera QR scanning, and offline operation. Project at apps/terminal-android/ — Kotlin, Jetpack Compose, calls the same /api/v1/store/loyalty/* API (no backend changes). Scaffold includes: - Gradle build (Kotlin DSL) with version catalog (libs.versions.toml) - Hilt DI, Retrofit + Moshi networking, Room offline DB - CameraX + ML Kit barcode scanning dependencies - DataStore for device config persistence - WorkManager for background sync - Three-screen navigation: Setup → PIN → Terminal - Stub screens with layout structure (ready to implement) - API models matching all loyalty store endpoints - PendingTransaction entity + DAO for offline queue - RewardFlow brand theme (purple, light/dark) - Landscape-only, fullscreen, Lock Task Mode ready - SETUP.md with Android Studio installation guide - .gitignore for Android build artifacts Tech decisions: - Min SDK 26 (Android 8.0, 95%+ tablet coverage) - Firebase App Distribution for v1, Play Store later - Staff PIN auth (no username/password on POS) - One-time device setup via QR code from web settings Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
# 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 `apps/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
|
|
|
|
```
|
|
apps/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
|
|
```
|