# mg1937/asc architecture

> Architecture diagram of the GitHub repository mg1937/asc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mg1937/asc
- Repository: https://github.com/mg1937/asc

## Overview

Droid ASC is an on-demand Android APK/DEX analysis and decompilation tool. Its main workflow locates a requested class in an APK, extracts its DEX, rebuilds a minimal DEX, and decompiles that class. Separate commands enumerate classes, decode the manifest, and search references across DEX entries; a GUI provides an interactive analysis surface. The graph follows the documented capabilities and sampled call sites; some GUI and APK-worker internals were not available, so uncertain wiring is omitted.

Main entry points: [`droidasc/asc_core/core/dex/dex_manager.py`](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dex/dex_manager.py) (DEX manager), [`droidasc/cli.py`](https://github.com/mg1937/asc/blob/main/droidasc/cli.py) (CLI commands), [`droidasc/asc_client/asc_handler.py`](https://github.com/mg1937/asc/blob/main/droidasc/asc_client/asc_handler.py) (Analysis facade), [`droidasc/asc_core/findrefs/findrefs_manager.py`](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/findrefs/findrefs_manager.py) (Reference manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_gui["Interactive GUI<br/>[app.py]"]
end

subgraph group_apk["APK access"]
  node_apk_handler["APK operations<br/>[apk_handler.py]"]
  node_manifest["Manifest decoder"]
end

subgraph group_engine["DEX analysis"]
  node_asc_handler["Analysis facade<br/>[asc_handler.py]"]
  node_dex_manager["DEX manager<br/>[dex_manager.py]"]
  node_interpreter["Opcode interpreter<br/>[dvm_interpreter.py]"]
  node_index_handler["Index collection<br/>[dvm_handlers.py]"]
  node_hollower["DEX extraction<br/>[dex_constructor.py]"]
  node_remapper["Index remapping<br/>[dex_remapper.py]"]
  node_builder["DEX builder<br/>[dex_builder.py]"]
  node_decompiler["Source decompiler<br/>[decompiler.py]"]
end

subgraph group_search["Reference search"]
  node_findrefs_manager["Reference manager"]
  node_locators["Reference locators"]
  node_scanner["Code scanner<br/>[code_item_scan.py]"]
end

node_user(("Analyst"))
node_apk_file["APK file"]
node_androguard["Androguard"]
node_results["Analysis output"]

node_user -->|"runs commands"| node_cli
node_user -->|"opens GUI"| node_gui
node_cli -->|"locates or lists"| node_apk_handler
node_cli -->|"decodes manifest"| node_manifest
node_cli -->|"requests decompilation"| node_asc_handler
node_cli -->|"writes results"| node_results
node_apk_file -->|"scanned by"| node_apk_handler
node_apk_file -->|"provides manifest"| node_manifest
node_manifest -.->|"decodes XML with"| node_androguard
node_apk_handler -->|"searches references through"| node_asc_handler
node_asc_handler -->|"extracts and rebuilds"| node_dex_manager
node_dex_manager -->|"interprets bytecode"| node_interpreter
node_dex_manager -->|"collects indices"| node_index_handler
node_interpreter -->|"dispatches opcodes"| node_index_handler
node_dex_manager -->|"hollows DEX"| node_hollower
node_dex_manager -->|"remaps indices"| node_remapper
node_dex_manager -->|"builds DEX"| node_builder
node_asc_handler -->|"decompiles rebuilt DEX"| node_decompiler
node_asc_handler -->|"searches references"| node_findrefs_manager
node_findrefs_manager -->|"resolves query indices"| node_locators
node_findrefs_manager -->|"scans references"| node_scanner
node_decompiler -->|"returns source"| node_results
node_findrefs_manager -->|"returns matches"| node_results
node_apk_handler -->|"returns class data"| node_results

click node_cli "https://github.com/mg1937/asc/blob/main/droidasc/cli.py"
click node_gui "https://github.com/mg1937/asc/blob/main/droidasc/asc_client/gui/app.py"
click node_apk_handler "https://github.com/mg1937/asc/blob/main/droidasc/asc_client/apk_handler.py"
click node_manifest "https://github.com/mg1937/asc/blob/main/droidasc/asc_client/manifest_handler.py"
click node_asc_handler "https://github.com/mg1937/asc/blob/main/droidasc/asc_client/asc_handler.py"
click node_dex_manager "https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dex/dex_manager.py"
click node_interpreter "https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dvm_interpreter.py"
click node_index_handler "https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dvm_handlers.py"
click node_hollower "https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dex/dex_constructor.py"
click node_remapper "https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dex/dex_remapper.py"
click node_builder "https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dex/dex_builder.py"
click node_decompiler "https://github.com/mg1937/asc/blob/main/droidasc/asc_core/utils/decompiler.py"
click node_findrefs_manager "https://github.com/mg1937/asc/blob/main/droidasc/asc_core/findrefs/findrefs_manager.py"
click node_locators "https://github.com/mg1937/asc/tree/main/droidasc/asc_core/findrefs/locator"
click node_scanner "https://github.com/mg1937/asc/blob/main/droidasc/asc_core/findrefs/scan/code_item_scan.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_gui toneBlue
class node_apk_handler,node_manifest toneAmber
class node_asc_handler,node_dex_manager,node_interpreter,node_index_handler,node_hollower,node_remapper,node_builder,node_decompiler toneMint
class node_findrefs_manager,node_locators,node_scanner toneRose
class node_user,node_apk_file,node_androguard,node_results toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/mg1937/asc/blob/main/droidasc/cli.py): `droidasc/cli.py`
- [Interactive GUI](https://github.com/mg1937/asc/blob/main/droidasc/asc_client/gui/app.py): `droidasc/asc_client/gui/app.py`

### APK access

- [APK operations](https://github.com/mg1937/asc/blob/main/droidasc/asc_client/apk_handler.py): `droidasc/asc_client/apk_handler.py`
- [Manifest decoder](https://github.com/mg1937/asc/blob/main/droidasc/asc_client/manifest_handler.py): `droidasc/asc_client/manifest_handler.py`

### DEX analysis

- [Analysis facade](https://github.com/mg1937/asc/blob/main/droidasc/asc_client/asc_handler.py): `droidasc/asc_client/asc_handler.py`
- [DEX manager](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dex/dex_manager.py): `droidasc/asc_core/core/dex/dex_manager.py`
- [Opcode interpreter](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dvm_interpreter.py): `droidasc/asc_core/core/dvm_interpreter.py`
- [Index collection](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dvm_handlers.py): `droidasc/asc_core/core/dvm_handlers.py`
- [DEX extraction](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dex/dex_constructor.py): `droidasc/asc_core/core/dex/dex_constructor.py`
- [Index remapping](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dex/dex_remapper.py): `droidasc/asc_core/core/dex/dex_remapper.py`
- [DEX builder](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/core/dex/dex_builder.py): `droidasc/asc_core/core/dex/dex_builder.py`
- [Source decompiler](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/utils/decompiler.py): `droidasc/asc_core/utils/decompiler.py`

### Reference search

- [Reference manager](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/findrefs/findrefs_manager.py): `droidasc/asc_core/findrefs/findrefs_manager.py`
- [Reference locators](https://github.com/mg1937/asc/tree/main/droidasc/asc_core/findrefs/locator): `droidasc/asc_core/findrefs/locator`
- [Code scanner](https://github.com/mg1937/asc/blob/main/droidasc/asc_core/findrefs/scan/code_item_scan.py): `droidasc/asc_core/findrefs/scan/code_item_scan.py`

### Other components

- **Analyst**
- **APK file**
- **Androguard**
- **Analysis output**

## Connections

- Analyst → CLI commands: runs commands
- Analyst → Interactive GUI: opens GUI
- CLI commands → APK operations: locates or lists
- CLI commands → Manifest decoder: decodes manifest
- CLI commands → Analysis facade: requests decompilation
- CLI commands → Analysis output: writes results
- APK file → APK operations: scanned by
- APK file → Manifest decoder: provides manifest
- Manifest decoder → Androguard: decodes XML with
- APK operations → Analysis facade: searches references through
- Analysis facade → DEX manager: extracts and rebuilds
- DEX manager → Opcode interpreter: interprets bytecode
- DEX manager → Index collection: collects indices
- Opcode interpreter → Index collection: dispatches opcodes
- DEX manager → DEX extraction: hollows DEX
- DEX manager → Index remapping: remaps indices
- DEX manager → DEX builder: builds DEX
- Analysis facade → Source decompiler: decompiles rebuilt DEX
- Analysis facade → Reference manager: searches references
- Reference manager → Reference locators: resolves query indices
- Reference manager → Code scanner: scans references
- Source decompiler → Analysis output: returns source
- Reference manager → Analysis output: returns matches
- APK operations → Analysis output: returns class data