admin/DroidScope
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6a53f87e032857d23fe1033c18478e2f129b26f1
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

761 lines
9.3 KiB
Markdown
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
```text
Android App
↓
Instrumentation SDK
↓
ADB Tunnel / WebSocket
↓
Go Backend
↓
React Frontend
↓
Wails Desktop Shell
```
---
# Repository Structure
```text
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:
```json
{
"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