# 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 [docs/DEVELOPMENT.md](docs/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