Samir Boulahtit
e759282116
Some checks failed
Rename apps/ → clients/ for clarity: - app/ (singular) = Python backend (FastAPI, server-rendered web UI) - clients/ (plural) = standalone client applications (API consumers) The web storefront/store/admin stays in app/ because it's server- rendered Jinja2, not a standalone frontend. clients/ is for native apps that connect to the API externally. Updated: - docs/architecture/overview.md — added clients/ to project structure - clients/terminal-android/SETUP.md — updated path references 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 toclients/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
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
cd apps/terminal-android
./gradlew assembleRelease
# APK at: app/build/outputs/apk/release/app-release.apk