# Android Agent Build & Deploy

## Prerequisites
- Android SDK installed (compileSdk 34, minSdk 26)
- Device connected via USB with USB debugging enabled
- `adb devices` shows device

## Device
```
9b2adc22        device
```

## Build Commands

### Build Debug APK
```powershell
cd D:\www-project\NexusGuard\apps\android-agent
.\gradlew assembleDebug
```

Output: `app/build/outputs/apk/debug/app-debug.apk`

### Install on Device
```powershell
adb install -r app\build\outputs\apk\debug\app-debug.apk
```

### Launch App
```powershell
adb shell am start -n com.datadunia.nexusguard/.MainActivity
```

### View Logs
```powershell
adb logcat -s AgentService GrpcClient Heartbeat TunnelManager Provisioning LogBuffer
```

### Check Device Connection
```powershell
adb devices
```

## One-Shot Build + Install + Launch
```powershell
cd D:\www-project\NexusGuard\apps\android-agent
.\gradlew assembleDebug && adb install -r app\build\outputs\apk\debug\app-debug.apk && adb shell am start -n com.datadunia.nexusguard/.MainActivity
```

## Architecture (matches device-agent)
- **gRPC signaling**: GrpcClient.kt — bidirectional streaming with fallback (HTTPS domain → WG IP → plaintext)
- **HTTP heartbeat**: Heartbeat.kt — POST /api/v1/heartbeat every 30s (fallback when gRPC down)
- **Background service**: AgentService.kt — foreground service with notification (START_STICKY)
- **Tunnel**: TunnelManager.kt — WireGuard via VPNService + GoBackend
- **HWID**: SHA-256(ANDROID_ID + manufacturer + model + device), persisted in EncryptedSharedPreferences
- **Provisioning**: Provisioning.kt — HTTP POST /api/v1/provisioning
- **Auto-start**: BootReceiver.kt — starts agent on device boot

## Commands (Agent)
- gRPC: HelloMessage → ConfigUpdate (full tunnel config + port forwards)
- gRPC: HeartbeatRequest every 30s → HeartbeatResponse (config_hash + forwards_changed)
- gRPC: Suspend/Resume/Reconnect/Disconnect from server
- HTTP heartbeat: fallback when gRPC disconnected

## .gitignore (Android artifacts)
```
*.aar
*.apk
*.aab
android-agent/app/build/
android-agent/build/
android-agent/.gradle/
android-agent/local.properties
```

## Commit Workflow
```powershell
# 1. Build
cd D:\www-project\NexusGuard\apps\android-agent
.\gradlew assembleDebug

# 2. Install + test
adb install -r app\build\outputs\apk\debug\app-debug.apk
adb shell am start -n com.datadunia.nexusguard/.MainActivity

# 3. Commit submodule
cd D:\www-project\NexusGuard\apps\android-agent
git add -A
git commit -m "feat: message"
git push origin main

# 4. Commit parent repo
cd D:\www-project\NexusGuard
git add apps/android-agent
git commit -m "chore: update android-agent submodule"
git push origin main
```