# suifei/asm2hex2 architecture

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

- Interactive diagram: https://gitdiagram.com/suifei/asm2hex2
- Repository: https://github.com/suifei/asm2hex2

## Overview

##### Project Type and Purpose
- Type: Cross-platform desktop GUI application (with a bundled CLI tool).
- Purpose: Bi-directional conversion between assembly and machine code (hex) using Capstone (disassembler) and Keystone (assembler), with a native GUI front-end powered by wxWidgets and a small CLI called cstool.

##### File Structure
Top-level view:
- CMakeLists.txt – build orchestrator
- dep/ – pre-downloaded dependencies:
– capstone/ + libcapstone.a
– keystone/ + libkeystone.a
– wxWidgets headers + libs (Windows)
- src/ – C++ source code:
– App.cpp/hpp, MainWindow.cpp/hpp, AboutDialog.cpp/hpp, Resources.*
– CsEngine.cpp/hpp, KsEngine.cpp/hpp (wrappers around Capstone/Keystone)
– OSCross.hpp (OS abstraction)
– cstool/ – standalone C CLI tool
- doc/, screenshots/, README.md – documentation and assets

##### README for Technical Stack
- GUI: wxWidgets (3.x)
- Engines: Capstone Engine (disassembly), Keystone Engine (assembly)
- Build: CMake, Ninja/MSVC/g++
- Languages: C++11, C for cstool

##### Main Components
A. Build System
– CMake + generator (Ninja, MSVC, make)
– Pulls in dep/lib and dep/include, compiles src, links static libs
B. UI Layer
– App (entry point)
– MainWindow (layout, menus, input controls: text fields, buttons)
– wxWidgets runtime library
C. Engine Layer
– KsEngine (wraps Keystone C API)
– CsEngine (wraps Capstone C API)
– OSCross (uniform OS calls if any)
D. External Libraries
– libkeystone.a, libcapstone.a (static)
– wxWidgets (static/dynamic)
E. CLI Sub-Tool
– cstool executable (links Capstone only, small printf wrapper)
F. OS Platform
– Windows, macOS, Linux (abstracted by wxWidgets & OSCross)

##### Relationships and Data Flows
- User enters ASM or HEX in UI → MainWindow controller
- MainWindow calls either KsEngine (assemble) or CsEngine (disassemble)
- Engine wrappers invoke Keystone/Capstone C API → process input → return results
- MainWindow renders output, syntax highlights via wxWidgets controls
- CLI: user invokes cstool → direct call into cstool.c source → Capstone → console output
- Build System fetches includes/libs from dep/, compiles everything per CMakeLists.txt

##### Architectural Patterns & Design Principles
- Layered separation:
– Presentation (wxWidgets UI)
– Application Logic (MainWindow, dialog controllers)
– Domain Logic (KsEngine, CsEngine wrappers)
– Infrastructure (external libs, OS abstraction)
- Single Responsibility: each engine wrapper handles one API.
- Cross-platform abstraction: wxWidgets + OSCross for OS-specific calls.
- Reuse of prebuilt deps under dep/ folder.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System Layer
    BuildSys["CMakeLists.txt"]:::build
    BuildSys -->|gathers deps/includes| DepDir

    %% Dependencies Layer
    subgraph "Dependencies" 
        direction TB
        DepDir["dep/"]:::external
        DepDir --> CapHeaders
        DepDir --> CapLib
        DepDir --> KeyHeaders
        DepDir --> KeyLib
        DepDir --> WXHdr
        DepDir --> WXLib
    end

    CapHeaders["capstone include"]:::external
    CapLib["libcapstone.a"]:::external
    KeyHeaders["keystone include"]:::external
    KeyLib["libkeystone.a"]:::external
    WXHdr["wxWidgets headers"]:::external
    WXLib["wxWidgets libs"]:::external

    %% Core Application Layer
    subgraph "Core Application (src/)" 
        direction TB
        App["App (src/App.cpp/hpp)"]:::frontend
        MainWindow["MainWindow (src/MainWindow.cpp/hpp)"]:::frontend
        About["AboutDialog (src/AboutDialog.cpp/hpp)"]:::frontend
        Resources["Resources (src/Resources.cpp/hpp)"]:::frontend
    end

    %% Engine Layer
    subgraph "Engine Wrappers (src/)" 
        direction TB
        CsEngine["CsEngine (src/CsEngine.cpp/hpp)"]:::engine
        KsEngine["KsEngine (src/KsEngine.cpp/hpp)"]:::engine
        OSCross["OSCross (src/OSCross.hpp)"]:::engine
    end

    %% CLI Tool
    CLI["cstool (src/cstool/)"]:::frontend

    %% OS/Platform Layer
    subgraph "OS Platforms" 
        direction TB
        OS["Windows/macOS/Linux"]:::os
    end

    %% UI Library
    WX["wxWidgets Runtime"]:::external

    %% Build Outputs
    BuildSys -->|builds| App
    BuildSys -->|builds| CLI

    %% UI Flow
    App -->|starts| MainWindow
    MainWindow -->|opens| About
    MainWindow -->|loads| Resources
    MainWindow -->|user input| CsEngine
    MainWindow -->|user input| KsEngine
    CsEngine -->|disassembly C API call| CapHeaders
    CsEngine --> CapLib
    KsEngine -->|assembly C API call| KeyHeaders
    KsEngine --> KeyLib
    App -->|uses| WX
    MainWindow -->|renders UI| WX
    App -->|abstracted OS calls| OSCross
    MainWindow --> OSCross
    OSCross --> OS
    WX --> OS

    %% CLI Flow
    CLI -->|invokes disassembly| CsEngine

    %% Click Events
    click BuildSys "https://github.com/suifei/asm2hex2/blob/main/CMakeLists.txt"
    click DepDir "https://github.com/suifei/asm2hex2/tree/main/dep/"
    click App "https://github.com/suifei/asm2hex2/blob/main/src/App.cpp"
    click MainWindow "https://github.com/suifei/asm2hex2/blob/main/src/MainWindow.cpp"
    click About "https://github.com/suifei/asm2hex2/blob/main/src/AboutDialog.cpp"
    click Resources "https://github.com/suifei/asm2hex2/blob/main/src/Resources.cpp"
    click CsEngine "https://github.com/suifei/asm2hex2/blob/main/src/CsEngine.cpp"
    click KsEngine "https://github.com/suifei/asm2hex2/blob/main/src/KsEngine.cpp"
    click OSCross "https://github.com/suifei/asm2hex2/blob/main/src/OSCross.hpp"
    click CLI "https://github.com/suifei/asm2hex2/tree/main/src/cstool/"
    click CapHeaders "https://github.com/suifei/asm2hex2/tree/main/dep/capstone/include/"
    click CapLib "https://github.com/suifei/asm2hex2/blob/main/dep/lib/osx/libcapstone.a"
    click KeyHeaders "https://github.com/suifei/asm2hex2/tree/main/dep/keystone/include/"
    click KeyLib "https://github.com/suifei/asm2hex2/blob/main/dep/lib/osx/libkeystone.a"
    click WXHdr "https://github.com/suifei/asm2hex2/tree/main/dep/win/include/wx/"
    click WXLib "https://github.com/suifei/asm2hex2/tree/main/dep/win/lib/gcc_lib/"

    %% Styles
    classDef build fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef engine fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef os fill:#D3D3D3,stroke:#333,stroke-width:1px
```
