docs: replace PLAN.md with README, add CLAUDE.md, DEVELOPMENT.md, TODO

PLAN.md (AI requirements doc) converted to README.md (human-facing project overview with feature status table). CLAUDE.md added for Claude Code with commands, architecture, and key conventions. DEVELOPMENT.md covers first-time setup, per-component build commands, hot-reload guidance, and ADB bundling notes. TODO.md tracks implementation status across all phases.
2026-05-06 14:52:01 +07:00
parent 62d56ef3d6
commit d42786d0c7
5 changed files with 598 additions and 760 deletions
@@ -0,0 +1,114 @@
+# DroidScope
+
+> Chrome DevTools for Android Native Apps
+
+A standalone cross-platform desktop application for Android application observability and debugging. Connect any Android device or emulator and get real-time visibility into logs, network traffic, storage, performance, and more — without needing Android Studio.
+
+---
+
+## Features
+
+### Phase 1 — MVP
+| Feature | Status |
+|---|---|
+| Device management (USB + wireless ADB) | ✅ Done |
+| Real-time device stats (RAM, battery, thermal, storage) | ✅ Done |
+| Logcat streaming | 🔧 In progress |
+| Network inspector (OkHttp interceptor) | 📋 Planned |
+| SharedPreferences inspector | 📋 Planned |
+| SQLite browser | 📋 Planned |
+| File browser | 📋 Planned |
+| Runtime URL override & feature flags | 📋 Planned |
+
+### Phase 2
+FPS monitoring, memory monitoring, StrictMode violations, thread monitoring / ANR risk.
+
+### Phase 3
+Memory leak detection, Jetpack Compose recomposition tooling, advanced tracing, flamegraphs.
+
+---
+
+## Technology Stack
+
+| Layer | Technology |
+|---|---|
+| Desktop shell | [Wails v2](https://wails.io) |
+| Backend | Go 1.23+ |
+| Frontend | React + TypeScript + Vite |
+| Android SDK | Kotlin, minSdk 24 |
+| UI components | shadcn/ui + Tailwind CSS |
+| State | Zustand |
+| Data fetching | TanStack Query |
+
+---
+
+## Architecture
+
+```
+Android App
+    ↓
+DroidScope Instrumentation SDK  (android-sdk/)
+    ↓
+ADB tunnel / WebSocket
+    ↓
+Go backend  (backend-go/)
+    ↓
+React frontend  (frontend-react/)
+    ↓
+Wails desktop shell  (desktop/)
+```
+
+The desktop app bundles the Go backend and React UI into a single native binary. No server required — everything runs locally.
+
+---
+
+## Repository Structure
+
+```
+DroidScope/
+├── desktop/          — Wails app (Go entry point, app.go bindings)
+├── backend-go/       — Go packages: ADB, device, logcat, network, storage…
+├── frontend-react/   — Vite + React + TypeScript UI
+├── android-sdk/      — Kotlin instrumentation SDK
+├── scripts/          — dev.sh, build.sh, download-adb.sh
+├── go.work           — Go workspace
+├── DEVELOPMENT.md    — Full development guide
+└── TODO.md           — Implementation status
+```
+
+---
+
+## Getting Started
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for full setup instructions.
+
+**Quick start:**
+
+```bash
+# 1. Install frontend dependencies
+cd frontend-react && npm install
+
+# 2. Start full dev environment
+bash scripts/dev.sh
+```
+
+Prerequisites: Go 1.23+, Node.js 20+, Wails CLI v2, system ADB accessible via `$ANDROID_HOME` or `$PATH`.
+
+---
+
+## Design Principles
+
+- **Local-only by default** — all communication stays on localhost; no cloud dependency
+- **Debug-build focused** — instrumentation SDK is designed for development builds, not production
+- **Low overhead** — minimal CPU/memory impact on both desktop and device
+- **Multi-device** — supports monitoring multiple connected devices simultaneously
+- **Retained data** — switching between devices preserves previously captured data in memory
+
+---
+
+## Out of Scope
+
+- Production analytics / crash reporting
+- MDM / device management
+- Cloud-hosted observability
+- CI/CD tooling