# calebfenton/simplify architecture

> Architecture diagram of the GitHub repository calebfenton/simplify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/calebfenton/simplify
- Repository: https://github.com/calebfenton/simplify

## Overview

- A Dalvik VM sandbox (smalivm)
- A deobfuscation/optimization engine (simplify)
- A demo and a CLI debugger (demoapp and sdbg)

##### Project Type and Purpose
- This is a command-line deobfuscation tool and library suite (not a web or mobile front-end).
- It offers a core VM library (smalivm), an optimizer CLI (simplify), a smali debugger CLI (sdbg), and a demo Android app.

##### File Structure
- Top-level modules (each a Gradle subproject):
– smalivm
– simplify
– demoapp
– sdbg
– simplify/ObfuscatedApp (an Android example)
- The root also holds CI configs, licensing, wrapper scripts, and settings.gradle linking modules.
- Each module has:
– src/main/java or src/main/kotlin (code)
– src/main/resources (config, XMLs)
– build.gradle (build logic)

##### Key Insights from the README
- smalivm: Executes Dalvik bytecode, builds an execution graph of register/class values.
- simplify: Consumes those graphs, applies passes (constant propagation, dead-code removal, unreflection, peephole), then rewrites the DEX.
- demoapp: Simple Java examples showing how to embed smalivm.
- sdbg: A REPL-style smali debugger built on smalivm that exposes CLI commands.

##### Main Components
A. smalivm Library
– Parser & Loader (SmaliParser, SmaliFileFactory)
– VirtualMachineFactory → VirtualMachine
– ExecutionContext & ExecutionGraph builder
– Emulation layer (MethodEmulator, opcode handlers)
– Debugger & Breakpoint subsystem
– Configuration loader & framework JAR resources
B. simplify Engine (CLI)
– Launcher / Main
– ExecutionGraphManipulator
– Strategy modules (ConstantPropagation, DeadRemoval, Peephole, Unreflection)
– DEX rewriter / output module
C. CLI Debugger (sdbg)
– Initialize / Main
– REPL loop with commands (BreakCommand, StepCommand, PrintCommand…)
– Hooks into smalivm’s Debugger and MethodExecutor
D. Demo and Example Apps
– demoapp: Java app that invokes smalivm APIs for simple smali methods
– ObfuscatedApp: Android project used as input for simplify

##### Relationships and Data Flow
- Input Stage:
– User supplies a DEX/APK to the simplify CLI.
- smalivm Stage:
– Simplify calls smalivm to execute methods
– smalivm builds ExecutionGraphs
- simplify Stage:
– The engine applies optimization passes to each graph
– Graph manipulator returns transformed DEX bytecode
– Output is a new, simplified DEX/APK
- Auxiliary Paths:
– sdbg CLI uses smalivm directly for interactive debugging
– demoapp embeds smalivm in a standalone Java application

##### Architectural Patterns and Principles
- Modular, library-plus-CLI pattern
- Pipeline pattern: parsing → virtual execution → graph generation → graph optimization → code emission
- Strategy pattern for different optimization passes
- Factory pattern for VM, opcode, and class‐loading components
- Separation of concerns: smalivm is pure execution and graph building, simplify is graph analysis and transformation

##### Don’t Overcomplicate—Break Into Clear Components
- Under smalivm, group sub-packages by function (parsing, execution, context, emulation, opcode, debug, type, configuration)
- Under simplify, group core and strategy packages

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Modules
    subgraph "smalivm Library"
        direction TB
        ParserLoader["Parser & Loader"]:::smalivm
        VMFactory["VirtualMachineFactory & VirtualMachine"]:::smalivm
        Context["ExecutionContext & ExecutionGraph"]:::smalivm
        Emulation["MethodEmulator & Opcode Handlers"]:::smalivm
        Debug["Debugger & Breakpoint"]:::smalivm
        Config["Configuration Loader & Framework JAR"]:::smalivm
    end

    subgraph "simplify Engine"
        direction TB
        SimplifyMain["Main & Launcher"]:::simplify
        GraphManipulator["ExecutionGraphManipulator"]:::simplify
        Strategies["Strategy Modules"]:::simplify
        Optimizer["DEX Rewriter / Optimizer"]:::simplify
        Options["Options & Parser"]:::simplify
    end

    subgraph "sdbg CLI"
        direction TB
        SdbgMain["Main & Init"]:::sdbg
        Commands["REPL Commands"]:::sdbg
    end

    subgraph "Demo & Example Apps"
        direction TB
        DemoApp["demoapp Java App"]:::demo
        ObfApp["ObfuscatedApp Android"]:::demo
    end

    %% Documents
    Input["DEX/APK Input"]:::doc
    Output["Simplified DEX/APK"]:::doc

    %% Data Flow
    Input -->|"DEX/APK"| SimplifyMain
    SimplifyMain -->|"calls smalivm"| ParserLoader
    ParserLoader -->|"SmaliParser output"| VMFactory
    VMFactory --> Context
    Context --> Emulation
    Emulation --> Context
    Context -->|"ExecutionGraph"| GraphManipulator
    GraphManipulator --> Strategies
    Strategies --> Optimizer
    Optimizer --> Output

    SdbgMain -->|"uses Debugger"| Debug
    Commands --> Debug

    DemoApp -->|"calls smalivm API"| ParserLoader
    ObfApp -->|"input to simplify"| Input

    %% Click Events
    click ParserLoader "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/dex/SmaliParser.java"
    click ParserLoader "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/dex/SmaliFileFactory.java"
    click VMFactory "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/VirtualMachineFactory.java"
    click VMFactory "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/VirtualMachine.java"
    click Context "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/context/ExecutionContext.java"
    click Context "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/context/ExecutionGraph.java"
    click Context "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/context/ExecutionGrapher.java"
    click Emulation "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/emulate/MethodEmulator.java"
    click Emulation "https://github.com/calebfenton/simplify/tree/master/smalivm/src/main/java/org/cf/smalivm/opcode"
    click Debug "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/debug/Debugger.java"
    click Debug "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/debug/Breakpoint.java"
    click Config "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/java/org/cf/smalivm/configuration/ConfigurationLoader.java"
    click Config "https://github.com/calebfenton/simplify/blob/master/smalivm/src/main/resources/framework/android-framework.jar"
    click SimplifyMain "https://github.com/calebfenton/simplify/blob/master/simplify/src/main/java/org/cf/simplify/Main.java"
    click SimplifyMain "https://github.com/calebfenton/simplify/blob/master/simplify/src/main/java/org/cf/simplify/Launcher.java"
    click GraphManipulator "https://github.com/calebfenton/simplify/blob/master/simplify/src/main/java/org/cf/simplify/ExecutionGraphManipulator.java"
    click Strategies "https://github.com/calebfenton/simplify/blob/master/simplify/src/main/java/org/cf/simplify/strategy/ConstantPropagationStrategy.java"
    click Strategies "https://github.com/calebfenton/simplify/blob/master/simplify/src/main/java/org/cf/simplify/strategy/DeadRemovalStrategy.java"
    click Strategies "https://github.com/calebfenton/simplify/blob/master/simplify/src/main/java/org/cf/simplify/strategy/PeepholeStrategy.java"
    click Strategies "https://github.com/calebfenton/simplify/blob/master/simplify/src/main/java/org/cf/simplify/strategy/UnreflectionStrategy.java"
    click Optimizer "https://github.com/calebfenton/simplify/blob/master/simplify/src/main/java/org/cf/simplify/Optimizer.java"
    click Options "https://github.com/calebfenton/simplify/blob/master/simplify/src/main/java/org/cf/simplify/SimplifyOptions.java"
    click Options "https://github.com/calebfenton/simplify/blob/master/simplify/src/main/java/org/cf/simplify/SimplifyOptionsParser.java"
    click SdbgMain "https://github.com/calebfenton/simplify/blob/master/sdbg/src/main/java/org/cf/sdbg/Main.kt"
    click SdbgMain "https://github.com/calebfenton/simplify/blob/master/sdbg/src/main/java/org/cf/sdbg/Initialize.kt"
    click Commands "https://github.com/calebfenton/simplify/tree/master/sdbg/src/main/java/org/cf/sdbg/command"
    click DemoApp "https://github.com/calebfenton/simplify/blob/master/demoapp/src/main/java/org/cf/demoapp/Main.java"
    click DemoApp "https://github.com/calebfenton/simplify/tree/master/demoapp/resources/org/cf/demosmali"
    click ObfApp "https://github.com/calebfenton/simplify/tree/master/simplify/ObfuscatedApp/app/src/main/java/org/cf/obfuscated"

    %% Styles
    classDef smalivm fill:#ADD8E6,stroke:#000;
    classDef simplify fill:#90EE90,stroke:#000;
    classDef sdbg fill:#FFA500,stroke:#000;
    classDef demo fill:#D3D3D3,stroke:#000;
    classDef doc fill:#FFE4C4,stroke:#000;
```
