chore: move DEVELOPMENT.md and TODO.md to docs/
This commit is contained in:
achmad
@@ -0,0 +1,238 @@
|
||||
# DroidScope — Development Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Tool | Version | Install |
|
||||
|---|---|---|
|
||||
| Go | 1.23+ | https://go.dev/dl |
|
||||
| Node.js | 20+ | https://nodejs.org |
|
||||
| Wails CLI | v2 | `go install github.com/wailsapp/wails/v2/cmd/wails@latest` |
|
||||
| Git | any | — |
|
||||
|
||||
> **macOS only:** Wails requires Xcode Command Line Tools — `xcode-select --install`
|
||||
>
|
||||
> **Linux only:** Wails requires `libgtk-3-dev libwebkit2gtk-4.0-dev` (Debian/Ubuntu) or equivalent.
|
||||
>
|
||||
> **Windows only:** Wails requires WebView2 (ships with Windows 11, otherwise install from Microsoft).
|
||||
|
||||
---
|
||||
|
||||
## First-time Setup
|
||||
|
||||
```bash
|
||||
# 1. Install frontend dependencies
|
||||
cd frontend-react
|
||||
npm install
|
||||
|
||||
# 2. (Optional) Download bundled ADB binaries for distribution builds
|
||||
# Skip this for local dev — the app falls back to your system ADB
|
||||
bash scripts/download-adb.sh
|
||||
|
||||
# 3. Make sure your system ADB is accessible for local dev
|
||||
# Either via ANDROID_HOME or PATH:
|
||||
export ANDROID_HOME=~/Library/Android/sdk # macOS example
|
||||
# or: ensure `adb` is on your PATH
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running in Development
|
||||
|
||||
```bash
|
||||
bash scripts/dev.sh
|
||||
```
|
||||
|
||||
**What `dev.sh` does, in order:**
|
||||
|
||||
| Step | Command | What it checks |
|
||||
|---|---|---|
|
||||
| 1 | `go build ./...` in `backend-go/` | Backend packages compile without errors |
|
||||
| 2 | `go build ./...` in `desktop/` | Desktop Go code (app.go, main.go, embeds) compiles |
|
||||
| 3 | `wails generate module` in `desktop/` | Regenerates `frontend-react/src/wailsjs/` from current `app.go` bindings |
|
||||
| 4 | `npm install` + `tsc -b --noEmit` in `frontend-react/` | Installs any new deps, type-checks TypeScript |
|
||||
| — | `wails dev` in `desktop/` | Starts the desktop app with hot reload |
|
||||
|
||||
If any step fails the script exits immediately (due to `set -e`) — fix the error and re-run.
|
||||
|
||||
**What happens once running:**
|
||||
- Wails compiles the Go backend and opens a native desktop window
|
||||
- Wails starts the Vite dev server (`npm run dev` in `frontend-react/`)
|
||||
- React/TS changes hot-reload instantly without restarting
|
||||
- Go changes (in `app.go`, `backend-go/`) require re-running `dev.sh`
|
||||
|
||||
> **When to re-run `dev.sh` vs just saving a file:**
|
||||
> - Edited only `.tsx` / `.ts` / `.css` → Vite hot-reloads automatically, no restart needed
|
||||
> - Edited `app.go` (added/changed a bound method) → re-run `dev.sh` to rebuild Go + regenerate bindings
|
||||
> - Edited anything under `backend-go/` → re-run `dev.sh` to rebuild
|
||||
|
||||
**Frontend only** (browser preview, no Wails bindings):
|
||||
|
||||
```bash
|
||||
cd frontend-react
|
||||
npm run dev
|
||||
# → http://localhost:5173
|
||||
```
|
||||
|
||||
> Wails bindings (`ListDevices`, `GetDeviceInfo`, etc.) are no-ops in plain browser mode — they only work inside the Wails desktop window.
|
||||
|
||||
---
|
||||
|
||||
## Building for Production
|
||||
|
||||
### Full desktop app (recommended)
|
||||
|
||||
```bash
|
||||
bash scripts/build.sh
|
||||
```
|
||||
|
||||
Or manually:
|
||||
|
||||
```bash
|
||||
# Step 1 — build frontend (outputs to desktop/frontend/dist/)
|
||||
cd frontend-react
|
||||
npm run build
|
||||
|
||||
# Step 2 — build desktop binary (embeds frontend dist + ADB binaries)
|
||||
cd desktop
|
||||
export PATH="$PATH:$(go env GOPATH)/bin"
|
||||
wails build
|
||||
```
|
||||
|
||||
Output: `desktop/build/bin/DroidScope` (macOS/Linux) or `desktop/build/bin/DroidScope.exe` (Windows)
|
||||
|
||||
---
|
||||
|
||||
### Backend only
|
||||
|
||||
```bash
|
||||
cd backend-go
|
||||
go build ./...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Frontend only (static bundle)
|
||||
|
||||
```bash
|
||||
cd frontend-react
|
||||
npm run build
|
||||
# Output: desktop/frontend/dist/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Android SDK
|
||||
|
||||
```bash
|
||||
cd android-sdk
|
||||
./gradlew :sdk:assembleDebug # debug AAR
|
||||
./gradlew :sdk:assembleRelease # release AAR
|
||||
# Output: android-sdk/sdk/build/outputs/aar/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type Checking (no build)
|
||||
|
||||
```bash
|
||||
# TypeScript
|
||||
cd frontend-react
|
||||
npx tsc -b --noEmit
|
||||
|
||||
# Go
|
||||
cd backend-go && go build ./...
|
||||
cd desktop && go build ./...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Regenerating Wails JS Bindings
|
||||
|
||||
Run this after adding or changing any exported method on `App` in `desktop/app.go`:
|
||||
|
||||
```bash
|
||||
cd desktop
|
||||
export PATH="$PATH:$(go env GOPATH)/bin"
|
||||
wails generate module
|
||||
# Output: frontend-react/src/wailsjs/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
DroidScope/
|
||||
├── desktop/ ← Wails app (Go entry point)
|
||||
│ ├── app.go ← Wails-bound methods (called from frontend)
|
||||
│ ├── main.go ← App bootstrap
|
||||
│ ├── wails.json ← Wails config (frontend dir, dev server)
|
||||
│ └── internal/adbembed/ ← ADB binary embedding + runtime extraction
|
||||
│
|
||||
├── backend-go/ ← Go backend packages
|
||||
│ ├── adb/ ← ADB command wrapper
|
||||
│ ├── device/ ← Device manager + DeviceInfo fetcher
|
||||
│ ├── logcat/ ← (stub) Logcat streaming
|
||||
│ ├── network/ ← (stub) Network inspector
|
||||
│ ├── storage/ ← (stub) SharedPrefs, SQLite, files
|
||||
│ ├── runtime/ ← (stub) Runtime config override
|
||||
│ ├── session/ ← (stub) Session management
|
||||
│ └── protocol/ ← Shared event types (Go structs)
|
||||
│
|
||||
├── frontend-react/ ← Vite + React + TypeScript
|
||||
│ ├── src/
|
||||
│ │ ├── wailsjs/ ← Auto-generated Wails bindings (do not edit)
|
||||
│ │ ├── features/ ← Feature modules (devices, logcat, network…)
|
||||
│ │ ├── components/ ← Shared UI components (layout, shadcn/ui)
|
||||
│ │ ├── hooks/ ← Shared hooks (useActiveDevice)
|
||||
│ │ ├── store/ ← Zustand global state
|
||||
│ │ └── types/ ← Shared TypeScript types (protocol)
|
||||
│ └── vite.config.ts ← Build outputs to ../desktop/frontend/dist/
|
||||
│
|
||||
├── android-sdk/ ← Kotlin Android SDK (Gradle)
|
||||
│ └── sdk/src/main/kotlin/dev/achmad/droidscope/
|
||||
│
|
||||
├── scripts/
|
||||
│ ├── dev.sh ← Start full dev environment
|
||||
│ ├── build.sh ← Production build
|
||||
│ └── download-adb.sh ← Download ADB binaries for bundling
|
||||
│
|
||||
├── go.work ← Go workspace (links desktop + backend-go)
|
||||
├── README.md ← Project overview and feature roadmap
|
||||
└── docs/
|
||||
├── DEVELOPMENT.md ← This file
|
||||
└── TODO.md ← Implementation status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Conventions
|
||||
|
||||
### Adding a new Go method callable from the frontend
|
||||
|
||||
1. Add the method to `desktop/app.go` (must be exported, receiver `*App`)
|
||||
2. Run `wails generate module` from `desktop/`
|
||||
3. Import from `@/wailsjs/go/main/App` in React
|
||||
|
||||
### Adding a new backend-go package
|
||||
|
||||
1. Create the package under `backend-go/`
|
||||
2. The `go.work` workspace + `replace` directive in `desktop/go.mod` handle local resolution — no publishing needed
|
||||
|
||||
### Active device scoping (all features)
|
||||
|
||||
- Import `useActiveDevice` from `@/hooks/use-active-device`
|
||||
- Check `isMonitoring` before starting streams or polls
|
||||
- Store per-device data in `deviceCache` via `patchDeviceCache(deviceId, data)` — never cleared on device switch
|
||||
- Show `<NoDeviceSelected />` when `!isMonitoring`
|
||||
|
||||
---
|
||||
|
||||
## ADB Binary Bundling
|
||||
|
||||
For **local development** the app resolves ADB in this order:
|
||||
1. Embedded binary in `desktop/internal/adbembed/bin/` (empty until `download-adb.sh` is run)
|
||||
2. `$ANDROID_HOME/platform-tools/adb`
|
||||
3. `adb` on `$PATH`
|
||||
|
||||
For **distribution builds** run `scripts/download-adb.sh` once before `wails build` to embed ADB for all platforms.
|
||||
+148
@@ -0,0 +1,148 @@
|
||||
# DroidScope — TODO
|
||||
|
||||
## Legend
|
||||
- `[x]` Done
|
||||
- `[ ]` Not started
|
||||
- `[~]` In progress
|
||||
|
||||
---
|
||||
|
||||
## Infrastructure
|
||||
|
||||
- [x] Project scaffold (Wails + Go + React/TS + Kotlin SDK)
|
||||
- [x] Monorepo structure (`desktop/`, `backend-go/`, `frontend-react/`, `android-sdk/`)
|
||||
- [x] Go workspace (`go.work`)
|
||||
- [x] Shared event protocol (Go structs + TypeScript types)
|
||||
- [x] Dev script (`scripts/dev.sh`) — builds backend, desktop, regenerates bindings, type-checks, then starts
|
||||
- [x] Build script (`scripts/build.sh`)
|
||||
- [x] Development guide (`DEVELOPMENT.md`)
|
||||
- [x] Bundle ADB binary infrastructure (`desktop/internal/adbembed/`)
|
||||
- [x] ADB discovery at runtime (embedded → ANDROID_HOME → PATH fallback)
|
||||
- [x] Download ADB binaries for distribution (`scripts/download-adb.sh` ready, run once)
|
||||
- [ ] CI/CD pipeline
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — MVP
|
||||
|
||||
### Device Management
|
||||
- [x] ADB wrapper (`backend-go/adb/`)
|
||||
- [x] List connected devices (1s poll)
|
||||
- [x] Device connect / disconnect
|
||||
- [x] Wireless ADB support
|
||||
- [x] Device reconnect handling
|
||||
- [x] Emulator support
|
||||
- [x] Static device info (model, Android version, ABI, manufacturer, screen, build fingerprint)
|
||||
- [x] Live device stats — 1s poll (available RAM, battery level/status, thermal status, available storage, IP)
|
||||
- [x] Frontend: device list panel with real-time updates
|
||||
- [x] Frontend: wireless connect dialog
|
||||
- [x] Frontend: disconnect action
|
||||
- [x] Frontend: device info panel — static fields fetched once, live fields pulsing every second
|
||||
- [x] Frontend: RAM usage progress bar (live)
|
||||
- [x] Frontend: split layout — device list + info detail side by side
|
||||
- [x] Frontend: selected device (info view) vs profiled device (monitoring target) — separate concepts
|
||||
- [x] Frontend: Profile / Stop profiling toggle per device card
|
||||
- [x] Frontend: active profiling indicator bar in device list
|
||||
- [x] Frontend: auto-clear selected + profiled device when device disconnects or goes offline
|
||||
|
||||
### Logcat
|
||||
- [~] Backend stub (`backend-go/logcat/stream.go`)
|
||||
- [ ] Real-time logcat streaming via ADB
|
||||
- [ ] Structured log parsing (priority, tag, PID, message)
|
||||
- [ ] Wails event push to frontend
|
||||
- [ ] Frontend: log table with virtualized rendering
|
||||
- [ ] Frontend: filter by tag
|
||||
- [ ] Frontend: filter by priority (V/D/I/W/E/A)
|
||||
- [ ] Frontend: search
|
||||
- [ ] Frontend: export logs
|
||||
|
||||
### Network Inspector
|
||||
- [ ] Android SDK: OkHttp interceptor
|
||||
- [ ] Backend: receive + store network events
|
||||
- [ ] Frontend: request list
|
||||
- [ ] Frontend: request detail (headers, body, timing)
|
||||
- [ ] Frontend: response detail (status, headers, body, size)
|
||||
- [ ] Frontend: JSON formatting
|
||||
- [ ] Frontend: cURL export
|
||||
- [ ] Frontend: filter / search
|
||||
|
||||
### Shared Preferences Inspector
|
||||
- [ ] Backend: pull + parse SharedPreferences XML via ADB
|
||||
- [ ] Backend: write-back support
|
||||
- [ ] Frontend: key/value table
|
||||
- [ ] Frontend: inline editing (String, Int, Long, Float, Boolean, StringSet)
|
||||
- [ ] Frontend: live update polling
|
||||
|
||||
### SQLite Browser
|
||||
- [ ] Backend: pull database file via ADB
|
||||
- [ ] Backend: query execution
|
||||
- [ ] Frontend: table list
|
||||
- [ ] Frontend: table data viewer (paginated)
|
||||
- [ ] Frontend: SQL query editor
|
||||
- [ ] Frontend: query history
|
||||
- [ ] Frontend: export
|
||||
|
||||
### File Browser
|
||||
- [ ] Backend: `adb shell ls` traversal
|
||||
- [ ] Backend: file download (`adb pull`)
|
||||
- [ ] Backend: file upload (`adb push`)
|
||||
- [ ] Backend: file delete
|
||||
- [ ] Frontend: file tree / list
|
||||
- [ ] Frontend: text / JSON / image preview
|
||||
|
||||
### Runtime Configuration
|
||||
- [ ] Android SDK: base URL override hook
|
||||
- [ ] Android SDK: feature flag toggle
|
||||
- [ ] Backend: send config command to device
|
||||
- [ ] Frontend: URL override input
|
||||
- [ ] Frontend: feature flag toggles
|
||||
- [ ] Frontend: deep link launcher
|
||||
|
||||
---
|
||||
|
||||
## Phase 2
|
||||
|
||||
- [ ] FPS monitoring (backend + frontend chart)
|
||||
- [ ] Memory monitoring (heap, GC events)
|
||||
- [ ] StrictMode violation monitoring
|
||||
- [ ] Thread monitoring + ANR risk
|
||||
|
||||
---
|
||||
|
||||
## Phase 3
|
||||
|
||||
- [ ] Memory leak detection (Activity/Fragment)
|
||||
- [ ] Compose recomposition tooling
|
||||
- [ ] Advanced tracing
|
||||
- [ ] Flamegraphs
|
||||
|
||||
---
|
||||
|
||||
## Android SDK
|
||||
|
||||
- [x] Project skeleton (`android-sdk/`)
|
||||
- [x] `DroidScope.init()` / `shutdown()` entry point
|
||||
- [ ] WebSocket transport to desktop
|
||||
- [ ] Network interceptor (OkHttp)
|
||||
- [ ] SharedPreferences observer
|
||||
- [ ] Logcat forwarder (SDK-side filtering)
|
||||
- [ ] FPS collector (Choreographer)
|
||||
- [ ] Memory collector (Debug.MemoryInfo)
|
||||
- [ ] StrictMode collector
|
||||
- [ ] Compose recomposition collector
|
||||
|
||||
---
|
||||
|
||||
## Frontend Shell
|
||||
|
||||
- [x] Sidebar navigation
|
||||
- [x] Dark theme
|
||||
- [x] Selected device vs profiled device — two independent concepts in store
|
||||
- [x] `useActiveDevice` hook — reads `profiledDeviceId`; `isMonitoring = false` pauses all feature panels
|
||||
- [x] `NoDeviceSelected` shared component — guides user to Profile a device
|
||||
- [x] Per-device data cache (`deviceCache`) — retained on device switch, never cleared automatically
|
||||
- [ ] Persistent profiled device indicator in sidebar or top bar
|
||||
- [ ] Multi-tab panel support
|
||||
- [ ] Keyboard shortcuts
|
||||
- [ ] Global search
|
||||
- [ ] Settings page
|
||||
Reference in New Issue
Block a user