# zrax/pycdc architecture

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

- Interactive diagram: https://gitdiagram.com/zrax/pycdc
- Repository: https://github.com/zrax/pycdc

## Overview

##### Project Type & Purpose
- A C++-based command-line tool providing two front-ends:
- **pycdas** – a Python byte-code disassembler
- **pycdc** – a Python byte-code decompiler
- Supports all Python versions by shipping version-specific opcode maps.

##### File Structure
- **Root sources**:
- `pycdas.cpp`, `pycdc.cpp` – CLI entrypoints
- `bytecode.cpp`/`.h`, `bytecode_ops.inl` – disassembler core
- `ASTNode.*`, `ASTree.*` – in-memory AST representation
- `pyc_*.cpp`/`.h` (module, code, numeric, object, sequence, string) – decompiler codegen
- `FastStack.h`, `data.*` – utilities
- **bytes/**: per-version opcode maps (e.g. `python_3_10.cpp`)
- **scripts/**: CI/Docker builds, Python-build patches, test harness setup
- **tests/**:
- `tests/input/…`.py – test Python snippets
- `tests/tokenized/…`.txt – expected disassembly
- `tests/run_tests.py` – test runner

##### README for Insights
- Confirms CMake-driven build, CLI usage patterns, support for marshalled code objects, plug-in style version control.

##### Main Components & Their Relationships
a. **CLI Front-Ends** (pycdas, pycdc)
– Parse command-line flags → open .pyc file
b. **Bytecode Loader** (`pyc_module`, `pyc_code`)
– Read header, extract raw byte stream or marshalled object
c. **Disassembler Engine** (`bytecode.cpp`, `bytecode_ops`)
– Uses version maps from `bytes/` → emits token stream
d. **AST Builder** (`ASTNode`, `ASTree`)
– Consumes tokens → constructs AST
e. **Decompiler Code Generator** (`pyc_numeric`, `pyc_object`, etc.)
– Traverses AST (Visitor pattern) → emits Python source
f. **Utilities** (`FastStack`, `data`)
g. **Version Maps** (`bytes/python_X_Y.cpp`)
– Plug-in modules for opcode definitions
h. **Testing Harness**
– Invokes CLI tools → compares output to expected tokens/source

Data Flow:
.pyc file → Loader → Disassembler → Token Stream → AST Builder → AST → Code Generator → .py source on stdout

##### Architectural Patterns & Design Principles
- **Modular layering**: loader, disassembler, AST, codegen
- **Plug-in/version pattern**: add new `bytes/python_X_Y.cpp` for new Python versions
- **Visitor**-style AST traversals for code generation
- **Separation of concerns**: tests, scripts, build system isolated

##### Technologies & Frameworks
- C++ (ISO, C++17 or later)
- CMake (build orchestration)
- Python scripts (testing, Dockerfile generation)
- GitHub Actions (CI workflows under `.github/workflows/`)

##### Essential Elements
- Build orchestration (CMake) as a separate top-level element
- Test harness path from CLI → tests → pass/fail reports

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level build orchestration
    CMake["CMakeLists.txt"]:::build

    %% Scripts and CI
    subgraph "Build & CI Scripts"
        direction TB
        ScriptsDir["scripts/"]:::scripts
        GHWorkflows[".github/workflows/"]:::scripts
    end

    %% CLI Front-Ends
    subgraph "CLI Front-Ends"
        direction TB
        PyCDAS["pycdas.cpp"]:::cli
        PyCDC["pycdc.cpp"]:::cli
    end

    %% Bytecode Loader
    subgraph "Bytecode Loader"
        direction TB
        PycModule["pyc_module.cpp/.h"]:::loader
        PycCode["pyc_code.cpp/.h"]:::loader
    end

    %% Disassembler Engine
    subgraph "Disassembler Engine"
        direction TB
        BytecodeCore["bytecode.cpp/.h"]:::disasm
        BytecodeOps["bytecode_ops.inl"]:::disasm
    end

    %% AST Builder
    subgraph "AST Builder"
        direction TB
        ASTNode["ASTNode.cpp/.h"]:::ast
        ASTree["ASTree.cpp/.h"]:::ast
    end

    %% Decompiler Code Generator
    subgraph "Decompiler Code Generator"
        direction TB
        PycNumeric["pyc_numeric.cpp/.h"]:::codegen
        PycObject["pyc_object.cpp/.h"]:::codegen
        PycSequence["pyc_sequence.cpp/.h"]:::codegen
        PycString["pyc_string.cpp/.h"]:::codegen
    end

    %% Utilities
    Utilities["FastStack.h\ndata.cpp/.h"]:::util

    %% Version Maps
    subgraph "Version Maps (bytes/)"
        direction TB
        MapHeader["bytecode_map.h"]:::version
        PyVersions["python_1_0.cpp…python_3_13.cpp"]:::version
    end

    %% Testing Harness
    subgraph "Testing Harness"
        direction TB
        TestRunner["tests/run_tests.py"]:::tests
        TestInput["tests/input/…"]:::tests
        TestExpected["tests/tokenized/…"]:::tests
    end

    %% Data Flow
    PyCDAS -->|"invoke"| PycModule
    PyCDC -->|"invoke"| PycModule
    PycModule -->|"read .pyc byte stream"| BytecodeCore
    PycCode -->|"read marshalled object"| BytecodeCore
    BytecodeCore -->|"apply opcode map"| BytecodeOps
    BytecodeOps -->|"token stream"| ASTNode
    ASTNode -->|"AST"| ASTree
    ASTree -->|"AST"| PycNumeric
    PycNumeric -->|"visit AST"| PycObject
    PycObject -->|"visit AST"| PycSequence
    PycSequence -->|"visit AST"| PycString
    PycString -->|"emit Python source"| Output["stdout .py"]:::external

    %% Utilities and Version Maps integration
    Utilities -.-> BytecodeCore
    Utilities -.-> PycNumeric
    MapHeader --> BytecodeOps
    PyVersions --> BytecodeOps

    %% Build & CI connections
    CMake --> PyCDAS
    CMake --> PyCDC
    CMake --> PycModule
    CMake --> BytecodeCore
    CMake --> ASTNode
    CMake --> PycNumeric
    CMake --> ScriptsDir
    CMake --> GHWorkflows

    %% Testing connections
    TestRunner --> PyCDAS
    TestRunner --> PyCDC
    TestRunner --> TestInput
    TestRunner --> TestExpected
    TestRunner -->|"runs tests"| Report["pass/fail"]:::external

    %% Click Events
    click PyCDAS "https://github.com/zrax/pycdc/blob/master/pycdas.cpp"
    click PyCDC "https://github.com/zrax/pycdc/blob/master/pycdc.cpp"
    click PycModule "https://github.com/zrax/pycdc/blob/master/pyc_module.cpp"
    click PycModule "https://github.com/zrax/pycdc/blob/master/pyc_module.h"
    click PycCode "https://github.com/zrax/pycdc/blob/master/pyc_code.cpp"
    click PycCode "https://github.com/zrax/pycdc/blob/master/pyc_code.h"
    click BytecodeCore "https://github.com/zrax/pycdc/blob/master/bytecode.cpp"
    click BytecodeCore "https://github.com/zrax/pycdc/blob/master/bytecode.h"
    click BytecodeOps "https://github.com/zrax/pycdc/blob/master/bytecode_ops.inl"
    click ASTNode "https://github.com/zrax/pycdc/blob/master/ASTNode.cpp"
    click ASTNode "https://github.com/zrax/pycdc/blob/master/ASTNode.h"
    click ASTree "https://github.com/zrax/pycdc/blob/master/ASTree.cpp"
    click ASTree "https://github.com/zrax/pycdc/blob/master/ASTree.h"
    click PycNumeric "https://github.com/zrax/pycdc/blob/master/pyc_numeric.cpp"
    click PycNumeric "https://github.com/zrax/pycdc/blob/master/pyc_numeric.h"
    click PycObject "https://github.com/zrax/pycdc/blob/master/pyc_object.cpp"
    click PycObject "https://github.com/zrax/pycdc/blob/master/pyc_object.h"
    click PycSequence "https://github.com/zrax/pycdc/blob/master/pyc_sequence.cpp"
    click PycSequence "https://github.com/zrax/pycdc/blob/master/pyc_sequence.h"
    click PycString "https://github.com/zrax/pycdc/blob/master/pyc_string.cpp"
    click PycString "https://github.com/zrax/pycdc/blob/master/pyc_string.h"
    click Utilities "https://github.com/zrax/pycdc/blob/master/FastStack.h"
    click Utilities "https://github.com/zrax/pycdc/blob/master/data.cpp"
    click Utilities "https://github.com/zrax/pycdc/blob/master/data.h"
    click MapHeader "https://github.com/zrax/pycdc/blob/master/bytes/bytecode_map.h"
    click PyVersions "https://github.com/zrax/pycdc/blob/master/bytes/python_1_0.cpp"
    click PyVersions "https://github.com/zrax/pycdc/blob/master/bytes/python_3_13.cpp"
    click TestRunner "https://github.com/zrax/pycdc/blob/master/tests/run_tests.py"
    click TestInput "https://github.com/zrax/pycdc/tree/master/tests/input/"
    click TestExpected "https://github.com/zrax/pycdc/tree/master/tests/tokenized/"
    click CMake "https://github.com/zrax/pycdc/blob/master/CMakeLists.txt"
    click ScriptsDir "https://github.com/zrax/pycdc/tree/master/scripts/"
    click GHWorkflows "https://github.com/zrax/pycdc/tree/master/.github/workflows/"

    %% Styles
    classDef build fill:#f0f8ff,stroke:#333,stroke-width:1px
    classDef scripts fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef cli fill:#add8e6,stroke:#333,stroke-width:1px
    classDef loader fill:#e6e6fa,stroke:#333,stroke-width:1px
    classDef disasm fill:#ffebcd,stroke:#333,stroke-width:1px
    classDef ast fill:#fafad2,stroke:#333,stroke-width:1px
    classDef codegen fill:#e0ffff,stroke:#333,stroke-width:1px
    classDef util fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef version fill:#ffe4e1,stroke:#333,stroke-width:1px
    classDef tests fill:#f5f5dc,stroke:#333,stroke-width:1px
    classDef external fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
