# ⚠️ IMPORTANT: Android Build File Locations

## Critical Information for Future Development

**DO NOT EDIT FILES IN `src-tauri/gen/android/` DIRECTLY!**

### File Structure

This project has **TWO** sets of Android source files:

1. **`src-tauri/android/`** - **SOURCE FILES** (edit these!)
   - This is the template directory
   - Changes here need to be copied to the generated directory

2. **`src-tauri/gen/android/`** - **GENERATED BUILD DIRECTORY** (do not edit directly!)
   - This is where Gradle actually builds the APK
   - Files here may be overwritten during builds

### How to Make Changes to Android Code

When you need to modify Android/Kotlin files:

1. **Edit the files in `src-tauri/android/src/main/java/`**
2. **Build using the provided script (which auto-syncs files)**
   ```bash
   ./scripts/build-android.sh
   ```

   The build script automatically runs `./scripts/sync-android-sources.sh` which copies:
   - `src-tauri/android/src/main/java/com/dtourolle/jellytau/player/` → generated directory
   - `src-tauri/android/src/main/java/com/dtourolle/jellytau/security/` → generated directory

3. **Manual sync (if needed)**
   ```bash
   ./scripts/sync-android-sources.sh
   ```

### Why This Matters

- If you only edit `src-tauri/gen/android/`, your changes will be lost
- If you only edit `src-tauri/android/`, your changes won't be in the build
- **You must edit both** (or edit source and copy to generated)

### Debug and release install side by side

The **debug** build type sets `applicationIdSuffix = ".debug"` in
`app/build.gradle.kts`, so a debug build is a genuinely separate Android app:

| build | applicationId | launcher name | versionName | signed with |
|---|---|---|---|---|
| `release` | `com.dtourolle.jellytau` | jellytau | `0.5.5` | real key (`.env`) |
| `release --debug` | `com.dtourolle.jellytau.debug` | JellyTau Debug | `0.5.5-debug-release` | debug keystore |
| `debug` | `com.dtourolle.jellytau.debug` | JellyTau Debug | `0.5.5-debug` | debug keystore |

`release --debug` is the **side-by-side release**: fully R8-minified, exactly
what ships, but packaged into the debug slot and signed with the local debug
keystore. It exists because R8 has broken release APKs here before (stripping
JNI-loaded player/security classes), and reproducing that previously meant
building with the real key and clobbering your working install. It shares the
applicationId *and* signature with the plain debug build, so the two replace
each other cleanly; only the versionName suffix tells you which is installed.

```bash
./scripts/build-and-deploy.sh release --device --debug   # build + install it
```

The flag is plumbed through as `JT_SIDE_BY_SIDE=1`, read by `build.gradle.kts`.
CI never sets it, so distributable release builds are untouched.

That means:

- **No uninstall step.** Debug builds are signed with the local auto-generated
  `~/.android/debug.keystore`, release builds with the real key. Two different
  keys on the *same* package is `INSTALL_FAILED_UPDATE_INCOMPATIBLE`; two
  different packages is just two apps.
- Each has **its own data directory** — separate settings, credentials,
  downloads and offline cache. A debug experiment cannot corrupt the state of
  the build you actually use. This is not optional and cannot be shared:
  Android gives each applicationId its own UID and enforces the boundary in the
  kernel. (`sharedUserId` is deprecated since API 29 and cannot be added to an
  already-installed app anyway.) You log in again in the debug app, once.
- Only the *application* id changes. Kotlin classes stay in the `namespace`
  package `com.dtourolle.jellytau`, so the JNI class lookups in
  `src-tauri/src/player/android/mod.rs`, the manifest `<service>` entry and the
  R8 keep rules in `proguard-jellytau.pro` are all unaffected. The FileProvider
  authority is `${applicationId}.fileprovider`, so it follows the suffix
  automatically.
- The launcher labels come from the `appLabel` / `activityLabel`
  manifestPlaceholders (`AndroidManifest.xml` uses `${appLabel}`), *not* from
  `resValue`, which would collide with Tauri's generated `strings.xml`.

Follow the right log stream with `./scripts/logcat.sh [debug|release]`
(defaults to debug).

### Key Files

Player-related Kotlin files:
- `player/JellyTauPlayer.kt` - Main player implementation
- `player/JellyTauPlaybackService.kt` - MediaSession service for lockscreen controls
- `security/SecureStorage.kt` - Android Keystore integration for secure credential storage

Always check BOTH locations exist and match after making changes!