# 1inch/profanity2 architecture

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

- Interactive diagram: https://gitdiagram.com/1inch/profanity2
- Repository: https://github.com/1inch/profanity2

## Overview

- Command‐Line Interface (CLI) & Argument Parsing:
– Files like ArgParser.hpp, help.hpp, and the usage information in the README indicate that the tool is driven by a CLI.
– Represent a “CLI / User Input” component which parses parameters such as the seed public key (-z) and mode flags like --leading, --benchmark, etc.

- Mode Selection and Core Logic:
– Files such as Mode.cpp/hpp and SpeedSample.cpp/hpp suggest that the core logic of selecting various scoring or matching modes is compartmentalized.

- GPU Compute Engine Using OpenCL:
– The presence of keccak.cl and profanity.cl files, along with CLMemory.hpp, emphasizes a dedicated kernel layer for GPU processing.
– Create a “GPU Compute Engine” block that highlights:
◦ OpenCL Kernel Management: Handles loading and executing kernels (e.g., keccak, the “profanity” kernel).
◦ Memory Management for OpenCL (managed by CLMemory.hpp, possibly interfacing with Dispatcher).

- Task Dispatch and Kernel Management:
– Dispatcher.cpp/hpp indicate a module responsible for dispatching tasks to GPU devices.
– Represent a “Dispatcher” or “Task Scheduler” that controls workload distribution across available GPU devices.

- Precomputation / Setup:
– Files like precomp.cpp/hpp suggest the presence of a module for precompiling or preparing certain computation aspects.
– Include a small block for any “Kernel Pre-compilation / Setup” that is necessary before the GPU workloads commence.

- Auxiliary and Utility Components:
– Utility headers such as lexical_cast.hpp, types.hpp, and possibly helper modules are supportive but contribute to overall system robustness.
– Optionally include a “Utilities” section that encapsulates these functions.

##### Relationship and Interactions
- The argument parser (via ArgParser.hpp) processes the input and sets appropriate flags, which determines the operational mode.
- The Core Mode Logic receives these parameters, invoking the correct mode (e.g., --leading, --benchmark).
- The Dispatcher then manages the distribution of computation tasks to appropriate GPU devices.
- The GPU Compute Engine (with its OpenCL kernels and memory management) performs high performance hash calculations.
- Data flow back from the GPU layer to the dispatcher for results, which then return output to the CLI.

##### Important Architectural Choices
- Separation between the user input / control layer and the performance-critical GPU computation layer.
- Point out the use of OpenCL as the technology that enables the performance boost on various hardware (as noted by benchmarks).
- That a dispatcher pattern is being used to handle parallel tasks on the GPU, ensuring both scalability and "safety by design".

##### Relevant Technologies and Frameworks
- OpenCL (for the GPU kernels in keccak.cl and profanity.cl).
- The use of C++ (given the .cpp and .hpp files) with a modular design separating modes, dispatching, precomputation, and input handling.
- Cite that performance tuning is a key aspect (e.g., work sizes and inverse calculations are configurable by parameters).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface / CLI Layer
    subgraph "User Interface / CLI Layer"
        CLI["CLI / User Input"]:::frontend
    end

    %% Core Logic Layer
    subgraph "Core Logic Layer"
        MODE["Mode Selector"]:::core
    end

    %% Task Management Layer
    subgraph "Task Management Layer"
        DISP["Dispatcher"]:::core
    end

    %% GPU Compute Layer
    subgraph "GPU Compute Layer"
        PRE["Precomputation Setup"]:::backend
        GPU["GPU Engine (OpenCL)"]:::backend
    end

    %% Utility Components
    subgraph "Utility Components"
        UTIL["Utilities"]:::utility
    end

    %% Data Flow Connections
    CLI -->|"parseInput"| MODE
    MODE -->|"determineMode"| DISP
    PRE -->|"prepareKernels"| GPU
    DISP -->|"dispatchTasks"| GPU
    GPU -->|"returnResults"| DISP
    DISP -->|"processOutput"| CLI

    %% Optional Utility Usage (dashed connections)
    MODE ---|"uses"| UTIL
    DISP ---|"uses"| UTIL
    GPU ---|"uses"| UTIL

    %% Click Events for CLI & Argument Parsing
    click CLI "https://github.com/1inch/profanity2/blob/master/ArgParser.hpp"
    click CLI "https://github.com/1inch/profanity2/blob/master/help.hpp"
    click CLI "https://github.com/1inch/profanity2/blob/master/README.md"

    %% Click Events for Mode Selection and Core Logic
    click MODE "https://github.com/1inch/profanity2/blob/master/Mode.cpp"
    click MODE "https://github.com/1inch/profanity2/blob/master/Mode.hpp"
    click MODE "https://github.com/1inch/profanity2/blob/master/SpeedSample.cpp"
    click MODE "https://github.com/1inch/profanity2/blob/master/SpeedSample.hpp"

    %% Click Events for GPU Compute Engine Using OpenCL
    click GPU "https://github.com/1inch/profanity2/blob/master/keccak.cl"
    click GPU "https://github.com/1inch/profanity2/blob/master/profanity.cl"
    click GPU "https://github.com/1inch/profanity2/blob/master/CLMemory.hpp"

    %% Click Events for Task Dispatch and Kernel Management
    click DISP "https://github.com/1inch/profanity2/blob/master/Dispatcher.cpp"
    click DISP "https://github.com/1inch/profanity2/blob/master/Dispatcher.hpp"

    %% Click Events for Precomputation / Setup
    click PRE "https://github.com/1inch/profanity2/blob/master/precomp.cpp"
    click PRE "https://github.com/1inch/profanity2/blob/master/precomp.hpp"

    %% Click Events for Auxiliary and Utility Components
    click UTIL "https://github.com/1inch/profanity2/blob/master/lexical_cast.hpp"
    click UTIL "https://github.com/1inch/profanity2/blob/master/types.hpp"

    %% Styling for different layers
    classDef frontend fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef backend fill:#ccccff,stroke:#000099,stroke-width:2px;
    classDef utility fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
```
