admin/DroidScope
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
14935db63efb12037bf9003b419714ab0869953a
DroidScope/PLAN.md
T
achmad 6a53f87e03 chore: initial project scaffold 
Sets up monorepo with Wails desktop shell, Go backend, React/TS frontend, and Kotlin Android SDK skeleton.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-06 13:13:21 +07:00

9.3 KiB
Raw Blame History

Android Observability Platform — AI-Oriented Requirements Document

Project Name

Temporary codename:

  • DroidScope

Project Summary

A standalone cross-platform desktop application for Android application observability and debugging.

The platform allows developers to:

  • Connect Android devices/emulators through ADB
  • Monitor application behavior in real time
  • Inspect network traffic
  • Inspect storage and databases
  • Monitor performance metrics
  • Analyze memory behavior
  • Observe Jetpack Compose recompositions
  • Stream logs
  • Modify runtime configurations

The application must provide a modern browser-like developer tooling experience similar to Chrome DevTools.

Primary Goals

Functional Goals

  • Real-time Android observability
  • Cross-platform desktop support
  • Multi-device support
  • Low-overhead instrumentation
  • Developer-focused workflows
  • Unified debugging interface
  • Plugin-capable architecture

Technology Stack

Desktop Framework

Wails

Responsibilities:

  • Native desktop shell
  • Window management
  • Packaging
  • Native integrations

Backend

Go

Responsibilities:

  • ADB communication
  • Device management
  • Event streaming
  • Monitoring orchestration
  • Local APIs
  • Session management
  • Data aggregation

Frontend

React + TypeScript

Responsibilities:

  • Dashboard UI
  • Inspector panels
  • Charts
  • Tables
  • Interaction layer

High-Level Architecture

Android App
    ↓
Instrumentation SDK
    ↓
ADB Tunnel / WebSocket
    ↓
Go Backend
    ↓
React Frontend
    ↓
Wails Desktop Shell

Repository Structure

root/
├── desktop/
├── backend-go/
├── frontend-react/
├── android-sdk/
├── shared-protocol/
├── docs/
└── scripts/

Core Components

1. Android Instrumentation SDK

Description

Embedded Android SDK responsible for collecting runtime diagnostics and streaming events to the desktop application.

SDK Requirements

General

  • Kotlin-first
  • Android SDK 24+
  • Modular architecture
  • Debug-build focused
  • Runtime enable/disable
  • Minimal overhead
  • Safe fallback behavior
  • R8/ProGuard compatibility

2. Go Backend

Description

Central orchestration engine responsible for:

  • ADB communication
  • Session handling
  • Event aggregation
  • WebSocket streaming
  • Data persistence

Backend Requirements

Device Management

Capabilities

  • Detect connected devices
  • Support multiple devices
  • Wireless ADB support
  • Device reconnect handling
  • Emulator support

Commands

  • List devices
  • Connect device
  • Disconnect device
  • Restart session

Event Streaming

Requirements

  • WebSocket-based streaming
  • Low latency
  • Event batching
  • Backpressure handling
  • Event replay support

Session Management

Requirements

  • Multiple concurrent sessions
  • Persistent sessions
  • Session restore
  • Session metadata

Security

Requirements

  • Local-only communication by default
  • Session isolation
  • Optional authentication
  • Safe runtime permissions

3. React Frontend

Description

Primary user interface for observability and inspection.

Frontend Requirements

General

  • Modern desktop UI
  • Responsive layout
  • Fast rendering
  • Keyboard shortcuts
  • Search everywhere
  • Virtualized large lists
  • Multi-tab support

Feature Requirements

Device Manager

Requirements

Device List

Display:

  • Device name
  • Device ID
  • Android version
  • Connection type
  • Connection status
  • Battery level
  • CPU architecture

Device Actions

Support:

  • Connect
  • Disconnect
  • Refresh
  • Restart session
  • Open shell

Logcat Monitoring

Requirements

Features

  • Real-time log streaming
  • Structured log rendering
  • Tag filtering
  • Priority filtering
  • Search
  • Export logs

Supported Priorities

  • Verbose
  • Debug
  • Info
  • Warn
  • Error
  • Assert

Network Inspector

Requirements

Capture

  • HTTP
  • HTTPS
  • WebSocket traffic

Request Inspection

Display:

  • URL
  • Method
  • Headers
  • Query parameters
  • Timing
  • Body

Response Inspection

Display:

  • Status code
  • Headers
  • Body
  • Response size
  • Timing

Features

  • JSON formatting
  • CURL export
  • Request replay
  • Filtering
  • Search
  • Timeline view

Shared Preferences Inspector

Requirements

Features

  • View entries
  • Edit entries
  • Delete entries
  • Live updates

Data Types

  • String
  • Int
  • Long
  • Float
  • Boolean
  • String Set

Database Browser

Requirements

Features

  • SQLite browsing
  • Room database support
  • Table inspection
  • Query execution
  • Schema visualization

Query Support

  • Read-only queries initially
  • Query history
  • Export support

File Browser

Requirements

Features

  • Browse sandbox files
  • Download files
  • Upload files
  • Delete files
  • Preview files

Preview Support

  • Text
  • JSON
  • Images

Runtime Configuration

Requirements

Features

  • Base URL override
  • Feature flag toggles
  • Runtime config editing
  • Deep link launcher

FPS Monitoring

Requirements

Features

  • Real-time FPS tracking
  • Jank detection
  • Slow frame tracking
  • Frame drop statistics

Memory Monitoring

Requirements

Features

  • Heap usage tracking
  • Allocation monitoring
  • GC event tracking
  • Native memory visibility

Memory Leak Detection

Requirements

Features

  • Activity leak detection
  • Fragment leak detection
  • Retained object tracking
  • Leak history

Thread Monitoring

Requirements

Features

  • Active thread list
  • Main-thread blocking detection
  • Thread state visibility
  • ANR risk visibility

StrictMode Monitoring

Requirements

Features

  • Disk read violations
  • Disk write violations
  • Network-on-main-thread detection
  • Resource leak detection

Compose Recomposition Monitoring

Requirements

Features

  • Recomposition counts
  • Hotspot detection
  • Frequent recomposition visibility
  • State update tracing

WebView Monitoring

Requirements

Features

  • URL tracking
  • Console log inspection
  • Resource loading visibility
  • WebView lifecycle visibility

Device Information

Requirements

Display

  • Device manufacturer
  • Device model
  • Android version
  • ABI
  • RAM
  • Storage
  • Battery
  • Thermal status

Loaded Libraries Inspection

Requirements

Features

  • Loaded native libraries
  • Dynamic library visibility
  • ABI metadata

Secure Storage Inspection

Requirements

Features

  • Keystore visibility
  • Key alias visibility
  • Encryption metadata visibility

Dashboard Layout

Main Sections

Sidebar

Contains:

  • Devices
  • Overview
  • Logs
  • Network
  • Storage
  • Performance
  • Compose
  • WebView
  • Runtime
  • Settings

Main Panel

Displays:

  • Active inspector
  • Charts
  • Tables
  • Request details
  • Device information

Non-Functional Requirements

Performance

Requirements

  • Low memory overhead
  • Low CPU overhead
  • Virtualized rendering
  • Efficient event streaming

Reliability

Requirements

  • Graceful reconnect handling
  • Crash recovery
  • Offline handling
  • Buffered events

Security

Requirements

  • Debug-only instrumentation by default
  • Sensitive data masking
  • Localhost-only communication by default

Packaging Requirements

Supported Platforms

  • macOS
  • Windows
  • Linux

Packaging Goals

  • Single installer
  • Bundled ADB
  • No Android Studio requirement
  • Minimal setup

AI Agent Guidance

Backend Guidelines

Go Backend Principles

  • Use goroutines for stream handling
  • Prefer event-driven architecture
  • Avoid tightly coupled modules
  • Use interfaces for feature modules
  • Keep protocol versioned

Frontend Guidelines

React Principles

  • Use feature-based architecture
  • Avoid excessive global state
  • Use virtualization for large datasets
  • Prefer streaming updates over polling

Android SDK Guidelines

SDK Principles

  • Avoid blocking main thread
  • Ensure instrumentation can be disabled
  • Prefer lightweight hooks
  • Avoid unstable internal Android APIs where possible

Event Protocol

Event Structure

All events should contain:

{
  "type": "",
  "timestamp": 0,
  "deviceId": "",
  "sessionId": "",
  "payload": {}
}

MVP Scope

Phase 1

Included Features

  • Device management
  • Logcat streaming
  • Network inspection
  • SharedPreferences inspection
  • SQLite browser
  • File browser
  • Runtime URL override

Phase 2

Included Features

  • FPS monitoring
  • Memory monitoring
  • StrictMode monitoring
  • Thread monitoring

Phase 3

Included Features

  • Leak visualization
  • Compose recomposition tooling
  • Advanced tracing
  • Flamegraphs

Future Scope

Potential Future Features

  • Plugin system
  • Scripting support
  • Automation support
  • iOS support
  • Flutter support
  • React Native support
  • Remote device support
  • Team collaboration

Out of Scope

Explicit Non-Goals

  • Production analytics platform
  • MDM solution
  • CI/CD tooling
  • Cloud-hosted observability platform
  • Crash reporting replacement

Success Criteria

MVP Success Conditions

  • Device detection works reliably
  • Logs stream in real time
  • Network inspector functions correctly
  • Storage inspection is stable
  • Dashboard remains responsive under heavy streams

Product Positioning

Primary positioning statement:

Chrome DevTools for Android Native Apps

Reference in New Issue View Git Blame Copy Permalink