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>
3.4 KiB
3.4 KiB
RewardFlow Terminal — Android Setup
Prerequisites
1. Install Android Studio
# 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
- Open Android Studio
- Choose "Standard" installation
- Accept SDK licenses:
Tools → SDK Manager → SDK Platforms → Android 15 (API 35) - 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
File → Open→ navigate toapps/terminal-android/- Wait for Gradle sync (first time downloads ~500MB of dependencies)
- If prompted about Gradle JDK, select the bundled JDK 17
4. Create a tablet emulator
Tools → Device Manager → Create Virtual Device- Category: Tablet → pick Pixel Tablet or Nexus 10
- System image: API 35 (download if needed)
- Finish
5. Run the app
- Select the tablet emulator in the device dropdown
- Click ▶️ Run
- 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
cd apps/terminal-android
./gradlew assembleRelease
# APK at: app/build/outputs/apk/release/app-release.apk