# sunwu51/jvmbyteswaptool architecture

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

- Interactive diagram: https://gitdiagram.com/sunwu51/jvmbyteswaptool
- Repository: https://github.com/sunwu51/jvmbyteswaptool

## Overview

##### Project Type and Purpose
- The project is an instrumentation tool that enables hot swapping of JVM class bytecode while a Java process is running, making it especially useful when used with frameworks like Spring Boot.
- It leverages JVM instrumentation (JVMTI) along with bytecode manipulation libraries such as ASM and javassist.
- It provides a web UI (served on a configurable HTTP port) for real-time interaction with the running process.
- There is also a client component written in Go (in jbs-client) which suggests an external interface or a simplified entry point for some operations.

##### Analyzing the File Structure
- Top-Level Directories:
– “src”: Contains the main Java source code, including subpackages like “w/core” (which holds various transformer modules and the compiler), “w/web” (which implements HTTP and Websocket servers), and “w/util” (common utility classes).
– “jbs-client”: This directory contains a Go module (with go.mod, main.go, and UI related files) that appears to serve as a client or alternative front-end for interacting with the tool.
– “.github” and other project configuration/build files (pom.xml, maven wrapper scripts) indicate that the project is built via Maven and integrated with CI workflows.
- Architectural Patterns:
– The Java code is modularized into distinct packages (core for the instrumentation logic, web for the UI and messaging APIs, and model/asm for bytecode transformation). This separation suggests a layered/concentric style design.
– The presence of “Attach.java” indicates that the project likely attaches to a running JVM process to perform the swap operations.
– The “web” package clearly deals with external communication via HTTP and WebSocket endpoints.
– The “jbs-client” directory shows a client-side implementation in Go, which might directly initiate connections to the web server or drive the overall tool from a command-line perspective.

a. Main Components:
- Java Core Engine:
– Entry point (App.java)
– Instrumentation modules and bytecode transformers (e.g., ExecBundle, GroovyBundle, various Transformer classes in the “core/model” and “core/compiler” packages)
– Native utilities (via NativeUtils, SpringUtils, etc.)
- Web Interface Module:
– HTTP server (Httpd.java) that serves the web UI
– WebSocket server (Websocketd.java) for bi-directional communication between the server and connected clients
– Messaging classes (under “w/web/message”) that encapsulate commands such as Watch, Swap, Exec, etc.
- Client Component (jbs-client in Go):
– A separate client-side application that likely interacts with the web service endpoints via HTTP/WebSockets for performing hot swaps or receiving logs.
- Supporting Utilities and Configuration:
– Build scripts (Maven configuration and wrapper)
– Test suite within “src/test” for ensuring various functionalities.

b. Mapping Out Relationships and Data Flow:
- That the JVM ByteSwap Tool has a layered architecture:
– The application starts in the Java Core Engine (App.java) which may perform attaching operations to a running JVM.
– Once attached, the instrumented components (transformers, compilers) are ready to act based on incoming commands.
– The Web Interface Module provides a REST/HTTP interface and WebSocket APIs to the user. The web UI (accessed via a browser) connects to it.
– The messaging layer carries commands (such as “Watch”, “Exec”, “ReplaceClass”) between the web interface and the core engine.
– The Go-based jbs-client could be depicted as an alternative or supplementary client tool that issues similar requests to the web service.
– Client (browser or jbs-client) → HTTP/WebSocket → Web Interface Module.
– Web Interface Module → Core Engine (triggering bytecode transformation commands).
– Core Engine → (if applicable) feedback/status → Web Interface Module → Client.

c. Highlighting Architectural Patterns and Technologies:
- JVMTI instrumentation and dynamic class redefinition using ASM/javassist.
- That the system is intended to work with Spring Boot applications, thus the architecture is designed for dynamic and live modifications.
- The separation between core logic (bytecode transformation) and the web service layer reflects a design principle that decouples business logic from presentation/interaction layers.

d. Relevant Technologies:
- Java (JDK >= 1.8)
- Maven (build management)
- ASM & javassist (bytecode manipulation)
- JVMTI (JVM instrumentation API)
- Go (for the jbs-client implementation)
- Web technologies (HTTP and WebSocket protocols for the UI interaction)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        C1["Browser UI"]:::client
        C2["Go Client Application"]:::client
    end

    %% Web Interface Module
    subgraph "Web Interface Module"
        W1["HTTP Server (Httpd.java)"]:::web
        W2["WebSocket Server (Websocketd.java)"]:::web
        W3["Messaging Layer"]:::web
    end

    %% Core Instrumentation Engine
    subgraph "Core Instrumentation Engine"
        CORE1["Entry Point (App.java)"]:::core
        CORE2["Attaching Module (Attach.java)"]:::core
        CORE3["Instrumentation Modules"]:::core
            CORE3A["ASM Utilities"]:::core
            CORE3B["Compiler (WCompiler.java)"]:::core
            CORE3C["Model Transformers"]:::core
    end

    %% Supporting Utilities
    subgraph "Supporting Utilities"
        UTIL["Utility Classes"]:::util
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        BUILD["Maven Build Files"]:::build
    end

    %% Connections from Client Layer to Web Interface Module (HTTP/WS interaction)
    C1 -->|"HTTP/WS"| W1
    C1 -->|"HTTP/WS"| W2
    C2 -->|"HTTP/WS"| W1

    %% Connections within Web Interface Module
    W1 --> W3
    W2 --> W3

    %% Flow from Web Interface to Core Instrumentation Engine
    W3 -->|"commands"| CORE1

    %% Internal Core Instrumentation Engine flow
    CORE1 --> CORE2
    CORE1 --> CORE3
    CORE3 --> CORE3A
    CORE3 --> CORE3B
    CORE3 --> CORE3C

    %% Feedback from Core back to Web Interface and Clients
    CORE3 -->|"status_updates"| W3
    W3 -->|"ui_updates"| C1

    %% Supporting Utilities and Build connections
    UTIL -->|"provides utils"| CORE1
    BUILD -->|"builds"| CORE1

    %% Click Events for Java Core Engine
    click CORE1 "https://github.com/sunwu51/jvmbyteswaptool/blob/master/src/main/java/w/App.java"
    click CORE2 "https://github.com/sunwu51/jvmbyteswaptool/blob/master/src/main/java/w/Attach.java"
    click CORE3 "https://github.com/sunwu51/jvmbyteswaptool/tree/master/src/main/java/w/core"
    click CORE3A "https://github.com/sunwu51/jvmbyteswaptool/tree/master/src/main/java/w/core/asm"
    click CORE3B "https://github.com/sunwu51/jvmbyteswaptool/blob/master/src/main/java/w/core/compiler/WCompiler.java"
    click CORE3C "https://github.com/sunwu51/jvmbyteswaptool/tree/master/src/main/java/w/core/model"

    %% Click Events for Web Interface Module
    click W1 "https://github.com/sunwu51/jvmbyteswaptool/blob/master/src/main/java/w/web/Httpd.java"
    click W2 "https://github.com/sunwu51/jvmbyteswaptool/blob/master/src/main/java/w/web/Websocketd.java"
    click W3 "https://github.com/sunwu51/jvmbyteswaptool/tree/master/src/main/java/w/web/message"

    %% Click Event for Go Client Component
    click C2 "https://github.com/sunwu51/jvmbyteswaptool/tree/master/jbs-client"

    %% Click Event for Supporting Utilities
    click UTIL "https://github.com/sunwu51/jvmbyteswaptool/tree/master/src/main/java/w/util"

    %% Click Event for Build and Configuration
    click BUILD "https://github.com/sunwu51/jvmbyteswaptool/blob/master/pom.xml"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef web fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef client fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef util fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef build fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
