# Development Setup Guide

Complete guide for running and debugging the Zelara mobile app in different environments.

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Quick Start](#quick-start)
3. [Development Workflows](#development-workflows)
   - [VS Code + Metro CLI](#vs-code--metro-cli)
   - [Android Studio + Metro](#android-studio--metro)
4. [Understanding Metro Bundler](#understanding-metro-bundler)
5. [Troubleshooting](#troubleshooting)
6. [Build Configurations](#build-configurations)

---

## Prerequisites

### Required Software

- **Node.js**: >= 18.x
- **npm** or **yarn**
- **JDK**: 17 (configured in [build.gradle:108-110](../android/app/build.gradle#L108-L110))
- **Android Studio**: Latest stable version
- **Android SDK**: API 35 (compileSdk), API 34 (targetSdk), API 24+ (minSdk)
- **Android NDK**: 27.2.12479018

### Environment Setup

1. **Install dependencies:**
   ```bash
   cd apps/mobile
   npm install
   ```

2. **Verify Android environment:**
   ```bash
   # Check ANDROID_HOME is set
   echo $ANDROID_HOME  # Linux/Mac
   echo $env:ANDROID_HOME # Windows

   # Verify SDK installation
   adb --version
   ```

3. **Connect device or start emulator:**
   ```bash
   # List connected devices
   adb devices

   # Or start Android Studio AVD Manager and launch an emulator
   ```

---

## Quick Start

### **Option A: VS Code (Recommended for beginners)**

```bash
cd apps/mobile
npm run android
```

This automatically:
1. Starts Metro bundler
2. Builds debug APK
3. Installs APK on device/emulator
4. Runs the app

### **Option B: Android Studio (Current workflow)**

**IMPORTANT:** When using Android Studio, Metro does NOT start automatically.

**Step 1: Start Metro manually**
```bash
cd apps/mobile
npm run start
```

**Step 2: Run app in Android Studio**
- Click **Run** (▶️) button
- Or: `Run > Run 'app'`
- Or: `Shift + F10`

---

## Development Workflows

### VS Code + Metro CLI

Best for: Terminal-first developers, CI/CD scripts, automated testing

#### Standard Workflow

1. **Start Metro + Build + Run (all-in-one):**
   ```bash
   cd apps/mobile
   npm run android
   ```

2. **Alternative: Separate Metro server (more control):**
   ```bash
   # Terminal 1: Start Metro
   cd apps/mobile
   npm run start

   # Terminal 2: Build and run
   npm run android
   ```

#### Debugging in VS Code

1. **Install React Native Tools extension:**
   - Extension ID: `msjsdiag.vscode-react-native`

2. **Add `.vscode/launch.json` configuration:**
   ```json
   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": "Debug Android",
         "cwd": "${workspaceFolder}/apps/mobile",
         "type": "reactnative",
         "request": "launch",
         "platform": "android"
       }
     ]
   }
   ```

3. **Start debugging:**
   - Press `F5` or `Run > Start Debugging`
   - Set breakpoints in TypeScript/JavaScript files
   - Use Debug Console for evaluation

#### Hot Reload

- **Fast Refresh**: Enabled by default - saves automatically reload
- **Manual reload**: Shake device or press `R` twice in Metro terminal
- **Dev menu**: Shake device or `Cmd+M` (Mac) / `Ctrl+M` (Windows/Linux)

---

### Android Studio + Metro

Best for: Native module development, UI inspection, Android-specific debugging

> **📖 Detailed Build Setup:** See [Android-Studio-Build-Setup.md](Android-Studio-Build-Setup.md) for:
> - Initial build configuration and troubleshooting
> - Automating Metro bundler in run configuration
> - Fixing Kotlin compilation errors
> - Build verification and testing

#### **Critical Understanding: Why Metro Doesn't Auto-Start**

Android Studio is an **Android native IDE** - it only handles:
- Gradle builds
- Native code compilation (Kotlin/Java)
- APK packaging and installation

It does **NOT**:
- Start JavaScript Metro bundler
- Bundle JS code in debug builds (by design: [build.gradle:64](../android/app/build.gradle#L64))

#### **The Two-Step Workflow**

**Step 1: Start Metro Bundler**

In **VS Code integrated terminal** or **external terminal**:
```bash
cd apps/mobile
npm run start
```

You should see:
```
                     ######                ######
                 ###     ####          ####     ###
                ##          ###      ###          ##
                ##             ##  ##             ##
                ##             ##  ##             ##
                ##           ##      ##           ##
                ##         ###          ###         ##
                 ##  ####                  ####  ##
                  #######                    ########

               Welcome to Metro v0.76.6
              Fast - Scalable - Integrated

 BUNDLER  Metro is now listening on port 8081
```

**Keep this terminal open** while developing.

**Step 2: Build & Run in Android Studio**

1. Open `apps/mobile/android/` in Android Studio
2. Wait for Gradle sync to complete
3. Select device/emulator from dropdown
4. Click **Run** (▶️) or press `Shift + F10`

**What happens:**
- Android Studio builds APK **without bundled JS** (debug mode)
- APK is installed on device
- App launches and connects to Metro at `localhost:8081`
- Metro serves JavaScript bundle to the app

#### Port Forwarding (USB Debugging) - REQUIRED

**IMPORTANT:** When connecting phone via USB, you **MUST** run this command every time:

```bash
# Forward port 8081 from device to computer
adb reverse tcp:8081 tcp:8081
```

**Why:** USB-connected Android devices don't automatically forward localhost ports. Without this command:
- Metro runs on computer at `localhost:8081`
- Device tries to connect to `localhost:8081` on **itself** (not computer)
- Result: "Unable to load script" error

**When to run:**
- ✅ Every time you connect phone via USB
- ✅ After unplugging and re-plugging USB cable
- ✅ After restarting adb (`adb kill-server` / `adb start-server`)
- ✅ If you see "Metro server not found" errors

**Verify it's working:**
```bash
# Should show the port forwarding
adb reverse --list
# Expected output:
# tcp:8081 tcp:8081
```

**Alternative - Skip Port Forwarding (Wireless Metro):**

If you don't want to run `adb reverse` every time:

1. Find your computer's IP address:
   ```bash
   # Windows
   ipconfig
   # Look for "Wireless LAN adapter Wi-Fi" → "IPv4 Address"

   # Mac/Linux
   ifconfig | grep inet
   ```

2. In the mobile app:
   - Shake device to open Dev Menu
   - Settings → Debug server host & port
   - Enter: `192.168.x.x:8081` (your computer's IP)
   - Reload app

3. **Requirement:** Phone and computer must be on same WiFi network

For wireless debugging, ensure device and computer are on same network.

#### Debugging with Android Studio

**Native Code (Kotlin/Java):**
- Set breakpoints in `.kt` or `.java` files
- Use Android Studio debugger (works normally)

**JavaScript/React Code:**
1. Ensure Metro is running
2. In app, open Dev Menu: Shake device or `Cmd+M` / `Ctrl+M`
3. Select **"Open Debugger"** → Opens Chrome DevTools or React Native DevTools
4. Set breakpoints in Sources tab

**Logcat for Crash Logs:**
- View → Tool Windows → Logcat
- Filter by package: `ai.zelara.mobile`
- Look for `ReactNativeJS` tag for JS errors

#### Hot Reload in Android Studio

Works the same as CLI workflow:
- **Fast Refresh**: Auto-reloads on save
- **Manual reload**: `R` key twice in Metro terminal
- **Clear cache and reload**: Dev Menu → Reload

---

## Understanding Metro Bundler

### What is Metro?

Metro is React Native's JavaScript bundler that:
- Transforms TypeScript/JSX → JavaScript
- Bundles all JS modules into single file
- Serves bundle to app via HTTP (development)
- Provides Fast Refresh (hot reload)

### Metro vs Gradle

| Component | Role | When It Runs |
|-----------|------|--------------|
| **Metro** | Bundles JavaScript code | `npm run start` or `npm run android` |
| **Gradle** | Builds Android native code | Android Studio build or `npm run android` |

### Debug vs Release Builds

**Debug Build** ([build.gradle:64](../android/app/build.gradle#L64)):
- `bundleInDebug: false` - JS NOT bundled into APK
- App expects Metro server at `localhost:8081`
- Fast Refresh enabled
- Not optimized, includes dev tools

**Release Build** ([build.gradle:65](../android/app/build.gradle#L65)):
- `bundleInRelease: true` - JS bundled into APK
- Standalone APK, no Metro needed
- Minified, optimized, production-ready

---

## Troubleshooting

### Error: "Unable to load script. Make sure you're either running Metro..."

**Screenshot Reference:** Your error message from 14:02:42

**Cause:** APK built without bundled JS, but Metro server not running.

**Solution:**
```bash
# Start Metro in separate terminal
cd apps/mobile
npm run start
```

Then reload app:
- Shake device → Reload
- Or close and reopen app

---

### Error: "Unable to instantiate application"

```
ClassNotFoundException: Didn't find class "ai.zelara.mobile.MainApplication"
```

**Cause:** Build cache corruption or Gradle sync issue.

**Solution:**
```bash
cd apps/mobile/android
./gradlew clean
./gradlew assembleDebug

# Then rebuild in Android Studio
```

---

### Error: "dlopen failed: library 'libreact_featureflagsjni.so' not found"

**Cause:** Native libraries not properly linked (New Architecture issue).

**Solution:**

1. **Clean build:**
   ```bash
   cd apps/mobile/android
   ./gradlew clean
   rm -rf .gradle
   rm -rf app/build
   ```

2. **Rebuild dependencies:**
   ```bash
   cd apps/mobile
   rm -rf node_modules
   npm install
   ```

3. **Verify New Architecture is enabled:**
   Check [gradle.properties:35](../android/gradle.properties#L35):
   ```properties
   newArchEnabled=true
   ```

4. **Rebuild:**
   ```bash
   cd apps/mobile
   npm run android
   ```

---

### Metro Port 8081 Already in Use

**Error:** `EADDRINUSE: address already in use :::8081`

**Solution:**

**Find and kill process:**
```bash
# Linux/Mac
lsof -i :8081
kill -9 <PID>

# Windows
netstat -ano | findstr :8081
taskkill /PID <PID> /F
```

**Or use different port:**
```bash
npm run start -- --port 8082
```

Then update port forwarding:
```bash
adb reverse tcp:8082 tcp:8082
```

---

### App Crashes Immediately After Install

**Check Logcat:**

1. Android Studio → Logcat
2. Filter: `package:ai.zelara.mobile`
3. Look for `FATAL EXCEPTION` or `ReactNativeJS` errors

**Common causes:**
- Missing native dependencies
- Incorrect package name
- Permissions not granted (camera, storage)

**Solution:**
```bash
# Check permissions in AndroidManifest.xml
cat android/app/src/main/AndroidManifestTest.xml

# Reinstall clean build
npm run android -- --reset-cache
```

---

### Fast Refresh Not Working

**Symptoms:** Code changes don't appear in app

**Solution:**

1. **Verify Metro is running** and shows bundling output
2. **Check Fast Refresh is enabled:**
   - Dev Menu → Settings → Ensure "Fast Refresh" toggled ON
3. **Force reload:**
   - Press `R` twice in Metro terminal
   - Or Dev Menu → Reload
4. **Clear Metro cache:**
   ```bash
   npm run start -- --reset-cache
   ```

---

### Wireless Debugging Connection Issues

**Problem:** App can't reach Metro server on computer

**Solution:**

1. **Ensure same network:**
   - Both device and computer on same WiFi
   - No VPN blocking local network

2. **Use computer's IP address:**
   - Dev Menu → Settings → Debug server host
   - Enter: `192.168.x.x:8081` (your computer's IP)

3. **Check firewall:**
   - Allow incoming connections on port 8081

---

### Device Pairing Connection Issues

**Error:** "Failed to connect to Desktop" when scanning QR code

**This is for Zelara Desktop ↔ Mobile device linking (port 8765), NOT Metro bundler (port 8081).**

**Checklist:**

1. **Desktop WebSocket server running:**
   ```bash
   # Check if port 8765 is listening
   netstat -an | findstr :8765
   # Expected: TCP    [IP]:8765    LISTENING
   ```
   - If not listening: Open Zelara Desktop app → Click "Generate QR Code"

2. **Windows Firewall rule created:**
   ```powershell
   # Run as Administrator
   cd C:\Users\[YourUsername]\Documents\core\apps\desktop\scripts
   .\setup-firewall.ps1
   ```
   - This allows inbound connections on port 8765

3. **Both devices on same WiFi network:**
   ```bash
   # On Desktop (Windows)
   ipconfig
   # Note "Wireless LAN adapter Wi-Fi" → IPv4 Address (e.g., 172.25.99.241)
   ```
   - Mobile WiFi settings: Check connected network name
   - **Must match** Desktop's network (same SSID)
   - Mobile IP should be in same subnet (e.g., 172.25.x.x)

4. **Guest network / AP isolation:**
   - Some routers isolate devices on guest networks
   - Try connecting to main WiFi network instead
   - Or use Mobile Hotspot workaround (see below)

**Quick Test - Mobile Hotspot:**

If unable to get both on same network:
1. Mobile: Enable Personal Hotspot
2. Desktop: Connect to Mobile's hotspot WiFi
3. Desktop: Open Zelara → Generate new QR code (new IP from hotspot)
4. Mobile: Scan QR code → Should work!

**Detailed Troubleshooting:** See [Desktop DEVICE-PAIRING-TROUBLESHOOTING.md](../../desktop/DEVICE-PAIRING-TROUBLESHOOTING.md)

---

## Build Configurations

### Understanding [build.gradle](../android/app/build.gradle)

#### React Native Configuration Block (Lines 62-67)

```gradle
project.ext.react = [
    enableHermes: true,      // Use Hermes JS engine
    bundleInDebug: false,    // Don't bundle JS in debug APK
    bundleInRelease: true,   // Bundle JS in release APK
    devDisabledInRelease: true
]
```

**When to change `bundleInDebug`:**

- **Keep `false` (default):** Normal development with Hot Reload
- **Set `true`:** Testing APK without Metro server (not recommended for dev)

#### Build Variants

**Debug:**
- Fast build time
- Metro-dependent
- Development features enabled
- APK: `app-debug.apk`

**Release:**
- Optimized, minified
- Standalone (Metro not needed)
- ProGuard/R8 enabled
- Requires signing configuration
- APK: `app-release.apk`

### Manual Bundle Creation

If you need to bundle JS manually (for testing release builds):

```bash
cd apps/mobile
npm run bundle:android
```

This creates:
- `android/app/src/main/assets/index.android.bundle`
- `android/app/src/main/res/` (assets)

Then build release APK:
```bash
cd android
./gradlew assembleRelease
```

Output: `android/app/build/outputs/apk/release/app-release.apk`

---

## Best Practices

### Development Workflow Checklist

- [ ] Always start Metro before running app in Android Studio
- [ ] Keep Metro terminal visible to see bundling logs
- [ ] Use Fast Refresh instead of full rebuild for JS changes
- [ ] Clean build when switching between branches
- [ ] Use `adb reverse` for USB debugging
- [ ] Check Logcat for crash details

### Performance Tips

- **Use debug builds for development** - Faster iteration
- **Clear Metro cache** if seeing stale code: `npm run start -- --reset-cache`
- **Clean Gradle cache** if build fails: `cd android && ./gradlew clean`
- **Reduce emulator resources** if computer is slow (lower RAM/CPU allocation)

### Team Collaboration

When sharing setup issues:
1. Share Metro terminal output (bundling logs)
2. Share Logcat filtered for `ai.zelara.mobile`
3. Include `adb devices` output
4. Mention which workflow you're using (VS Code CLI or Android Studio)

---

## Additional Resources

- [React Native Debugging Docs](https://reactnative.dev/docs/debugging)
- [Metro Configuration](https://metrobundler.dev/docs/configuration/)
- [Android Studio User Guide](https://developer.android.com/studio/intro)
- [Zelara Permissions Setup](../PERMISSIONS_SETUP.md) - Camera, storage permissions

---

**Last Updated:** 2025-02-24
**React Native Version:** 0.76.6
**Target Android SDK:** 35 (compileSdk), 34 (targetSdk)