# noidsirius/soottutorial architecture

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

- Interactive diagram: https://gitdiagram.com/noidsirius/soottutorial
- Repository: https://github.com/noidsirius/soottutorial

## Overview

1. This repository is a tutorial-style Java project for static program analysis with Soot. The code is organized as a small “analysis toolchain” plus a set of sample programs/APKs that serve as inputs to those analyses.

2. The main executable entrypoint is `src/main/java/dev/navids/soottutorial/Main.java`. It acts as a dispatcher: the first CLI argument selects which tutorial/analysis to run, and optional extra arguments control variants such as drawing a graph or choosing an Android call-graph algorithm.

3. The core analysis code is split by topic:
   - `hellosoot/` for the simplest Soot/Jimple and control-flow-graph examples.
   - `basicapi/` for basic Soot APIs on plain Java classes.
   - `intraanalysis/` for intraprocedural analyses, including `usagefinder/` and `npanalysis/`.
   - `android/` for Android-specific instrumentation, call graphs, and points-to analysis.
   - `visual/` for graph filtering and visualization support.

4. The simplest pipeline is in the `HelloSoot` chapter: a demo Java file under `demo/HelloSoot/FizzBuzz.java` is loaded, converted to Soot’s intermediate representation, and printed or visualized as a CFG. This chapter is about understanding Soot’s core IR and method-level control flow.

5. The `BasicAPI` chapter follows a similar pattern but targets `demo/BasicAPI/Circle.java`. It exercises Soot’s class/method inspection and call-graph-related APIs, showing how to traverse and summarize a Java program rather than just inspect one method.

6. The intraprocedural analysis subsystem works over small Java examples in `demo/IntraAnalysis/`. `UsageFinder` searches for uses of a particular method signature inside a program, while `npanalysis/` contains a null-pointer analysis built around custom flow-set logic. These are classic “analyze one program, report facts” tools rather than transformers.

7. The Android subsystem is the most boundary-heavy part of the repo. It consumes either a third-party APK (`demo/Android/calc.apk`) or the bundled demo app (`demo/Android/st_demo.apk`) and then uses Soot/FlowDroid-based utilities to build call graphs, run points-to analysis, and instrument bytecode. The Android classes are split between analysis logic and instrumentation helpers (`AndroidLogger`, `AndroidClassInjector`, `InstrumentUtil`, `AndroidUtil`).

8. Android instrumentation outputs a modified APK rather than just textual results. The README shows that instrumented artifacts are written under `demo/Android/Instrumented`, then signed with the provided scripts before installation. That creates a clear data flow: APK in → Soot transforms/injects code → signed APK out → device/runtime logs back via `adb logcat`.

9. The repository also includes a separate Android sample application source tree at `demo/Android/STDemoApp/`. This app is not the analysis engine; it is the analyzed target used for the call-graph and points-to chapters. Its compiled artifact is `demo/Android/st_demo.apk`.

10. The `visual/` package provides the graph-facing boundary between analysis results and human-readable output. It contains filters for generic and Android call graphs plus a `Visualizer` utility, which implies analysis results can be reduced before being rendered or displayed.

11. External dependencies are important to the architecture: the repo depends on Soot and several FlowDroid-related JARs under `lib/`. Android chapters also require the Android SDK, because some analyses operate on APKs and need Android platform classes during resolution and instrumentation.

12. Build and execution are Gradle-based at the root, with Gradle wrappers checked in for reproducibility. The README’s `./gradlew run --args="..."` pattern indicates one binary/tooling entrypoint that branches into multiple analysis workflows.

13. The repo is structured as a teaching artifact as much as a codebase. The `docs/` tree mirrors the tutorial chapters, while the `demo/` tree holds the concrete input programs/APKs that each chapter consumes. That separation is a key architectural boundary: tutorial text in `docs/`, analysis code in `src/main`, and sample targets in `demo/`.

14. Tests under `src/test/java/dev/navids/soottutorial/` exercise the main tutorial modules, including Android-specific cases. This suggests the analyses are intended to be runnable end-to-end in CI, not just as standalone demos.

15. In diagram terms, the main flow is: sample source/APK from `demo/` → Soot/FlowDroid-based analysis code in `src/main` → textual reports, call graphs, or transformed APKs → optional visualization or device execution. The major architectural boundaries are plain Java analysis vs. Android analysis, and analysis-only outputs vs. transformed runtime artifacts.

Main entry points: [`src/main/java/dev/navids/soottutorial/Main.java`](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/Main.java) (Main), [`src/main/java/dev/navids/soottutorial/android/AndroidCallgraph.java`](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidCallgraph.java) (Android CG), [`src/main/java/dev/navids/soottutorial/android/AndroidClassInjector.java`](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidClassInjector.java) (Instrument), [`src/main/java/dev/navids/soottutorial/android/AndroidPointsToAnalysis.java`](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidPointsToAnalysis.java) (Android PTA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Analysis Engine"]
  node_src_main["Main<br/>dispatcher<br/>[Main.java]"]
  node_hello_soot["HelloSoot<br/>tutorial analysis<br/>[HelloSoot.java]"]
  node_basic_api["BasicAPI<br/>tutorial analysis<br/>[BasicAPI.java]"]
  node_usage_finder["UsageFinder<br/>intra analysis<br/>[UsageFinder.java]"]
  node_np_analysis["Null Analysis<br/>intra analysis"]
  node_np_main["NPAMain<br/>analysis driver<br/>[NPAMain.java]"]
  node_android_cg["Android CG<br/>android analysis"]
  node_android_pta["Android PTA<br/>android analysis"]
  node_android_instrument["Instrument<br/>android transform"]
  node_android_util["Android Utils<br/>android support<br/>[AndroidUtil.java]"]
  node_visualizer["Visualizer<br/>visualization<br/>[Visualizer.java]"]
end

subgraph group_demo["Demo Inputs"]
  node_fizzbuzz["FizzBuzz<br/>demo java<br/>[FizzBuzz.java]"]
  node_circle["Circle<br/>demo java<br/>[Circle.java]"]
  node_usage_example["Usage Example<br/>demo java<br/>[UsageExample.java]"]
  node_np_example["Null Example<br/>demo java"]
  node_calc_apk["calc.apk<br/>android apk<br/>[calc.apk]"]
  node_st_demo_apk["st_demo.apk<br/>android apk<br/>[st_demo.apk]"]
end

subgraph group_androidapp["Android Sample App"]
  node_st_demo_app["STDemoApp<br/>android app source<br/>[MainActivity.java]"]
end

subgraph group_platform["Platform"]
  node_soot_libs[("Soot Libs<br/>external deps")]
  node_gradle_build["Gradle Build<br/>build system<br/>[build.gradle]"]
end

node_src_main -->|"dispatches"| node_hello_soot
node_src_main -->|"dispatches"| node_basic_api
node_src_main -->|"dispatches"| node_usage_finder
node_src_main -->|"dispatches"| node_np_main
node_src_main -->|"dispatches"| node_android_cg
node_src_main -->|"dispatches"| node_android_pta
node_src_main -->|"dispatches"| node_android_instrument
node_hello_soot -->|"analyzes"| node_fizzbuzz
node_basic_api -->|"analyzes"| node_circle
node_usage_finder -->|"analyzes"| node_usage_example
node_np_analysis -->|"analyzes"| node_np_example
node_np_main -->|"uses"| node_np_analysis
node_android_cg -->|"analyzes"| node_calc_apk
node_android_cg -->|"analyzes"| node_st_demo_apk
node_android_pta -->|"analyzes"| node_calc_apk
node_android_pta -->|"analyzes"| node_st_demo_app
node_android_instrument -->|"transforms"| node_calc_apk
node_android_instrument -->|"transforms"| node_st_demo_apk
node_android_instrument -->|"uses"| node_android_util
node_android_cg -->|"feeds"| node_visualizer
node_basic_api -->|"feeds"| node_visualizer
node_android_cg -->|"depends on"| node_soot_libs
node_android_pta -->|"depends on"| node_soot_libs
node_android_instrument -->|"depends on"| node_soot_libs
node_gradle_build -->|"builds"| node_src_main
node_gradle_build -->|"builds"| node_st_demo_app

click node_src_main "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/Main.java"
click node_hello_soot "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/hellosoot/HelloSoot.java"
click node_basic_api "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/basicapi/BasicAPI.java"
click node_usage_finder "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/intraanalysis/usagefinder/UsageFinder.java"
click node_np_analysis "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/intraanalysis/npanalysis/NullPointerAnalysis.java"
click node_np_main "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/intraanalysis/npanalysis/NPAMain.java"
click node_android_cg "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidCallgraph.java"
click node_android_pta "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidPointsToAnalysis.java"
click node_android_instrument "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidClassInjector.java"
click node_android_util "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidUtil.java"
click node_visualizer "https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/visual/Visualizer.java"
click node_fizzbuzz "https://github.com/noidsirius/soottutorial/blob/master/demo/HelloSoot/FizzBuzz.java"
click node_circle "https://github.com/noidsirius/soottutorial/blob/master/demo/BasicAPI/Circle.java"
click node_usage_example "https://github.com/noidsirius/soottutorial/blob/master/demo/IntraAnalysis/UsageExample.java"
click node_np_example "https://github.com/noidsirius/soottutorial/blob/master/demo/IntraAnalysis/NullPointerExample.java"
click node_calc_apk "https://github.com/noidsirius/soottutorial/blob/master/demo/Android/calc.apk"
click node_st_demo_apk "https://github.com/noidsirius/soottutorial/blob/master/demo/Android/st_demo.apk"
click node_st_demo_app "https://github.com/noidsirius/soottutorial/blob/master/demo/Android/STDemoApp/app/src/main/java/dev/navids/multicomp1/MainActivity.java"
click node_soot_libs "https://github.com/noidsirius/soottutorial/blob/master/lib/soot-infoflow-classes.jar"
click node_gradle_build "https://github.com/noidsirius/soottutorial/blob/master/build.gradle"

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_src_main,node_hello_soot,node_basic_api,node_usage_finder,node_np_analysis,node_np_main,node_android_cg,node_android_pta,node_android_instrument,node_android_util,node_visualizer toneBlue
class node_fizzbuzz,node_circle,node_usage_example,node_np_example,node_calc_apk,node_st_demo_apk toneAmber
class node_st_demo_app toneMint
class node_soot_libs,node_gradle_build toneRose
```

## Components

### Analysis Engine

Main Soot-based tutorial analyses and helpers

- [Main](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/Main.java): dispatcher · CLI entrypoint that selects which tutorial analysis to run · `src/main/java/dev/navids/soottutorial/Main.java`
- [HelloSoot](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/hellosoot/HelloSoot.java): tutorial analysis · Introductory Soot/Jimple and CFG demo · `src/main/java/dev/navids/soottutorial/hellosoot/HelloSoot.java`
- [BasicAPI](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/basicapi/BasicAPI.java): tutorial analysis · Class and method inspection plus call-graph-oriented API usage · `src/main/java/dev/navids/soottutorial/basicapi/BasicAPI.java`
- [UsageFinder](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/intraanalysis/usagefinder/UsageFinder.java): intra analysis · Finds uses of a target method signature in a program · `src/main/java/dev/navids/soottutorial/intraanalysis/usagefinder/UsageFinder.java`
- [Null Analysis](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/intraanalysis/npanalysis/NullPointerAnalysis.java): intra analysis · Custom intraprocedural null-pointer analysis · `src/main/java/dev/navids/soottutorial/intraanalysis/npanalysis/NullPointerAnalysis.java`
- [NPAMain](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/intraanalysis/npanalysis/NPAMain.java): analysis driver · Entry driver for the null-pointer analysis chapter · `src/main/java/dev/navids/soottutorial/intraanalysis/npanalysis/NPAMain.java`
- [Android CG](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidCallgraph.java): android analysis · Builds Android call graphs with Soot/FlowDroid support · `src/main/java/dev/navids/soottutorial/android/AndroidCallgraph.java`
- [Android PTA](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidPointsToAnalysis.java): android analysis · Points-to analysis over Android apps · `src/main/java/dev/navids/soottutorial/android/AndroidPointsToAnalysis.java`
- [Instrument](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidClassInjector.java): android transform · APK instrumentation and class injection utilities · `src/main/java/dev/navids/soottutorial/android/AndroidClassInjector.java`
- [Android Utils](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/android/AndroidUtil.java): android support · Shared Android helpers, logging, and instrumentation utilities · `src/main/java/dev/navids/soottutorial/android/AndroidUtil.java`
- [Visualizer](https://github.com/noidsirius/soottutorial/blob/master/src/main/java/dev/navids/soottutorial/visual/Visualizer.java): visualization · Reduces and renders analysis output such as call graphs · `src/main/java/dev/navids/soottutorial/visual/Visualizer.java`

### Demo Inputs

Small Java programs and APKs analyzed by the tutorials

- [FizzBuzz](https://github.com/noidsirius/soottutorial/blob/master/demo/HelloSoot/FizzBuzz.java): demo java · HelloSoot demo program used as the simplest analysis input · `demo/HelloSoot/FizzBuzz.java`
- [Circle](https://github.com/noidsirius/soottutorial/blob/master/demo/BasicAPI/Circle.java): demo java · BasicAPI demo class used for class and method traversal · `demo/BasicAPI/Circle.java`
- [Usage Example](https://github.com/noidsirius/soottutorial/blob/master/demo/IntraAnalysis/UsageExample.java): demo java · Sample program for method-usage searching · `demo/IntraAnalysis/UsageExample.java`
- [Null Example](https://github.com/noidsirius/soottutorial/blob/master/demo/IntraAnalysis/NullPointerExample.java): demo java · Sample program for null-pointer analysis · `demo/IntraAnalysis/NullPointerExample.java`
- [calc.apk](https://github.com/noidsirius/soottutorial/blob/master/demo/Android/calc.apk): android apk · Third-party APK used as an Android analysis target · `demo/Android/calc.apk`
- [st_demo.apk](https://github.com/noidsirius/soottutorial/blob/master/demo/Android/st_demo.apk): android apk · Bundled compiled Android target app · `demo/Android/st_demo.apk`

### Android Sample App

Bundled target app used by Android analyses

- [STDemoApp](https://github.com/noidsirius/soottutorial/blob/master/demo/Android/STDemoApp/app/src/main/java/dev/navids/multicomp1/MainActivity.java): android app source · Source tree for the bundled Android sample application · `demo/Android/STDemoApp/app/src/main/java/dev/navids/multicomp1/MainActivity.java`

### Platform

Build and external analysis dependencies

- [Soot Libs](https://github.com/noidsirius/soottutorial/blob/master/lib/soot-infoflow-classes.jar): external deps · Soot and FlowDroid-related libraries used by the analyses · `lib/soot-infoflow-classes.jar`
- [Gradle Build](https://github.com/noidsirius/soottutorial/blob/master/build.gradle): build system · Root Gradle-based build and execution entrypoint · `build.gradle`

## Connections

- Main → HelloSoot: dispatches · CLI selects HelloSoot tutorial
- Main → BasicAPI: dispatches · CLI selects BasicAPI tutorial
- Main → UsageFinder: dispatches · CLI selects usage-finding analysis
- Main → NPAMain: dispatches · CLI selects null-pointer analysis run
- Main → Android CG: dispatches · CLI selects Android call-graph workflow
- Main → Android PTA: dispatches · CLI selects Android points-to workflow
- Main → Instrument: dispatches · CLI selects APK instrumentation workflow
- HelloSoot → FizzBuzz: analyzes · Loads the demo program and prints or visualizes its CFG
- BasicAPI → Circle: analyzes · Inspects the demo Java class
- UsageFinder → Usage Example: analyzes · Searches the sample program for target method uses
- Null Analysis → Null Example: analyzes · Runs intraprocedural null analysis on the sample program
- NPAMain → Null Analysis: uses · Driver wires up the flow analysis
- Android CG → calc.apk: analyzes · Builds a call graph over an APK input
- Android CG → st_demo.apk: analyzes · Builds a call graph over the bundled demo app artifact
- Android PTA → calc.apk: analyzes · Runs Android points-to analysis on APK input
- Android PTA → STDemoApp: analyzes · Uses the bundled app source/artifact as Android target
- Instrument → calc.apk: transforms · Injects code into an APK
- Instrument → st_demo.apk: transforms · Produces a modified runtime artifact from the demo app
- Instrument → Android Utils: uses · Shares logging and instrumentation helpers
- Android CG → Visualizer: feeds · Call graphs can be filtered and visualized
- BasicAPI → Visualizer: feeds · Program summaries can be rendered
- Android CG → Soot Libs: depends on · Uses Soot/FlowDroid libraries
- Android PTA → Soot Libs: depends on · Uses Soot/FlowDroid libraries
- Instrument → Soot Libs: depends on · Uses Soot and Android infoflow classes
- Gradle Build → Main: builds · Compiles and runs the main tutorial tool
- Gradle Build → STDemoApp: builds · Builds the bundled Android sample app
