# Gold AI Terminal — Android APK Build Guide

Build a native Android APK from the PWA using Capacitor (Ionic).

---

## Prerequisites

| Tool | Version | Download |
|------|---------|----------|
| Node.js | >= 18 | https://nodejs.org |
| Android Studio | Latest | https://developer.android.com/studio |
| JDK | 17+ | bundled with Android Studio |
| Git | Any | https://git-scm.com |

Make sure `ANDROID_HOME` and `JAVA_HOME` environment variables are set.

---

## Step 1 — Install Dependencies

Open a terminal in the project root:

```bash
cd "gold_ai_institutional_terminal_v2"
npm install
```

---

## Step 2 — Initialize Capacitor

```bash
npx cap init "Gold AI Terminal" com.goldai.terminal --web-dir web
```

This creates `capacitor.config.json` (already included in the project).

---

## Step 3 — Add Android Platform

```bash
npx cap add android
```

This generates the `android/` folder with a full Gradle project.

---

## Step 4 — Sync Web Assets

```bash
npx cap sync android
```

Run this every time you change files in `web/`.

---

## Step 5 — Generate Icons (Required)

The manifest references PNG icons. Generate them from the SVG:

```bash
# Install sharp (one-time)
npm install --save-dev sharp

# Run generator
node tools/generate-icons.js
```

Or use an online SVG-to-PNG converter and save PNGs to `web/icons/`:

```
web/icons/icon-72.png
web/icons/icon-96.png
web/icons/icon-128.png
web/icons/icon-144.png
web/icons/icon-152.png
web/icons/icon-192.png
web/icons/icon-192-maskable.png
web/icons/icon-384.png
web/icons/icon-512.png
web/icons/icon-512-maskable.png
```

---

## Step 6 — Open in Android Studio

```bash
npx cap open android
```

Android Studio opens the `android/` Gradle project.

---

## Step 7 — Configure App in Android Studio

1. In `android/app/src/main/AndroidManifest.xml` verify:
   - `android:label="Gold AI Terminal"`
   - `android:theme="@style/AppTheme.NoActionBar"`

2. In `android/app/build.gradle`:
   ```gradle
   android {
       compileSdkVersion 34
       defaultConfig {
           applicationId "com.goldai.terminal"
           minSdkVersion 26
           targetSdkVersion 34
           versionCode 2
           versionName "2.0.0"
       }
   }
   ```

---

## Step 8 — Build Debug APK

In Android Studio:
- Menu → **Build → Build Bundle(s) / APK(s) → Build APK(s)**
- APK location: `android/app/build/outputs/apk/debug/app-debug.apk`

Or via terminal:
```bash
cd android
./gradlew assembleDebug
```

---

## Step 9 — Build Release APK (for distribution)

### 9a. Generate a keystore (one-time)
```bash
keytool -genkeypair -v \
  -keystore android/keystore/release.keystore \
  -alias goldai \
  -keyalg RSA -keysize 2048 \
  -validity 10000
```

### 9b. Configure signing in `android/app/build.gradle`
```gradle
android {
    signingConfigs {
        release {
            storeFile file("../../keystore/release.keystore")
            storePassword "YOUR_STORE_PASSWORD"
            keyAlias "goldai"
            keyPassword "YOUR_KEY_PASSWORD"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled false
        }
    }
}
```

### 9c. Build release APK
```bash
cd android
./gradlew assembleRelease
```

Release APK: `android/app/build/outputs/apk/release/app-release.apk`

---

## Step 10 — Install on Android Device

Enable **Developer Options → USB Debugging** on your Android device, then:

```bash
adb install android/app/build/outputs/apk/debug/app-debug.apk
```

Or simply copy the APK to the device and open it.

---

## Alternative: PWABuilder (No Android Studio)

1. Start the server: `npm start`
2. Visit https://www.pwabuilder.com
3. Enter `http://localhost:3000`
4. Download the Android package (TWA)
5. Install the signed APK directly

---

## Alternative: Chrome PWA Install (No APK needed)

On Android Chrome:
1. Open `http://your-server-ip:3000`
2. Tap the browser menu (⋮)
3. Tap **"Add to Home Screen"**
4. The app installs as a standalone PWA (identical experience to APK)

---

## Troubleshooting

| Issue | Fix |
|-------|-----|
| `ANDROID_HOME not set` | Set env var to SDK path (e.g. `C:\Users\DELL\AppData\Local\Android\Sdk`) |
| `Gradle build failed` | Run `cd android && ./gradlew clean` then rebuild |
| `White screen on open` | Run `npx cap sync android` then rebuild APK |
| Icons missing | Generate PNG icons from SVG (Step 5) |
| `adb not found` | Add `%ANDROID_HOME%\platform-tools` to PATH |

---

## File Structure After Android Setup

```
gold_ai_institutional_terminal_v2/
├── web/                     ← PWA frontend
│   ├── index.html
│   ├── dashboard.js
│   ├── manifest.json
│   ├── service-worker.js
│   ├── offline.html
│   ├── icon.svg
│   └── icons/               ← PNG icons (generate these)
├── server/                  ← Node.js backend
│   ├── server.js
│   └── risk_engine.js
├── android/                 ← Generated by Capacitor
│   └── app/build/outputs/apk/
├── tools/
│   └── generate-icons.js
├── capacitor.config.json
└── package.json
```

---

*Gold AI Institutional Terminal v2.0 — Android Build Guide*
