# nisargjhaveri/vscode-android-debug architecture

> Architecture diagram of the GitHub repository nisargjhaveri/vscode-android-debug, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nisargjhaveri/vscode-android-debug
- Repository: https://github.com/nisargjhaveri/vscode-android-debug

## Overview

##### Project Type and Purpose
- This is a VS Code extension (TypeScript) that provides:
– Android app debugging (Java, Native, or dual)
– CPU profiling via simpleperf or Firefox Profiler
– A custom profile viewer inside VS Code
- Key indicators:
– package.json with “activationEvents” and “contributes.debuggers”
– src/ folder with debugAdapter, debugConfigProvider, profile‑converter, profile‑viewer, etc.

##### File Structure
Top‑level artifacts:
- package.json / tsconfig.json / .vscodeignore – VS Code extension manifest & build config
- src/ – all TypeScript source code
- examples/SampleApplication – test Android app demonstrating usage
- .github/workflows – CI pipeline for building & packaging
- src/test – unit and integration tests
Within src/:
- extension.ts – extension entry point; registers providers & commands
- debugConfigProvider.ts – implements DebugConfigurationProvider for “android-debug”
- debugLifecycleManager.ts – orchestrates launch/attach lifecycles
- debugAdapter.ts & jdwp.ts – implement Debug Adapter Protocol (DAP) interactions, JDWP for Java, spawn LLDB for native
- androidPaths.ts, targetPicker.ts, targetCommand.ts – resolve SDK/NDK paths, pick devices, run ADB commands
- profile-converter/ – converters from simpleperf & Firefox Profiler formats to internal model
- profile-viewer/ – custom editor for displaying converted profiles
- logger.ts, utils.ts – shared utilities

##### Extract Additional Insights from README
- Extension contributes two debugger types: “android-debug” and “android-profile.”
- Depends on external extensions: CodeLLDB (native) and Java Debugger by Red Hat.
- Relies on Android SDK/NDK and ADB under the hood.

##### Main Components and Interactions
A. VS Code Host
- User invokes “Start Debugging” or “Open Profile”
- UI & Debug View communicate via the Debug Adapter Protocol (DAP)
B. Extension Host (Your code)
1. Activation & Registration
– extension.ts registers DebugConfigurationProvider, custom editor, commands
2. Debug Configuration Provider
– debugConfigProvider.ts supplies default launch/attach configs to VS Code
3. Debug Lifecycle Manager
– debugLifecycleManager.ts kicks off ADB device selection, installs APK (if needed), resumes process
4. Debug Adapter(s)
– For Java: use jdwp.ts to speak JDWP to device’s VM
– For Native: spawn CodeLLDB (dap) with symbolSearchPaths
– debugAdapter.ts ties both adapters into a “dual” session
5. Profile Conversion Pipeline
– profile-converter/converter.ts invokes either simpleperf or firefox‑profiler submodules
– Generates a common JSON/graph model
6. Profile Viewer
– profile-viewer/profileCustomEditor.ts implements a Custom Editor in VS Code
C. External Services
- Android Device / Emulator (via ADB)
- Android SDK & platform-tools
- Android NDK (for native symbols)
- CodeLLDB & Java Debugger extensions (hosted in VS Code)

##### Architectural Patterns & Principles
- Modular separation: configuration → lifecycle → protocol adapters → converters → UI
- Use of Debug Adapter Protocol (DAP) as a decoupling layer
- Plugin‑style extension registration via VS Code API
- Single Responsibility: each module handles one aspect (device pick, JDWP, LLDB, profile conversion, viewing)

– VS Code UI & Debug View (green)
– Extension Host
- Activation & Registration
- Debug Configuration Provider
- Debug Lifecycle Manager
- Java Debug Adapter (JDWP)
- Native Debug Adapter (LLDB)
- Profile Converter
- Profile Viewer
– External Entities (gray): Android Device/Emulator, Android SDK/NDK, CodeLLDB & Java Debugger extensions
– User → VS Code UI → Extension (activation)
– Extension → ADB (install/launch) → Device
– Device → JDWP adapter → Extension → VS Code (Java debugging)
– Extension → spawn LLDB → Device (native debugging)
– Device profiling data → Converter → Viewer → VS Code UI
– Purple labels: third‑party extensions

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "VS Code Host"
        user["User"]:::external
        vscodeUI["VS Code UI & Debug View"]:::vscodeCore
    end

    subgraph "Extension Host"
        activation["Activation & Registration"]:::extension
        config["DebugConfigurationProvider"]:::extension
        lifecycle["DebugLifecycleManager"]:::extension
        androidPaths["Android Path Resolution"]:::extension
        devicePicker["Device Picker Module"]:::extension
        deviceCmd["Device Command Executor"]:::extension
        unifiedDA["Unified Debug Adapter"]:::extension
        jdwp["Java Debug Adapter (JDWP)"]:::extension
        subgraph "Profile Conversion Pipeline"
            converter["Profile Converter"]:::extension
            subgraph "Firefox Profiler"
                firefoxProfile["profile.ts"]:::extension
                firefoxUtils["unique-string-array.ts"]:::extension
            end
            subgraph "simpleperf"
                spDef["simpleperf_report.d.ts"]:::extension
                spImpl["simpleperf_report.js"]:::extension
                spProto["simpleperf_report.proto"]:::extension
            end
        end
        profilerInt["Profiler Command Interface"]:::extension
        profileViewer["Profile Viewer"]:::extension
        subgraph "Shared Modules"
            logger["Logger"]:::extension
            utils["General Utils"]:::extension
            commonTypes["Common Type Definitions"]:::extension
            extDeps["Extension Dependencies Declaration"]:::extension
        end
    end

    subgraph "External Services"
        device["Android Device/Emulator"]:::external
        sdk["Android SDK & platform-tools"]:::external
        ndk["Android NDK"]:::external
        codelldbExt["CodeLLDB Extension"]:::external
        javaDbgExt["Java Debugger Extension"]:::external
    end

    user -->|"invoke"| vscodeUI
    vscodeUI -->|"activationEvent"| activation
    activation --> config
    activation --> profI[Profiler Command Interface]
    activation --> profileViewer
    config --> lifecycle
    lifecycle --> androidPaths
    lifecycle --> devicePicker
    devicePicker --> deviceCmd
    deviceCmd --> sdk
    deviceCmd --> device
    lifecycle --> unifiedDA
    unifiedDA --> jdwp
    unifiedDA --> codelldbExt
    unifiedDA --> javaDbgExt
    jdwp -->|"JDWP"| device
    codelldbExt -->|"LLDB"| device
    profilerInt --> converter
    firefoxProfile --> converter
    firefoxUtils --> converter
    spDef --> converter
    spImpl --> converter
    spProto --> converter
    converter --> profileViewer
    profileViewer -->|"Custom Editor"| vscodeUI
    sdk --> device
    ndk --> device

    click activation "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/extension.ts"
    click config "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/debugConfigProvider.ts"
    click lifecycle "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/debugLifecycleManager.ts"
    click androidPaths "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/androidPaths.ts"
    click devicePicker "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/targetPicker.ts"
    click deviceCmd "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/targetCommand.ts"
    click jdwp "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/jdwp.ts"
    click unifiedDA "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/debugAdapter.ts"
    click converter "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/profile-converter/converter.ts"
    click firefoxProfile "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/profile-converter/firefox-profiler/profile.ts"
    click firefoxUtils "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/profile-converter/firefox-profiler/unique-string-array.ts"
    click spDef "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/profile-converter/simpleperf/simpleperf_report.d.ts"
    click spImpl "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/profile-converter/simpleperf/simpleperf_report.js"
    click spProto "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/profile-converter/simpleperf/simpleperf_report.proto"
    click profileViewer "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/profile-viewer/profileCustomEditor.ts"
    click logger "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/logger.ts"
    click utils "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/utils.ts"
    click commonTypes "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/commonTypes.ts"
    click extDeps "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/extensionDependencies.ts"
    click profilerInt "https://github.com/nisargjhaveri/vscode-android-debug/blob/main/src/profiler.ts"

    classDef vscodeCore fill:#e0ffe0,stroke:#0a0;
    classDef extension fill:#e0e0ff,stroke:#00f;
    classDef external fill:#f0f0f0,stroke:#888;
```
