How tunguyen35/cyberchef works
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: api.mjs Node API · operations Operations · Operation.mjs Operation · App.mjs App
Components 21
Core
Shared execution engine and operation library
- Chef · Top-level execution coordinator
src/core/Chef.mjs - Recipe · Ordered operation pipeline
src/core/Recipe.mjs - Operation · Operation definition and metadata
src/core/Operation.mjs - Ingredient · Operation inputs and options
src/core/Ingredient.mjs - Dish · Typed intermediate and final values
src/core/Dish.mjs - Dish types · Typed boundaries for strings, bytes, JSON, files, lists, and more
src/core/dishTypes/index.mjs - Errors · Operation and dish failure conditions
src/core/errors/index.mjs - Core libs · Shared algorithms and parsers used by operations
src/core/lib - Operations · Large library of transforms and analyzers
src/core/operations
Web
Browser UI, workers, and orchestration
Node
Node.js API and REPL runtime
- Node API · Programmatic Node.js interface over the shared core
src/node/api.mjs - REPL · Command-line interactive runtime
src/node/repl.mjs - NodeRecipe · Node-specific recipe wrapper
src/node/NodeRecipe.mjs - File · Node file abstraction used by the runtime
src/node/File.mjs
Build
Packaging, release, and automation
- Build flow · Webpack, Grunt, Babel, ESLint, PostCSS, Docker, and release automation
Tests
Validation across browser, node, and operations
- Browser tests · End-to-end UI and interaction checks
tests/browser - Node tests · API and runtime integration checks
tests/node - Op tests · Per-operation correctness coverage
tests/operations
Connections 23
- 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