# vintagelock/cyberchef architecture

> Architecture diagram of the GitHub repository vintagelock/cyberchef, 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/vintagelock/cyberchef
- Repository: https://github.com/vintagelock/cyberchef

## Overview

##### Project Type and Purpose
- CyberChef is an “all-in-one” web tool—a cyber Swiss Army knife—that allows users to perform a wide range of data transformations and “cyber” operations via the browser. It is designed as a client-side application (with a Node.js variant available) featuring a modular operations engine.

##### File Structure for Key Components
- Core Engine – Under src/core you see modules for “Chef” (the engine), “ChefWorker”, “Dish”, “Recipe”, “Operation”, and many supporting libraries (in lib and dishTypes) as well as error handling and configuration. This layer is responsible for executing the operations (transformations, encoding/decoding, etc.) defined in independent modules.
- Operations Modules – A huge collection of files under src/core/operations represent each individual operation (or transformation) CyberChef supports (e.g., AESDecrypt, Base64 operations, etc.). These clearly need to be treated as modular plugins/components.
- Web UI – Under src/web you have the entire front-end including the App, HTML components (HTMLCategory, HTMLIngredient, HTMLOperation, Manager), and styling (CSS files), along with workers and waiters that help manage asynchronous operations and UI interaction.
- Node.js API – Under src/node, the files (like NodeDish, NodeRecipe, api.mjs, and wrapper.js) implement a Node.js interface, showing the project’s backend support for CLI or programmatic transformation.
- Testing and Build/Dev Infrastructure – The tests folder (with browser tests, Node tests, operation-specific tests) and build/configuration files (Gruntfile, webpack.config.js, package.json) indicate a robust testing and build/deployment lifecycle.

##### Main Components
a. UI/Web Layer:
- UI Utilities, waiters, and web workers (src/web/waiters, src/web/workers) manage asynchronous tasks and front-end responsiveness.
b. Core Processing Engine:
- At the heart of CyberChef is its core processing engine (src/core/Chef, ChefWorker, Recipe, Operation).
- Modular “operations” (each operation module under src/core/operations) plug into the engine.
- Supporting libraries (src/core/lib) and dish type implementations (src/core/dishTypes) support data type-specific logic.
c. Node.js API Layer:
- The Node.js wrapper (src/node/api, NodeDish, NodeRecipe) exposes the processing functionalities outside the browser.
- This module integrates with the core engine much like the web UI does.
d. Configuration & Extensibility:
- Configuration files and scripts (src/core/config and src/node/config) provide setups, script generators, and version bumping utilities.
- Build and deployment pipelines visible in the GitHub workflow files and Gruntfile.js.

##### Relationships and Data Flow
- The UI (client-side) captures user input and drag-and-drop operations. It then sends the recipe and data to the core engine.
- The core engine loads and executes the sequence of modular operations. Each operation processes data and passes results to subsequent operations in a “recipe.”
- Additionally, the Node.js API acts as a headless wrapper to the same core engine, enabling scripted or command-line-based transformation.
- Interactions between modules (e.g., Chef & Operation, and dish types within operations) are critical and should be illustrated as fluid and chain-like.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Clearly delineate layers for UI, processing core, and Node.js API.
- Asynchronous & Worker-Based Processing: Highlight the use of web workers (src/web/workers) that offload processing from the UI thread.

##### Extra Elements
- Don’t forget to mark the configuration scripts (in src/core/config and src/node/config/scripts) as support utilities that feed into the system assembly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Config["Web Config & Extensibility Scripts"]:::config
    Test["Testing & Build/Dev Infrastructure"]:::test
    UI["Web UI (Input,Operations,Recipe,Output)"]:::ui
    Core["Core Processing Engine (Chef)"]:::core
    Ops["Operations Modules (Plugins)"]:::plugin
    Node["Node.js API Layer"]:::node

    Config -->|"sets_up"| Core
    Config -->|"configures"| Node
    Test -->|"validates"| UI
    Test -->|"tests_engine"| Core
    UI -->|"sends_recipe"| Core
    Core -->|"invokes_ops"| Ops
    Ops -->|"returns_result"| Core
    Core -->|"outputs_data"| UI
    Node -->|"invokes_engine"| Core

    click UI "https://github.com/vintagelock/cyberchef/tree/master/src/web"
    click Core "https://github.com/vintagelock/cyberchef/tree/master/src/core"
    click Ops "https://github.com/vintagelock/cyberchef/tree/master/src/core/operations"
    click Node "https://github.com/vintagelock/cyberchef/tree/master/src/node"
    click Config "https://github.com/vintagelock/cyberchef/tree/master/src/core/config"
    click Test "https://github.com/vintagelock/cyberchef/tree/master/tests"

    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef plugin fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef node fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef test fill:#FFA07A,stroke:#000,stroke-width:2px;
```
