chat_web_app/llm-fe/android/README.md

Hesychia — Android

Native Capacitor project for ai.hesychia.chat. Web UI comes from the CRA build/ output in the parent llm-fe/ package (synced with npx cap sync).

Broader Capacitor notes (env files, icons, QA): ../ANDROID.md.

Prerequisites

• Node.js 20
• JDK 17+
• Android Studio with SDK Platform 35
• ANDROID_HOME set, or open this folder once in Android Studio (writes local.properties)

Build the web bundle and sync

From the npm root (llm-fe/, one level up):

cd ..
npm ci
npm run build:android:store   # Play binary: .env.mobile → build → cap sync android
# npm run build:mobile        # same web env, also syncs iOS

Open this project in Android Studio:

npm run android:open
# or: npx cap open android

Re-sync after changing web code (with an existing build/):

npm run android:sync

Backend URLs are baked in at web-build time via ../.env.mobile (prod by default).

Run on a device / emulator

Android Studio

1. Sync Gradle when prompted.
2. Pick an emulator or USB device (enable USB debugging).
3. Run app.

CLI (debug APK)

./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

Version before a store release

app/build.gradle stores the floor (hesychiaVersionNameFloor / hesychiaVersionCodeFloor). A local bundleRelease uses that floor. Deploy Prod passes the next pair with -PhesychiaVersionName and -PhesychiaVersionCode after reading android-v* Gitea releases, so a prod run does not need a version commit.

Field	Rule
versionName	User-visible major.minor.patch
versionCode	Integer; must increase for every Play upload

Sign a release build

Do not commit keystores or passwords.

1. Create an upload keystore (once), outside the repo:

keytool -genkey -v -keystore /home/westfarn/.android/hesychia-upload.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias aiml-chat-upload

Reuse an existing Play upload key. Do not generate a second keystore for an app that already has one.

2. Create keystore.properties in this directory (android/, gitignored). On the Deploy Prod runner the file is /home/westfarn/.android/hesychia-keystore.properties (not RealPath’s keystore.properties):

storeFile=/home/westfarn/.android/hesychia-upload.jks
storePassword=REPLACE_ME
keyAlias=aiml-chat-upload
keyPassword=REPLACE_ME

3. Build a signed App Bundle:

./gradlew bundleRelease

Output:

app/build/outputs/bundle/release/app-release.aab

Signed APK (if needed):

./gradlew assembleRelease
# → app/build/outputs/apk/release/app-release.apk

Without keystore.properties, release builds are unsigned; debug builds do not need it.

Deploy to Google Play

Deploy Prod builds the signed AAB and attaches it to a Gitea release (android-v<versionName>-<versionCode>, asset hesychia-<versionName>-<versionCode>.aab). Download that asset and upload it yourself. See ../ANDROID.md.

1. Play Console → app Hesychia (ai.hesychia.chat).
2. Complete store listing: privacy policy URL, data-safety form, screenshots.
3. Set Account deletion URL to the public instructions page (no sign-in required):
   • https://hesychia.ai/account-deletion/ (preferred product host)
   • or https://chat.aimloperations.com/account-deletion/ until hesychia.ai cutover
4. Testing → Internal testing → create release → upload app-release.aab.
5. Add testers, roll out internal track, verify on devices.
6. Promote to closed / open / production only after internal QA passes.

See also ../ANDROID.md Play checklist and issue #103.

Each new upload needs a higher versionCode.

Useful Gradle tasks

Task	Purpose
./gradlew assembleDebug	Debug APK
./gradlew assembleRelease	Release APK (signed if props present)
./gradlew bundleRelease	Play Store .aab
./gradlew clean	Clean build outputs

App identity

Application ID	ai.hesychia.chat
Display name	Hesychia
Min / target SDK	23 / 35 (see variables.gradle)