# tunguyen35/cyberchef architecture

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

- Interactive diagram: https://gitdiagram.com/tunguyen35/cyberchef
- Repository: https://github.com/tunguyen35/cyberchef

## Overview

CyberChef is a largely client-side data-processing application with one shared computation core and two thin presentation/runtime layers: a browser UI and a Node.js API/REPL. The central architectural idea is “input + recipe + operations = output,” where a recipe is an ordered pipeline of operations applied to typed data.

1. **Core engine**
   The `src/core` tree is the main subsystem. It defines the execution model for recipes, operations, ingredients, and dishes. This is the framework-agnostic layer that both the browser app and Node.js entrypoints reuse.

2. **Data model and execution pipeline**
   The core model is built around `Recipe`, `Operation`, `Ingredient`, `Dish`, and `Chef` classes. A recipe is the pipeline, operations are the individual transforms, ingredients are operation inputs/options, and dishes represent the typed intermediate/final data flowing through the pipeline.

3. **Typed data boundaries**
   `src/core/dishTypes` and `src/core/errors` define the boundary between raw values and operation-specific representations. CyberChef treats content as different dish types such as strings, numbers, JSON, byte arrays, files, HTML, and lists, with explicit errors when operations cannot run on the current type or are excluded.

4. **Operation library as plug-in surface**
   `src/core/operations` is the dominant content area: each `.mjs` file is a single operation implementation. These cover encoding/decoding, crypto, hashing, compression, parsers, formatters, image transforms, text utilities, and protocol/file analysis. This directory is the functional heart of the product and the main place where new capabilities are added.

5. **Shared helper libraries**
   `src/core/lib` contains reusable algorithmic modules used by many operations: bases and encodings, ciphers, hashes, binary/bitwise helpers, compression, date/time, file signatures, protocol parsers, QR/graphics utilities, and similar domain helpers. These are not UI concerns; they are the computational building blocks that operations compose.

6. **Browser application boundary**
   `src/web` is the interactive UI layer. It owns layout, controls, themes, static HTML, CSS, and the browser-facing orchestration code. The UI exposes the four main work areas from the README: input, output, operations list, and recipe editor.

7. **UI orchestration and state management**
   The web layer is split into components like `App`, `Manager`, `HTMLCategory`, `HTMLIngredient`, and `HTMLOperation`, plus “waiter” modules that coordinate UI regions such as input, output, recipe, controls, tabs, timing, and workers. This suggests a modular, event-driven UI where each region listens to shared application state rather than doing its own processing.

8. **Browser worker boundary**
   Heavy or asynchronous work is pushed into `src/web/workers` and coordinated by `src/web/waiters`. The worker layer includes input processing, dish processing, ZIP handling, and loader work. This separation keeps large file handling and expensive transforms off the main UI thread, which matters because CyberChef supports very large inputs.

9. **Node.js runtime boundary**
   `src/node` provides a programmatic API and REPL for running CyberChef outside the browser. Files like `NodeRecipe`, `NodeDish`, `api.mjs`, `apiUtils.mjs`, and `repl.mjs` adapt the shared core to server-side/scripted usage. The architecture here is an adapter layer over the same core engine, not a separate implementation.

10. **Excluded or environment-specific operations**
   `src/node/config/excludedOperations.mjs` indicates that not every operation is available in Node. This is an important boundary: some operations depend on browser-only APIs or UI capabilities, so the node runtime exposes a subset of the operation set.

11. **Build, packaging, and release flow**
   The repository uses webpack, Grunt, Babel, ESLint, PostCSS, and Docker. The app can be served as a static web application, built into a container, or published as the `cyberchef` package. GitHub Actions handle validation and release artifacts, including the prebuilt Docker image referenced in the README.

12. **Test architecture**
   Tests are split by surface area: browser tests under `tests/browser`, Node/API tests under `tests/node`, and operation-level tests under `tests/operations`. That mirrors the architecture itself and reinforces the main boundaries: UI behavior, runtime integration, and transformation correctness.

For an architecture diagram, the most important flow is:
browser input or Node input → recipe assembly → shared core execution → typed intermediate dishes → final output, with worker threads used for expensive processing in the browser and a separate Node adapter exposing the same core outside the UI.

Main entry points: [`src/node/api.mjs`](https://github.com/tunguyen35/cyberchef/blob/master/src/node/api.mjs) (Node API), [`src/core/operations`](https://github.com/tunguyen35/cyberchef/tree/master/src/core/operations) (Operations), [`src/core/Operation.mjs`](https://github.com/tunguyen35/cyberchef/blob/master/src/core/Operation.mjs) (Operation), [`src/web/App.mjs`](https://github.com/tunguyen35/cyberchef/blob/master/src/web/App.mjs) (App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core"]
  node_chef["Chef<br/>engine<br/>[Chef.mjs]"]
  node_recipe["Recipe<br/>pipeline<br/>[Recipe.mjs]"]
  node_operation["Operation<br/>transform<br/>[Operation.mjs]"]
  node_ingredient["Ingredient<br/>input model<br/>[Ingredient.mjs]"]
  node_dish["Dish<br/>typed data<br/>[Dish.mjs]"]
  node_dishtypes["Dish types<br/>type boundary<br/>[index.mjs]"]
  node_errors["Errors<br/>[index.mjs]"]
  node_lib["Core libs<br/>helpers"]
  node_ops["Operations<br/>plugin surface"]
end

subgraph group_web["Web"]
  node_app["App<br/>browser shell<br/>[App.mjs]"]
  node_manager["Manager<br/>ui coordinator<br/>[Manager.mjs]"]
  node_waiters["Waiters<br/>ui bindings"]
  node_workers["Workers<br/>background tasks"]
end

subgraph group_node["Node"]
  node_nodeapi["Node API<br/>runtime adapter<br/>[api.mjs]"]
  node_noderepl["REPL<br/>interactive shell<br/>[repl.mjs]"]
  node_noderecipe["NodeRecipe<br/>adapter<br/>[NodeRecipe.mjs]"]
  node_nodefile["File<br/>node IO<br/>[File.mjs]"]
end

subgraph group_build["Build"]
  node_buildtools["Build flow<br/>tooling"]
end

subgraph group_tests["Tests"]
  node_browsertests["Browser tests"]
  node_nodetests["Node tests"]
  node_optests["Op tests<br/>operation tests"]
end

node_chef -->|"runs"| node_recipe
node_recipe -->|"contains"| node_operation
node_operation -->|"uses"| node_ingredient
node_operation -->|"produces"| node_dish
node_dish -->|"constrained by"| node_dishtypes
node_operation -->|"fails with"| node_errors
node_ops -->|"depends on"| node_lib
node_ops -->|"accepts"| node_dishtypes
node_ops -->|"raises"| node_errors
node_app -->|"orchestrates"| node_manager
node_manager -->|"binds"| node_waiters
node_manager -->|"dispatches"| node_workers
node_workers -->|"executes"| node_chef
node_app -->|"loads"| node_ops
node_nodeapi -->|"wraps"| node_noderecipe
node_nodeapi -->|"reuses"| node_chef
node_noderepl -->|"drives"| node_nodeapi
node_nodefile -->|"feeds"| node_nodeapi
node_buildtools -->|"packages"| node_app
node_buildtools -->|"packages"| node_nodeapi
node_browsertests -->|"covers"| node_app
node_nodetests -->|"covers"| node_nodeapi
node_optests -->|"covers"| node_ops

click node_chef "https://github.com/tunguyen35/cyberchef/blob/master/src/core/Chef.mjs"
click node_recipe "https://github.com/tunguyen35/cyberchef/blob/master/src/core/Recipe.mjs"
click node_operation "https://github.com/tunguyen35/cyberchef/blob/master/src/core/Operation.mjs"
click node_ingredient "https://github.com/tunguyen35/cyberchef/blob/master/src/core/Ingredient.mjs"
click node_dish "https://github.com/tunguyen35/cyberchef/blob/master/src/core/Dish.mjs"
click node_dishtypes "https://github.com/tunguyen35/cyberchef/blob/master/src/core/dishTypes/index.mjs"
click node_errors "https://github.com/tunguyen35/cyberchef/blob/master/src/core/errors/index.mjs"
click node_lib "https://github.com/tunguyen35/cyberchef/tree/master/src/core/lib"
click node_ops "https://github.com/tunguyen35/cyberchef/tree/master/src/core/operations"
click node_app "https://github.com/tunguyen35/cyberchef/blob/master/src/web/App.mjs"
click node_manager "https://github.com/tunguyen35/cyberchef/blob/master/src/web/Manager.mjs"
click node_waiters "https://github.com/tunguyen35/cyberchef/tree/master/src/web/waiters"
click node_workers "https://github.com/tunguyen35/cyberchef/tree/master/src/web/workers"
click node_nodeapi "https://github.com/tunguyen35/cyberchef/blob/master/src/node/api.mjs"
click node_noderepl "https://github.com/tunguyen35/cyberchef/blob/master/src/node/repl.mjs"
click node_noderecipe "https://github.com/tunguyen35/cyberchef/blob/master/src/node/NodeRecipe.mjs"
click node_nodefile "https://github.com/tunguyen35/cyberchef/blob/master/src/node/File.mjs"
click node_browsertests "https://github.com/tunguyen35/cyberchef/tree/master/tests/browser"
click node_nodetests "https://github.com/tunguyen35/cyberchef/tree/master/tests/node"
click node_optests "https://github.com/tunguyen35/cyberchef/tree/master/tests/operations"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chef,node_recipe,node_operation,node_ingredient,node_dish,node_dishtypes,node_errors,node_lib,node_ops toneBlue
class node_app,node_manager,node_waiters,node_workers toneAmber
class node_nodeapi,node_noderepl,node_noderecipe,node_nodefile toneMint
class node_buildtools toneRose
class node_browsertests,node_nodetests,node_optests toneIndigo
```

## Components

### Core

Shared execution engine and operation library

- [Chef](https://github.com/tunguyen35/cyberchef/blob/master/src/core/Chef.mjs): engine · Top-level execution coordinator · `src/core/Chef.mjs`
- [Recipe](https://github.com/tunguyen35/cyberchef/blob/master/src/core/Recipe.mjs): pipeline · Ordered operation pipeline · `src/core/Recipe.mjs`
- [Operation](https://github.com/tunguyen35/cyberchef/blob/master/src/core/Operation.mjs): transform · Operation definition and metadata · `src/core/Operation.mjs`
- [Ingredient](https://github.com/tunguyen35/cyberchef/blob/master/src/core/Ingredient.mjs): input model · Operation inputs and options · `src/core/Ingredient.mjs`
- [Dish](https://github.com/tunguyen35/cyberchef/blob/master/src/core/Dish.mjs): typed data · Typed intermediate and final values · `src/core/Dish.mjs`
- [Dish types](https://github.com/tunguyen35/cyberchef/blob/master/src/core/dishTypes/index.mjs): type boundary · Typed boundaries for strings, bytes, JSON, files, lists, and more · `src/core/dishTypes/index.mjs`
- [Errors](https://github.com/tunguyen35/cyberchef/blob/master/src/core/errors/index.mjs): runtime errors · Operation and dish failure conditions · `src/core/errors/index.mjs`
- [Core libs](https://github.com/tunguyen35/cyberchef/tree/master/src/core/lib): helpers · Shared algorithms and parsers used by operations · `src/core/lib`
- [Operations](https://github.com/tunguyen35/cyberchef/tree/master/src/core/operations): plugin surface · Large library of transforms and analyzers · `src/core/operations`

### Web

Browser UI, workers, and orchestration

- [App](https://github.com/tunguyen35/cyberchef/blob/master/src/web/App.mjs): browser shell · Browser application bootstrap · `src/web/App.mjs`
- [Manager](https://github.com/tunguyen35/cyberchef/blob/master/src/web/Manager.mjs): ui coordinator · Coordinates shared UI state and regions · `src/web/Manager.mjs`
- [Waiters](https://github.com/tunguyen35/cyberchef/tree/master/src/web/waiters): ui bindings · Region-specific UI orchestration modules · `src/web/waiters`
- [Workers](https://github.com/tunguyen35/cyberchef/tree/master/src/web/workers): background tasks · Off-main-thread processing for heavy input and dishes · `src/web/workers`

### Node

Node.js API and REPL runtime

- [Node API](https://github.com/tunguyen35/cyberchef/blob/master/src/node/api.mjs): runtime adapter · Programmatic Node.js interface over the shared core · `src/node/api.mjs`
- [REPL](https://github.com/tunguyen35/cyberchef/blob/master/src/node/repl.mjs): interactive shell · Command-line interactive runtime · `src/node/repl.mjs`
- [NodeRecipe](https://github.com/tunguyen35/cyberchef/blob/master/src/node/NodeRecipe.mjs): adapter · Node-specific recipe wrapper · `src/node/NodeRecipe.mjs`
- [File](https://github.com/tunguyen35/cyberchef/blob/master/src/node/File.mjs): node IO · Node file abstraction used by the runtime · `src/node/File.mjs`

### Build

Packaging, release, and automation

- **Build flow**: tooling · Webpack, Grunt, Babel, ESLint, PostCSS, Docker, and release automation

### Tests

Validation across browser, node, and operations

- [Browser tests](https://github.com/tunguyen35/cyberchef/tree/master/tests/browser): browser tests · End-to-end UI and interaction checks · `tests/browser`
- [Node tests](https://github.com/tunguyen35/cyberchef/tree/master/tests/node): node tests · API and runtime integration checks · `tests/node`
- [Op tests](https://github.com/tunguyen35/cyberchef/tree/master/tests/operations): operation tests · Per-operation correctness coverage · `tests/operations`

## Connections

- Chef → Recipe: runs · Coordinates recipe execution
- Recipe → Operation: contains · An ordered list of transforms
- Operation → Ingredient: uses · Reads options and parameters
- Operation → Dish: produces · Transforms typed input into output
- Dish → Dish types: constrained by · Values move through explicit typed boundaries
- Operation → Errors: fails with · Rejected or invalid execution paths
- Operations → Core libs: depends on · Operations build on shared computational helpers
- Operations → Dish types: accepts · Operations specialize by input type
- Operations → Errors: raises · Operations surface domain and type errors
- App → Manager: orchestrates · Browser shell delegates UI state handling
- Manager → Waiters: binds · Event-driven region coordination
- Manager → Workers: dispatches · Hands off expensive work to background threads
- Workers → Chef: executes · Worker-side processing uses the shared engine
- App → Operations: loads · Browser UI presents operation library
- Node API → NodeRecipe: wraps · Node adapter exposes recipe execution
- Node API → Chef: reuses · Node runtime shares the core engine
- REPL → Node API: drives · Interactive shell sits on the API
- File → Node API: feeds · File abstraction supplies Node inputs
- Build flow → App: packages · Build pipeline produces the browser artifact
- Build flow → Node API: packages · Build pipeline also supports the Node distribution
- Browser tests → App: covers · Validates browser behavior
- Node tests → Node API: covers · Validates Node API and runtime behavior
- Op tests → Operations: covers · Checks transformation correctness
