# guardsquare/proguard architecture

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

- Interactive diagram: https://gitdiagram.com/guardsquare/proguard
- Repository: https://github.com/guardsquare/proguard

## Overview

##### Main Components
- Core Engine (Base):
– This is the heart of ProGuard, located in the “base” module. It contains the main logic: configuration parsing, processing the bytecode, and executing various tasks. It is further segmented into packages for obfuscation, optimization, shrinking, backporting, and even specialized code handling (e.g., Kotlin optimizations).
- Annotations Module:
– Provides custom annotations (like Keep, KeepPublic, etc.) to control obfuscation behavior. These annotations tie into the core engine’s processing.
- Build Tool Integrations:
– Gradle Plugin: Found under “gradle-plugin”, this module integrates ProGuard with Gradle builds, providing a task (ProGuardTask) and associated configuration handling.
– Ant Integration: The “ant” module contains tasks and classes to enable ProGuard runs from Apache Ant builds.
- Frontend/User Interfaces:
– Command-line Interface: The “bin” directory has scripts (proguard.sh, proguard.bat, etc.) that launch the command-line version of ProGuard.
– Graphical User Interface (GUI): The “gui” module provides the Swing-based interface for users to interact with ProGuard visually.
– Retrace Tool: In the “retrace” module, there is functionality to de-obfuscate stack traces, mapping them back to original code.
- Documentation & Examples:
– “docs” and “examples” directories provide the user manual, configuration instructions, and sample projects demonstrating use in different environments (Android, standalone, Gradle, etc.).

##### Relationships and Interactions
- The frontends (CLI, GUI, Gradle Plugin, Ant tasks) act as entry points for users. They feed configuration files and options into the core engine (base module).
- The core engine processes input (the bytecode, configuration files) using its integrated modules (for obfuscation, shrinking, optimization, and preverification).
- The annotations module provides metadata that the core engine reads during processing to retain or discard classes/members.
- The retrace tool takes obfuscated stack traces (output from the core engine during an error scenario) and maps them back to the original code symbols.
- Integration modules abstract environment-specific adjustments (for Android projects, Java 8 setups, etc.) and convert build system inputs to standard core functionality.

##### Architectural Patterns and Design Principles
- Modular Design: The project is organized into clearly defined modules (base, gui, gradle-plugin, ant, retrace) that communicate with the core engine.
- Separation of Concerns: Frontend interfaces, integration plugins, and core processing logic are segmented to ensure each component handles a dedicated responsibility.
- Configurable Pipeline: The system makes heavy use of configuration files (standard .pro files) that control various stages (shrinking, obfuscation, optimization) of the bytecode processing.
- Extensibility: With its annotation-based configuration and various integration points, the project supports extensibility (e.g., additional plugins or support for new build systems).

##### Relevant Technologies and Frameworks
- Language: Java (requiring a Java 8 JDK for building).
- Build Tools: Gradle (primary build system), Ant (also supported), along with scripts for cross-platform command-line operation.
- UI Framework: Swing is used for the GUI.
- Dependency & Integration Management: Modules such as the gradle-plugin ensure integration with user builds via Gradle’s DSL.
- Documentation tooling: Markdown documents in the “docs” directory along with MkDocs configuration.

##### Specific Elements
- Clear Labels: Clearly mark the modules (Base, Annotations, GUI, Gradle Plugin, Ant, Retrace, and Command-line).
- Interaction Flow: Map out the sequence from user configuration (via scripts or plugins) → core processing (using obfuscation, shrinking, etc.) → final outputs (optimized bytecode, retrace logs).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Integration Frontends
    subgraph "Integration Frontends"
        CLI["Command-line Interface"]:::integration
        GUI["Graphical User Interface"]:::integration
        Gradle["Gradle Plugin"]:::integration
        Ant["Ant Integration"]:::integration
    end

    %% Core Processing Engine
    subgraph "Core Processing Engine"
        Core["Core Engine (Base)"]:::core
    end

    %% Utility Modules
    subgraph "Utility Modules"
        Annotations["Annotations Module"]:::utility
        Retrace["Retrace Tool"]:::utility
    end

    %% Documentation and Examples
    subgraph "Documentation and Examples"
        Docs["Documentation"]:::docs
        Examples["Examples"]:::docs
    end

    %% Connections from Integration Frontends to Core Engine
    CLI -->|"feedsConfig"| Core
    GUI -->|"feedsConfig"| Core
    Gradle -->|"buildConfig"| Core
    Ant -->|"buildConfig"| Core

    %% Annotation metadata flows into Core Engine
    Annotations -->|"providesMetadata"| Core

    %% Core Engine outputs to Retrace Tool (for symbol mapping)
    Core -->|"obfuscatedOutput"| Retrace

    %% Documentation guides configuration and usage
    Docs -->|"configGuide"| Core
    Examples -->|"sampleUsage"| Core

    %% Click Events
    click Core "https://github.com/guardsquare/proguard/tree/master/base"
    click Annotations "https://github.com/guardsquare/proguard/blob/master/annotations/src/main/java/proguard/annotation/Keep.java"
    click Gradle "https://github.com/guardsquare/proguard/blob/master/gradle-plugin/src/main/kotlin/proguard/gradle/plugin/ProGuardPlugin.kt"
    click Ant "https://github.com/guardsquare/proguard/blob/master/ant/src/main/java/proguard/ant/ProGuardTask.java"
    click CLI "https://github.com/guardsquare/proguard/tree/master/bin"
    click GUI "https://github.com/guardsquare/proguard/blob/master/gui/src/main/java/proguard/gui/ProGuardGUI.java"
    click Retrace "https://github.com/guardsquare/proguard/blob/master/retrace/src/main/java/proguard/retrace/ReTrace.java"
    click Docs "https://github.com/guardsquare/proguard/blob/master/docs/md/index.md"

    %% Styles
    classDef integration fill:#AEE6FF,stroke:#0277BD,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef utility fill:#FFECB3,stroke:#F57F17,stroke-width:2px;
    classDef docs fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;
```
