From be5178e04fe1e5b18ae9b2e892d0ea62bf99803d Mon Sep 17 00:00:00 2001
From: datadunia <datadunia@ymail.com>
Date: Fri, 3 Jul 2026 17:11:45 +0700
Subject: [PATCH] docs: add android-build.md with build/deploy commands

---
 .tests/android-build.md | 96 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 .tests/android-build.md

diff --git a/.tests/android-build.md b/.tests/android-build.md
new file mode 100644
index 0000000..8b3e7dc
--- /dev/null
+++ b/.tests/android-build.md
@@ -0,0 +1,96 @@
+# 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
+```