# niklashigi/apk-mitm architecture

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

- Interactive diagram: https://gitdiagram.com/niklashigi/apk-mitm
- Repository: https://github.com/niklashigi/apk-mitm

## Overview

##### File structure
- bin/apk-mitm: the shim that invokes `dist/cli.js` when you run `apk-mitm`
- src/cli.ts & src/index.ts: argument parsing and high-level orchestration
- src/tasks/: each file here is one step in the pipeline (decode, modify manifest, inject network config, disable pinning, encode, sign, plus subfolder for Smali-level patches)
- src/tools/: wrappers around external binaries (Apktool, Uber-APK-Signer)
- src/utils/: low-level helpers (file system, downloads, process spawning, error reporting, globbing)
- README.md: explains features, flow, external dependencies (Java, apktool, uber-apk-signer), CLI parameters, and troubleshooting

##### Key insights from the README
- 5-stage pipeline: decode → patch manifest/NW config → patch Smali → re-encode → sign
- Uses Apktool (Java) and Uber-APK-Signer (Java) under the hood
- Offers a `--wait` hook for manual modifications
- Can handle both APKs and App Bundles (XAPK/APKS requires zip/unzip)

##### Detail
- Interplay between the Task Modules and the Tool Wrappers
- Utility layer as a shared service invoked by multiple components
- Do not oversimplify—include the Java VM and JARs as first-class nodes so that the complete end-to-end flow is visible

## Diagram (Mermaid)

```mermaid
flowchart TB
    User["User"]:::external
    subgraph "CLI Layer"
        CLI["CLI Entry Point"]:::node
        Orchestrator["Task Orchestrator"]:::node
    end
    User --> CLI
    CLI --> Orchestrator

    subgraph "Pipeline Tasks"
        CheckPrereq["Check Prerequisites Task"]:::node
        DownloadTools["Download Tools Task"]:::node
        DecodeAPK["Decode Task"]:::node
        ModifyManifest["Manifest Modifier Task"]:::node
        NetworkConfig["Network Security Config Task"]:::node
        DisablePinning["Certificate Pinning Disable Task"]:::node
        CopyCert["Copy Certificate File Task"]:::node
        SmaliParse["Smali: parse-head"]:::node
        SmaliPatches["Smali: patches"]:::node
        SmaliProcess["Smali: process-file"]:::node
        SmaliTypes["Smali: types"]:::node
        EncodeAPK["Encode Task"]:::node
        SignAPK["Sign Task"]:::node
    end

    Orchestrator --> CheckPrereq
    CheckPrereq --> DownloadTools
    DownloadTools --> DecodeAPK
    DecodeAPK --> ModifyManifest
    ModifyManifest --> NetworkConfig
    NetworkConfig --> DisablePinning
    DisablePinning --> CopyCert
    CopyCert --> SmaliParse
    SmaliParse --> SmaliPatches
    SmaliPatches --> SmaliProcess
    SmaliProcess --> SmaliTypes
    SmaliTypes --> EncodeAPK
    EncodeAPK --> SignAPK

    subgraph "Tool Wrappers"
        WrapApktool["Apktool Wrapper"]:::node
        WrapSigner["Uber-APK-Signer Wrapper"]:::node
        ToolBase["Common Tool Abstraction"]:::node
    end
    DownloadTools --> ToolBase
    ToolBase --> WrapApktool
    ToolBase --> WrapSigner
    DecodeAPK --> WrapApktool
    EncodeAPK --> WrapApktool
    SignAPK --> WrapSigner

    subgraph "Utility Layer"
        Utils["Utility Layer"]:::node
    end
    Utils -.-> CheckPrereq
    Utils -.-> DownloadTools
    Utils -.-> DecodeAPK
    Utils -.-> ModifyManifest
    Utils -.-> NetworkConfig
    Utils -.-> DisablePinning
    Utils -.-> CopyCert
    Utils -.-> SmaliParse
    Utils -.-> SmaliPatches
    Utils -.-> SmaliProcess
    Utils -.-> SmaliTypes
    Utils -.-> EncodeAPK
    Utils -.-> SignAPK

    subgraph "External Runtimes & Tools"
        JavaVM["Java VM"]:::external
        ApktoolJAR["Apktool JAR"]:::external
        SignerJAR["Uber-APK-Signer JAR"]:::external
    end
    WrapApktool --> JavaVM
    JavaVM --> ApktoolJAR
    WrapSigner --> JavaVM
    JavaVM --> SignerJAR

    subgraph "Storage"
        TempDir["Temporary Directory"]:::storage
        FinalAPK["Patched & Signed APK"]:::storage
    end
    DecodeAPK --> TempDir
    ModifyManifest --> TempDir
    NetworkConfig --> TempDir
    DisablePinning --> TempDir
    CopyCert --> TempDir
    SmaliProcess --> TempDir
    EncodeAPK --> TempDir
    SignAPK -->|writes| FinalAPK
    SignAPK -->|output path| CLI

    README["README & Docs"]:::node
    CLI --> README

    click CLI "https://github.com/niklashigi/apk-mitm/tree/main/bin/apk-mitm"
    click CLI "https://github.com/niklashigi/apk-mitm/blob/main/src/cli.ts"
    click Orchestrator "https://github.com/niklashigi/apk-mitm/blob/main/src/index.ts"
    click DecodeAPK "https://github.com/niklashigi/apk-mitm/blob/main/src/patch-apk.ts"
    click DecodeAPK "https://github.com/niklashigi/apk-mitm/blob/main/src/patch-app-bundle.ts"
    click CheckPrereq "https://github.com/niklashigi/apk-mitm/blob/main/src/tasks/check-prerequisites.ts"
    click DownloadTools "https://github.com/niklashigi/apk-mitm/blob/main/src/tasks/download-tools.ts"
    click ModifyManifest "https://github.com/niklashigi/apk-mitm/blob/main/src/tasks/modify-manifest.ts"
    click NetworkConfig "https://github.com/niklashigi/apk-mitm/blob/main/src/tasks/create-netsec-config.ts"
    click DisablePinning "https://github.com/niklashigi/apk-mitm/blob/main/src/tasks/disable-certificate-pinning.ts"
    click CopyCert "https://github.com/niklashigi/apk-mitm/blob/main/src/tasks/copy-certificate-file.ts"
    click SmaliParse "https://github.com/niklashigi/apk-mitm/blob/main/src/tasks/smali/parse-head.ts"
    click SmaliPatches "https://github.com/niklashigi/apk-mitm/blob/main/src/tasks/smali/patches.ts"
    click SmaliProcess "https://github.com/niklashigi/apk-mitm/blob/main/src/tasks/smali/process-file.ts"
    click SmaliTypes "https://github.com/niklashigi/apk-mitm/blob/main/src/tasks/smali/types.ts"
    click WrapApktool "https://github.com/niklashigi/apk-mitm/blob/main/src/tools/apktool.ts"
    click WrapSigner "https://github.com/niklashigi/apk-mitm/blob/main/src/tools/uber-apk-signer.ts"
    click ToolBase "https://github.com/niklashigi/apk-mitm/blob/main/src/tools/tool.ts"
    click Utils "https://github.com/niklashigi/apk-mitm/blob/main/src/utils/fs.ts"
    click README "https://github.com/niklashigi/apk-mitm/blob/main/README.md"
    click README "https://github.com/niklashigi/apk-mitm/tree/main/docs/troubleshooting/"

    classDef node fill:#cfe2ff,stroke:#0366d6,stroke-width:1px
    classDef external fill:#ffcc99,stroke:#d35400,stroke-width:1px
    classDef storage fill:#d5f5e3,stroke:#27ae60,stroke-width:1px
```
