chat_web_app/llm-fe/ANDROID.md

Android (Capacitor)

Ship the CRA web build as an Android app via Capacitor. One codebase: llm-fe/ → web + Android + iOS WebView.

Build & Play deploy steps: android/README.md. iOS sibling: IOS.md / ios/README.md.

Prerequisites for blockers already merged: JWT-only auth (#22), WebSocket lifecycle (#23), HashRouter (#24).

Prerequisites

• Node.js 20 (matches CI; Capacitor 7.x)
• JDK 17+ (OpenJDK fine)
• Android Studio (Ladybug+) with Android SDK Platform 35, build-tools, and an emulator or device
• Set ANDROID_HOME (or open the project once in Android Studio so local.properties is generated)

One-time / day-to-day

cd llm-fe
npm ci
npm run build:mobile   # loads .env.mobile → CRA build → cap sync android
npm run android:open   # opens android/ in Android Studio

Or sync only after an existing build/:

npm run android:sync

Environment

File	Purpose
.env.mobile	Endpoints baked into the mobile bundle (build:mobile)
.env.production	Web prod deploys (build / build:prod)
.env.beta	Web beta deploys

Default .env.mobile matches production (chatbackend.aimloperations.com). Point it at beta to flip the shell without touching web deploys. Optional gitignored override: .env.mobile.local.

Versioning

In android/app/build.gradle:

• versionName — user-visible string; keep aligned with package.json version (currently 0.1.0)
• versionCode — integer; must increase for every Play Store upload

Bump both before each store release.

Icons / splash

Source art lives in llm-fe/assets/:

• icon.png / splash.png / splash-dark.png — Capacitor inputs (Hesychia meander mark)
• logo-source.png — cropped square master
• logo-mark-transparent.png — circular mark with transparent corners (web / in-app)

In-app UI also imports src/llm-fe/assets/brand/hesychia-mark.png.

Regenerate Android densities after changing source art:

npm run assets:generate

Same command also regenerates iOS Assets.xcassets (see IOS.md).

Signing (upload keystore)

Never commit keystores. Store outside the repo (e.g. host secrets / password manager).

keytool -genkey -v -keystore ~/Documents/secrets/aiml-chat-upload.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias aiml-chat-upload

Create llm-fe/android/keystore.properties (gitignored):

storeFile=/absolute/path/to/aiml-chat-upload.jks
storePassword=...
keyAlias=aiml-chat-upload
keyPassword=...

Release App Bundle:

cd llm-fe/android
./gradlew bundleRelease
# → app/build/outputs/bundle/release/app-release.aab

Debug APK (no signing props needed):

./gradlew assembleDebug

Manual QA checklist

On emulator and physical device:

• Login / logout / password reset flows
• Chat streaming + markdown / code blocks
• Charts (recharts)
• Dark / light theme
• Hardware back: navigates history, exits at root
• Keyboard does not cover compose input; notch/safe-area OK
• Background → resume keeps or reconnects WebSocket
• Airplane mode → restore reconnects

Play Store (internal testing first)

Out of band ops (not automated here):

1. Google Play developer account
2. Privacy policy URL (product site / legal)
3. Data safety form (JWT auth, chat content, analytics if Tianji runs in WebView)
4. Screenshots for phone (+ tablet if targeting)
5. Upload .aab to internal testing track before production

Related issues

• #20 — this Android wrap
• #21 — iOS (reuses this scaffolding)
• #22 / #23 / #24 — auth / WS / routing