# sim0n/caesium architecture

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

- Interactive diagram: https://gitdiagram.com/sim0n/caesium
- Repository: https://github.com/sim0n/caesium

## Overview

##### Project type and purpose
- Caesium is a standalone Java desktop application (Swing‐based GUI) that performs Java bytecode obfuscation.
- It reads an input JAR (and its dependencies), applies a configurable set of “mutator” transformations on the bytecode, and emits a mutated JAR.

##### File structure
- Top-level: pom.xml (Maven build), .github/workflows/maven.yml (CI), README, LICENSE.
- src/main/java/dev/sim0n/caesium: core packages:
- “gui” – Swing UI classes (CGui, LibraryTab)
- “manager” – ClassManager & MutatorManager orchestration
- “mutator” – ClassMutator interface + implementations (e.g., ControlFlowMutator, StringMutator, CrasherMutator)
- “util” – Various helper modules (ASMUtil, ByteUtil, OSUtil, wrapper, classwriter)
- PreRuntime, Start, Caesium – bootstrapping and core engine
- src/main/resources: configuration (caesium.properties), logging (log4j2.xml)

##### README for additional insights
- Confirms a plugin-style mutator architecture.
- Emphasizes performance, dependency requirements, and UI usage flow.

a. Input/Output
- Input: User-selected JAR + external dependencies
- Output: Obfuscated JAR
b. GUI Layer
- CGui & LibraryTab: lets user pick mutators, launch “Mutate”
- Sends user choices to the Core Engine
c. Core Engine
- Start → PreRuntime → Caesium: bootstrap, load configuration, initialize managers
- ClassManager: reads class files via ASM (using CaesiumClassWriter, ClassTree)
- MutatorManager: holds available ClassMutator implementations
d. Mutator Plugins
- Each ClassMutator impl applies a specific transformation on the in-memory class tree
- May invoke utilities (ByteUtil, StringUtil, Dictionary, OSUtil)
e. Utilities & External Libraries
- ASM library (invoked via ASMUtil & classwriter)
- Logging (log4j2)
- Wrapper classes for reflection/bytecode manipulation
f. Configuration & Resources
- caesium.properties drives default settings
- log4j2.xml configures logging levels and appenders

Data flow:
1. User clicks “Mutate” → GUI calls Core Engine
2. Core Engine loads input classes → ClassManager builds ClassTree
3. MutatorManager iterates selected mutators → transforms ClassTree
4. ClassTree written out via CaesiumClassWriter & ASM → output JAR
5. GUI displays completion/failure

##### Architectural patterns & principles
- Plugin/Strategy pattern for mutators (ClassMutator interface + multiple impls)
- Modular separation: UI vs. Engine vs. Plugins vs. Utilities
- Single JAR monolith (no microservices)
- Clear layering: Presentation → Orchestration → Transformation → I/O

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input/Output
    InputJar["Input JAR"]:::io
    OutputJar["Obfuscated JAR"]:::io

    %% Desktop Application Boundary
    subgraph "Desktop Application"
        %% UI Layer
        subgraph "UI Layer"
            CGui["CGui"]:::ui
            LibraryTab["LibraryTab"]:::ui
        end

        %% Core Engine
        subgraph "Core Engine"
            Start["Start"]:::core
            PreRuntime["PreRuntime"]:::core
            CaesiumCore["Caesium"]:::core
            ClassManager["ClassManager"]:::core
            MutatorManager["MutatorManager"]:::core
        end

        %% Mutator Plugins
        subgraph "Mutator Plugins"
            ClassMutator["ClassMutator"]:::plugin
            subgraph "Implementations"
                AttributeMutator["AttributeMutator"]:::plugin
                ControlFlowMutator["ControlFlowMutator"]:::plugin
                StringMutator["StringMutator"]:::plugin
                BadAnnotationMutator["BadAnnotationMutator"]:::plugin
                ImageCrashMutator["ImageCrashMutator"]:::plugin
            end
        end

        %% Utilities & Helpers
        subgraph "Utilities & Helpers"
            ASMUtil["ASMUtil"]:::util
            CaesiumClassWriter["CaesiumClassWriter"]:::util
            ClassTree["ClassTree"]:::util
            ByteUtil["ByteUtil"]:::util
            Dictionary["Dictionary"]:::util
            OSUtil["OSUtil"]:::util
            OS["OS"]:::util
            StringUtil["StringUtil"]:::util
            VersionUtil["VersionUtil"]:::util
            Wrapper["Wrapper"]:::util
            ClassWrapper["ClassWrapper"]:::util
            FieldWrapper["FieldWrapper"]:::util
            MethodWrapper["MethodWrapper"]:::util
            CaesiumException["CaesiumException"]:::util
        end

        %% Configuration & Resources
        subgraph "Config & Resources"
            Properties["caesium.properties"]:::config
            LogConfig["log4j2.xml"]:::config
        end
    end

    %% External Libraries
    ASMExt["ASM Library"]:::external
    Log4jExt["Log4j2"]:::external

    %% Data Flow
    InputJar -->|select JAR| CGui
    CGui -->|launch mutate| Start
    Start --> PreRuntime
    PreRuntime --> Properties
    PreRuntime --> LogConfig
    PreRuntime --> CaesiumCore
    CaesiumCore --> ClassManager
    ClassManager --> ClassTree
    CaesiumCore --> MutatorManager
    MutatorManager --> ClassMutator
    ClassMutator --> AttributeMutator
    ClassMutator --> ControlFlowMutator
    ClassMutator --> StringMutator
    ClassMutator --> BadAnnotationMutator
    ClassMutator --> ImageCrashMutator

    %% Plugin usage of utilities
    AttributeMutator -->|uses| ClassTree
    ControlFlowMutator -->|uses| ASMUtil
    StringMutator -->|uses| ByteUtil
    BadAnnotationMutator -->|uses| Wrapper
    ImageCrashMutator -->|uses| OSUtil

    %% ClassWriter and ASM
    ClassTree --> CaesiumClassWriter
    CaesiumClassWriter --> ASMExt
    CaesiumClassWriter --> OutputJar

    %% Logging
    CaesiumCore --> Log4jExt

    %% Completion
    CaesiumCore -->|result| CGui
    CGui -->|display| OutputJar

    %% Click Events
    click CGui "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/gui/CGui.java"
    click LibraryTab "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/gui/LibraryTab.java"
    click Start "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/Start.java"
    click PreRuntime "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/PreRuntime.java"
    click CaesiumCore "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/Caesium.java"
    click ClassManager "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/manager/ClassManager.java"
    click MutatorManager "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/manager/MutatorManager.java"
    click ClassMutator "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/mutator/ClassMutator.java"
    click AttributeMutator "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/mutator/impl/AttributeMutator.java"
    click ControlFlowMutator "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/mutator/impl/ControlFlowMutator.java"
    click StringMutator "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/mutator/impl/StringMutator.java"
    click BadAnnotationMutator "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/mutator/impl/crasher/BadAnnotationMutator.java"
    click ImageCrashMutator "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/mutator/impl/crasher/ImageCrashMutator.java"
    click ASMUtil "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/ASMUtil.java"
    click CaesiumClassWriter "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/classwriter/CaesiumClassWriter.java"
    click ClassTree "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/classwriter/ClassTree.java"
    click ByteUtil "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/ByteUtil.java"
    click Dictionary "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/Dictionary.java"
    click OSUtil "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/OSUtil.java"
    click OS "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/OS.java"
    click StringUtil "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/StringUtil.java"
    click VersionUtil "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/VersionUtil.java"
    click Wrapper "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/wrapper/Wrapper.java"
    click ClassWrapper "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/wrapper/impl/ClassWrapper.java"
    click FieldWrapper "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/wrapper/impl/FieldWrapper.java"
    click MethodWrapper "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/util/wrapper/impl/MethodWrapper.java"
    click Properties "https://github.com/sim0n/caesium/blob/master/src/main/resources/caesium.properties"
    click LogConfig "https://github.com/sim0n/caesium/blob/master/src/main/resources/log4j2.xml"
    click CaesiumException "https://github.com/sim0n/caesium/blob/master/src/main/java/dev/sim0n/caesium/exception/CaesiumException.java"

    %% Styles
    classDef ui fill:#c2f0c2,stroke:#2d882d,color:#000
    classDef core fill:#c2dfff,stroke:#2d4f8d,color:#000
    classDef plugin fill:#ffd9b3,stroke:#b36400,color:#000
    classDef util fill:#e0e0e0,stroke:#7a7a7a,color:#000
    classDef config fill:#e6ccb3,stroke:#a66a00,color:#000
    classDef external fill:#ffcccc,stroke:#b30000,color:#000
    classDef io fill:#e5ccff,stroke:#5a009a,color:#000
```
