# hegaz0y/mtk_bypass architecture

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

- Interactive diagram: https://gitdiagram.com/hegaz0y/mtk_bypass
- Repository: https://github.com/hegaz0y/mtk_bypass

## Overview

##### Project type and purpose
- This is a command-line Python utility whose goal is to disable security protection on powered-off phones (MTK devices) so that SP Flash Tool can interact with them.
- It is not a full-stack web app or microservice; it is a single executable workflow that integrates with libusb, pyusb, pyserial and a native driver filter to perform a hardware exploit.

##### File structure
- Top-level:
- .gitignore, LICENSE, README.md, main entrypoint (main.py inferred from README).
- MTk_Bypass/ directory containing a second README, a driver helper script (Hegaz0y.py), and its own LICENSE.
- MTk_Bypass/src/:
- common.py – shared utilities
- config.py – loads and parses JSON5-based configuration
- device.py – abstracts USB/serial device detection & connection
- exploit.py – contains the bypass/exploit logic
- logger.py – logging facility
- Key indicators:
- The directory structure follows a logical “package” layout (modules under src).
- Interaction with external native driver (libusb-win32) and SP Flash Tool.

##### README for additional insights
- Setup steps: installing Python, libusb-win32, using a “filter wizard” to install a virtual serial device.
- Runtime: run main.py, detect the device, perform exploit, output “Protection disabled.”
- Integration point: after exploit, SP Flash Tool communicates directly with the phone.

##### Elements
- Clear labels for each Python module/component.
- User → main.py
- main.py → config, logger, device, exploit
- device ↔ libusb driver ↔ phone hardware
- phone hardware → SP Flash Tool
- External dependencies (green)
- Hardware (gray)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Setup
    User["User"]:::hardware
    Hegaz0y["Driver Helper Script\n(Hegaz0y.py)"]:::pythonModule
    click Hegaz0y "https://github.com/hegaz0y/mtk_bypass/blob/main/MTk_Bypass/Hegaz0y.py"
    User -->|Step 0: run helper| Hegaz0y

    %% CLI Entrypoint
    Main["CLI Entrypoint\n(main.py)"]:::pythonModule
    click Main "https://github.com/hegaz0y/mtk_bypass/blob/main/./main.py"
    User -->|Step 1: invoke CLI| Main

    %% Documentation and Licenses
    DocsRoot["Project README\n(README.md)"]:::externalLib
    click DocsRoot "https://github.com/hegaz0y/mtk_bypass/blob/main/./README.md"
    DocsPkg["Package README\n(MTk_Bypass/README.md)"]:::externalLib
    click DocsPkg "https://github.com/hegaz0y/mtk_bypass/blob/main/MTk_Bypass/README.md"
    LicenseRoot["Project License\n(LICENSE)"]:::externalLib
    click LicenseRoot "https://github.com/hegaz0y/mtk_bypass/tree/main/./LICENSE"
    LicensePkg["Package License\n(MTk_Bypass/LICENSE)"]:::externalLib
    click LicensePkg "https://github.com/hegaz0y/mtk_bypass/tree/main/MTk_Bypass/LICENSE"
    Main --> DocsRoot
    Main --> DocsPkg
    Main --> LicenseRoot
    Main --> LicensePkg

    %% Python Modules Subgraph
    subgraph "Python Modules" 
        direction TB
        Common["Common Utilities\n(common.py)"]:::pythonModule
        click Common "https://github.com/hegaz0y/mtk_bypass/blob/main/MTk_Bypass/src/common.py"
        Config["Configuration Loader\n(config.py)"]:::pythonModule
        click Config "https://github.com/hegaz0y/mtk_bypass/blob/main/MTk_Bypass/src/config.py"
        Logger["Logger\n(logger.py)"]:::pythonModule
        click Logger "https://github.com/hegaz0y/mtk_bypass/blob/main/MTk_Bypass/src/logger.py"
        Device["Device Abstraction\n(device.py)"]:::pythonModule
        click Device "https://github.com/hegaz0y/mtk_bypass/blob/main/MTk_Bypass/src/device.py"
        Exploit["Exploit Engine\n(exploit.py)"]:::pythonModule
        click Exploit "https://github.com/hegaz0y/mtk_bypass/blob/main/MTk_Bypass/src/exploit.py"
    end

    Main -->|Step 2| Common
    Main -->|Step 3| Config
    Main -->|Step 4| Logger
    Main -->|Step 5| Device
    Main -->|Step 6| Exploit

    %% Module Interactions
    Config -->|loads JSON5 config| Common
    Exploit -->|uses| Device

    %% External Libraries and Drivers
    subgraph "External Dependencies"
        direction TB
        PyUSB["pyusb"]:::externalLib
        PySerial["pyserial"]:::externalLib
        JSON5["json5"]:::externalLib
        LibUSB["libusb-win32 Driver"]:::driver
    end

    Device -->|uses| PyUSB
    Device -->|uses| PySerial
    Config -->|parses JSON5| JSON5
    Device -->|interfaces via| LibUSB

    %% Hardware and Tools
    Phone["Target Phone\n(USB interface)"]:::hardware
    SPFT["SP Flash Tool"]:::driver

    LibUSB -->|shims USB| Phone
    Exploit -->|sends commands| Device
    Device -->|detects & opens| Phone
    Phone -->|now accessible| SPFT

    %% Classes
    classDef pythonModule fill:#D6E8FF,stroke:#0366d6,color:#000
    classDef externalLib fill:#E2F0D9,stroke:#228B22,color:#000
    classDef driver fill:#E2E2E2,stroke:#888888,color:#000
    classDef hardware fill:#F0E68C,stroke:#DAA520,color:#000
```
