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>
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 `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
|
|
```
|