# p1sec/qcsuper architecture

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

- Interactive diagram: https://gitdiagram.com/p1sec/qcsuper
- Repository: https://github.com/p1sec/qcsuper

## Overview

##### Project type and purpose
- QCSuper is a Python-based command-line tool for capturing mobile radio frames (2G/3G/4G/5G) over Qualcomm Diag protocol and exporting them (PCAP, JSON, DLF, etc.) or sending them live to Wireshark.
- It is organized as a CLI “full-stack” utility with three main layers: Input adapters, Protocol parsing/core, and Output modules.

##### File structure
- Top level:
- qcsuper.py / setup.py / README.md / docs / LICENSE
- src/:
- __main__.py – entry point
- inputs/ – all Input adapters (ADB, USB modem, TCP, DLF, JSON, HDLC mixin, external ADB binaries)
- protocol/ – definitions of Qualcomm Diag protocol messages, subsystems, GSMTAP encapsulation, log types
- modules/ – output modules (pcap dump, wireshark live, JSON geo, DLF dump, EFS shell, memory dump, decoded SIBs, CLI interactive)
- tests/ – unit tests for core functionality

##### README for additional insights
- Describes how QCSuper uses “input” to fetch raw Diag frames, the “modules” to process or persist those frames, and external tools like ADB, pyserial, pyusb, Wireshark.

a. Entry Point / CLI
- qcsuper.py / src/__main__.py that parses arguments, discovers Input adapters, loads Protocol layer, loads Modules.
b. Input Adapters Layer
- ADB Adapter (adb_bridge, adb_wsl2)
- USB Modem Adapter (usb_modem_pyserial, pyusb, device detection logic)
- TCP Adapter (tcp_connector)
- File Readers (dlf_read, json_geo_read)
c. Core Protocol Layer
- Diag protocol parser: protocol/messages.py, subsystems.py, efs2.py, gsmtap.py, log_types.py
- Helpers: protocol framing, CRC, message reassembly (SIBs), NAS decryption
d. Output Modules Layer
- pcap_dump / wireshark_live (GSMTAP packet generator)
- json_geo_dump / json_geo_read
- dlf_dump / dlf_read
- memory_dump
- decoded_sibs_dump
- efs_shell (interactive filesystem shell)
- cli interactive REPL
- info module
e. External Services / Tools
- ADB daemon on host <–> device
- USB subsystem / libusb
- Wireshark application
- System shell / su for device mode-switching
- Python libraries: pyserial, pyusb, crcmod, pycrate

##### Relationships & Data flows
1. User invokes CLI → argument parsing
2. CLI selects one Input adapter → establishes connection to device or file
3. Raw Diag data flows into Core Protocol layer → parsed into high-level messages
4. Core passes messages to enabled Modules
5. Each Module:
- processes messages (encapsulate in GSMTAP, decrypt, reassemble)
- writes output to file, spawns Wireshark, or drives an interactive shell
6. External dependencies:
- ADB or USB subsystem for Input
- Wireshark for live display

##### Architectural patterns & design principles
- Layered architecture (Input → Core → Modules)
- Plugin pattern (each input or module extends a base class)
- Single responsibility: adapters only fetch raw frames; protocol layer only parses; modules only produce outputs
- Dependency inversion: Core layer defines interfaces; concrete adapters and modules implement them
- Testable components: protocol and modules have unit tests under tests/

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point / CLI
    subgraph "Entry Point / CLI"
        direction TB
        QCSuper["qcsuper.py"] 
        Main["__main__.py"]
    end

    QCSuper -->|"invokes"| Main

    %% Input Adapters Layer
    subgraph "Input Adapters Layer" 
        direction TB
        BaseInput["_base_input.py"]:::inputAdapters
        HDLCMixin["_hdlc_mixin.py"]:::inputAdapters
        ADBAdapter["adb.py"]:::inputAdapters
        ADBBridge["adb_bridge"]:::inputAdapters
        ADBWSL2["adb_wsl2.py"]:::inputAdapters
        ADBWSL2Bridge["adb_wsl2_bridge.ps1"]:::inputAdapters
        USBArg["usb_modem_argparser.py"]:::inputAdapters
        USBPySerial["usb_modem_pyserial.py"]:::inputAdapters
        USBPyUSB["usb_modem_pyusb.py"]:::inputAdapters
        USBDevFinder["usb_modem_pyusb_devfinder.py"]:::inputAdapters
        TCPConnector["tcp_connector.py"]:::inputAdapters
        DLFReader["dlf_read.py"]:::inputAdapters
        JSONGeoReader["json_geo_read.py"]:::inputAdapters
        ExternalADB["external/adb/*"]:::inputAdapters
    end

    Main -->|"discovers adapters"| BaseInput
    BaseInput --> HDLCMixin
    BaseInput --> ADBAdapter
    ADBAdapter --> ADBBridge
    ADBAdapter --> ADBWSL2
    ADBWSL2 --> ADBWSL2Bridge
    BaseInput --> USBArg
    USBArg --> USBPySerial
    USBArg --> USBPyUSB
    USBPyUSB --> USBDevFinder
    BaseInput --> TCPConnector
    BaseInput --> DLFReader
    BaseInput --> JSONGeoReader
    BaseInput --> ExternalADB

    %% Core Protocol Layer
    subgraph "Core Protocol Layer"
        direction TB
        Messages["messages.py"]:::core
        Subsystems["subsystems.py"]:::core
        EFS2["efs2.py"]:::core
        GSMTAP["gsmtap.py"]:::core
        LogTypes["log_types.py"]:::core
    end

    Main -->|"loads protocol"| Messages
    BaseInput -->|"raw frames"| Messages
    Messages --> Subsystems
    Subsystems --> EFS2
    Subsystems --> GSMTAP
    Messages --> LogTypes

    %% Output Modules Layer
    subgraph "Output Modules Layer"
        direction TB
        PCAPDump["pcap_dump.py"]:::modules
        WiresharkLive["diag_nr_rrc_dissector.lua"]:::modules
        JSONGeoDump["json_geo_dump.py"]:::modules
        DLFDump["dlf_dump.py"]:::modules
        MemoryDump["memory_dump.py"]:::modules
        DecodedSIBs["decoded_sibs_dump.py"]:::modules
        EFSShell["efs_shell.py"]:::modules
        EFSShellCmds["efs_shell_commands/*"]:::modules
        CLIInteractive["cli.py"]:::modules
        InfoMod["info.py"]:::modules
    end

    GSMTAP --> PCAPDump
    GSMTAP --> WiresharkLive
    Messages --> JSONGeoDump
    Messages --> DLFDump
    Messages --> MemoryDump
    Messages --> DecodedSIBs
    Messages --> EFSShell
    EFSShell --> EFSShellCmds
    Messages --> CLIInteractive
    Messages --> InfoMod

    %% External Tools/Services
    subgraph "External Tools / Services"
        direction TB
        ADBDaemon["ADB Daemon"]:::external
        USBSubsystem["USB Subsystem / libusb"]:::external
        TCPEndpoint["TCP Endpoint"]:::external
        WiresharkApp["Wireshark"]:::external
        SysShell["System Shell / su"]:::external
        PyLibs["Python Libraries"]:::external
        FileSystem["File System"]:::external
        STDOUT["STDOUT"]:::external
    end

    ADBDaemon -->|"device access"| ADBAdapter
    USBSubsystem --> USBArg
    TCPEndpoint --> TCPConnector
    PCAPDump --> FileSystem
    JSONGeoDump --> FileSystem
    DLFDump --> FileSystem
    MemoryDump --> FileSystem
    DecodedSIBs --> FileSystem
    CLIInteractive --> STDOUT
    WiresharkLive --> WiresharkApp
    SysShell --> ADBWSL2Bridge
    PyLibs --> USBPySerial
    PyLibs --> USBPyUSB
    PyLibs --> GSMTAP

    %% Click Events
    click QCSuper "https://github.com/p1sec/qcsuper/blob/master/qcsuper.py"
    click Main "https://github.com/p1sec/qcsuper/blob/master/src/__main__.py"
    click BaseInput "https://github.com/p1sec/qcsuper/blob/master/src/inputs/_base_input.py"
    click HDLCMixin "https://github.com/p1sec/qcsuper/blob/master/src/inputs/_hdlc_mixin.py"
    click ADBAdapter "https://github.com/p1sec/qcsuper/blob/master/src/inputs/adb.py"
    click ADBBridge "https://github.com/p1sec/qcsuper/tree/master/src/inputs/adb_bridge"
    click ADBWSL2 "https://github.com/p1sec/qcsuper/blob/master/src/inputs/adb_wsl2.py"
    click ADBWSL2Bridge "https://github.com/p1sec/qcsuper/blob/master/src/inputs/adb_wsl2_bridge/adb_wsl2_bridge.ps1"
    click USBArg "https://github.com/p1sec/qcsuper/blob/master/src/inputs/usb_modem_argparser.py"
    click USBPySerial "https://github.com/p1sec/qcsuper/blob/master/src/inputs/usb_modem_pyserial.py"
    click USBPyUSB "https://github.com/p1sec/qcsuper/blob/master/src/inputs/usb_modem_pyusb.py"
    click USBDevFinder "https://github.com/p1sec/qcsuper/blob/master/src/inputs/usb_modem_pyusb_devfinder.py"
    click TCPConnector "https://github.com/p1sec/qcsuper/blob/master/src/inputs/tcp_connector.py"
    click DLFReader "https://github.com/p1sec/qcsuper/blob/master/src/inputs/dlf_read.py"
    click JSONGeoReader "https://github.com/p1sec/qcsuper/blob/master/src/inputs/json_geo_read.py"
    click ExternalADB "https://github.com/p1sec/qcsuper/tree/master/src/inputs/external/adb"
    click Messages "https://github.com/p1sec/qcsuper/blob/master/src/protocol/messages.py"
    click Subsystems "https://github.com/p1sec/qcsuper/blob/master/src/protocol/subsystems.py"
    click EFS2 "https://github.com/p1sec/qcsuper/blob/master/src/protocol/efs2.py"
    click GSMTAP "https://github.com/p1sec/qcsuper/blob/master/src/protocol/gsmtap.py"
    click LogTypes "https://github.com/p1sec/qcsuper/blob/master/src/protocol/log_types.py"
    click PCAPDump "https://github.com/p1sec/qcsuper/blob/master/src/modules/pcap_dump.py"
    click WiresharkLive "https://github.com/p1sec/qcsuper/blob/master/src/modules/wireshark_plugin/diag_nr_rrc_dissector.lua"
    click JSONGeoDump "https://github.com/p1sec/qcsuper/blob/master/src/modules/json_geo_dump.py"
    click DLFDump "https://github.com/p1sec/qcsuper/blob/master/src/modules/dlf_dump.py"
    click MemoryDump "https://github.com/p1sec/qcsuper/blob/master/src/modules/memory_dump.py"
    click DecodedSIBs "https://github.com/p1sec/qcsuper/blob/master/src/modules/decoded_sibs_dump.py"
    click EFSShell "https://github.com/p1sec/qcsuper/blob/master/src/modules/efs_shell.py"
    click EFSShellCmds "https://github.com/p1sec/qcsuper/tree/master/src/modules/efs_shell_commands"
    click CLIInteractive "https://github.com/p1sec/qcsuper/blob/master/src/modules/cli.py"
    click InfoMod "https://github.com/p1sec/qcsuper/blob/master/src/modules/info.py"

    %% Styles
    classDef inputAdapters fill:#e0f7fa,stroke:#006064,color:#006064;
    classDef core fill:#e8f5e9,stroke:#1b5e20,color:#1b5e20;
    classDef modules fill:#fff3e0,stroke:#e65100,color:#e65100;
    classDef external fill:#eceff1,stroke:#546e7a,color:#546e7a;
```
