# mercuryworkshop/scramjet architecture

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

- Interactive diagram: https://gitdiagram.com/mercuryworkshop/scramjet
- Repository: https://github.com/mercuryworkshop/scramjet

## Overview

Scramjet is an experimental browser-based web proxy for sandboxing and rewriting remote sites to bypass browser restrictions and censorship. The principal flow is bootstrap registration and setup, followed by controller-managed service-worker interception, proxy fetching, response rewriting, and execution in a sandboxed client. The repository also includes a Rust/JavaScript rewriter implementation and browser-management plugins. The README documents the overall interception, rewriting, and sandboxing design; several internal links below are therefore documented at subsystem level rather than verified from sampled runtime calls.

Main entry points: [`packages/core/src/fetch/fetch.ts`](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/fetch/fetch.ts) (Proxy fetch handler), [`packages/controller/src/index.ts`](https://github.com/mercuryworkshop/scramjet/blob/main/packages/controller/src/index.ts) (Controller and frames), [`packages/core/src/shared/rewriters`](https://github.com/mercuryworkshop/scramjet/tree/main/packages/core/src/shared/rewriters) (Content rewriters), [`packages/core/src/client/client.ts`](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/client/client.ts) (Sandbox client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Bootstrap and setup"]
  node_bootstrap_client["Bootstrap client<br/>[client.ts]"]
  node_bootstrap_sw["Service worker setup<br/>[clientcommon.ts]"]
  node_bootstrap_server["Bootstrap server<br/>[server.ts]"]
end

subgraph group_runtime["Proxy runtime"]
  node_controller["Controller and frames<br/>[index.ts]"]
  node_rpc["RPC helpers<br/>[index.ts]"]
  node_proxy_fetch["Proxy fetch handler<br/>[fetch.ts]"]
  node_fetch_parsing["Fetch parsing<br/>[parse.ts]"]
  node_transport["Proxy transport"]
  node_headers["HTTP headers<br/>[headers.ts]"]
end

subgraph group_rewrite["Rewriting and sandbox"]
  node_rewriters["Content rewriters"]
  node_html_rewriter["HTML rewriting<br/>[html.ts]"]
  node_js_rewriter["JavaScript rewriting<br/>[js.ts]"]
  node_wasm_rewriter["Wasm rewriting<br/>[wasm.ts]"]
  node_native_rewriter["Native rewriter<br/>[rewriter.rs]"]
  node_rewriter_analysis["Coverage analysis<br/>[analyze.rs]"]
  node_client["Sandbox client<br/>[client.ts]"]
  node_client_entry["Client entry<br/>[entry.ts]"]
  node_dom["DOM emulation"]
  node_shared_intercepts["Browser API interception"]
  node_sourcemaps["Source maps<br/>[sourcemaps.ts]"]
end

subgraph group_extensions["Browser extensions"]
  node_event_plugin["Event handler plugin"]
  node_bubble["Late event listeners"]
  node_link_plugin["Link handler plugin"]
end

node_user(("Site visitor"))
node_remote(("Remote website"))

node_user -.->|"starts proxy"| node_bootstrap_client
node_bootstrap_client -->|"registers worker"| node_bootstrap_sw
node_bootstrap_client -->|"creates controller"| node_controller
node_bootstrap_server -->|"serves bootstrap"| node_bootstrap_client
node_controller -->|"creates handler"| node_proxy_fetch
node_controller -->|"configures transport"| node_transport
node_controller -->|"uses RPC"| node_rpc
node_proxy_fetch -.->|"uses parsing"| node_fetch_parsing
node_proxy_fetch -.->|"handles headers"| node_headers
node_proxy_fetch -.->|"fetches remote content"| node_remote
node_proxy_fetch -.->|"rewrites responses"| node_rewriters
node_rewriters -.->|"includes"| node_html_rewriter
node_rewriters -.->|"includes"| node_js_rewriter
node_rewriters -.->|"includes"| node_wasm_rewriter
node_native_rewriter -.->|"analyzes coverage"| node_rewriter_analysis
node_client_entry -.->|"initializes"| node_client
node_client -.->|"emulates DOM"| node_dom
node_client -.->|"intercepts APIs"| node_shared_intercepts
node_client -->|"uses source maps"| node_sourcemaps
node_event_plugin -->|"sets up listeners"| node_bubble
node_link_plugin -->|"registers click handlers"| node_event_plugin

click node_bootstrap_client "https://github.com/mercuryworkshop/scramjet/blob/main/packages/bootstrap/src/client.ts"
click node_bootstrap_sw "https://github.com/mercuryworkshop/scramjet/blob/main/packages/bootstrap/src/clientcommon.ts"
click node_bootstrap_server "https://github.com/mercuryworkshop/scramjet/blob/main/packages/bootstrap/src/server.ts"
click node_controller "https://github.com/mercuryworkshop/scramjet/blob/main/packages/controller/src/index.ts"
click node_rpc "https://github.com/mercuryworkshop/scramjet/blob/main/packages/rpc/index.ts"
click node_proxy_fetch "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/fetch/fetch.ts"
click node_fetch_parsing "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/fetch/parse.ts"
click node_headers "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/fetch/headers.ts"
click node_rewriters "https://github.com/mercuryworkshop/scramjet/tree/main/packages/core/src/shared/rewriters"
click node_html_rewriter "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/shared/rewriters/html.ts"
click node_js_rewriter "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/shared/rewriters/js.ts"
click node_wasm_rewriter "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/shared/rewriters/wasm.ts"
click node_native_rewriter "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/rewriter/native/src/rewriter.rs"
click node_rewriter_analysis "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/rewriter/coverage-macro/src/analyze.rs"
click node_client "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/client/client.ts"
click node_client_entry "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/client/entry.ts"
click node_dom "https://github.com/mercuryworkshop/scramjet/tree/main/packages/core/src/client/dom"
click node_shared_intercepts "https://github.com/mercuryworkshop/scramjet/tree/main/packages/core/src/client/shared"
click node_sourcemaps "https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/client/shared/sourcemaps.ts"
click node_event_plugin "https://github.com/mercuryworkshop/scramjet/blob/main/packages/utils/src/event-handler-plugin.ts"
click node_bubble "https://github.com/mercuryworkshop/scramjet/blob/main/packages/utils/src/alwaysLastBubble.ts"
click node_link_plugin "https://github.com/mercuryworkshop/scramjet/blob/main/packages/utils/src/link-handler-plugin.ts"

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_bootstrap_client,node_bootstrap_sw,node_bootstrap_server toneBlue
class node_controller,node_rpc,node_proxy_fetch,node_fetch_parsing,node_transport,node_headers toneAmber
class node_rewriters,node_html_rewriter,node_js_rewriter,node_wasm_rewriter,node_native_rewriter,node_rewriter_analysis,node_client,node_client_entry,node_dom,node_shared_intercepts,node_sourcemaps toneMint
class node_event_plugin,node_bubble,node_link_plugin toneRose
class node_user,node_remote toneIndigo
```

## Components

### Bootstrap and setup

- [Bootstrap client](https://github.com/mercuryworkshop/scramjet/blob/main/packages/bootstrap/src/client.ts): `packages/bootstrap/src/client.ts`
- [Service worker setup](https://github.com/mercuryworkshop/scramjet/blob/main/packages/bootstrap/src/clientcommon.ts): `packages/bootstrap/src/clientcommon.ts`
- [Bootstrap server](https://github.com/mercuryworkshop/scramjet/blob/main/packages/bootstrap/src/server.ts): `packages/bootstrap/src/server.ts`

### Proxy runtime

- [Controller and frames](https://github.com/mercuryworkshop/scramjet/blob/main/packages/controller/src/index.ts): `packages/controller/src/index.ts`
- [RPC helpers](https://github.com/mercuryworkshop/scramjet/blob/main/packages/rpc/index.ts): `packages/rpc/index.ts`
- [Proxy fetch handler](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/fetch/fetch.ts): `packages/core/src/fetch/fetch.ts`
- [Fetch parsing](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/fetch/parse.ts): `packages/core/src/fetch/parse.ts`
- **Proxy transport**
- [HTTP headers](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/fetch/headers.ts): `packages/core/src/fetch/headers.ts`

### Rewriting and sandbox

- [Content rewriters](https://github.com/mercuryworkshop/scramjet/tree/main/packages/core/src/shared/rewriters): `packages/core/src/shared/rewriters`
- [HTML rewriting](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/shared/rewriters/html.ts): `packages/core/src/shared/rewriters/html.ts`
- [JavaScript rewriting](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/shared/rewriters/js.ts): `packages/core/src/shared/rewriters/js.ts`
- [Wasm rewriting](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/shared/rewriters/wasm.ts): `packages/core/src/shared/rewriters/wasm.ts`
- [Native rewriter](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/rewriter/native/src/rewriter.rs): `packages/core/rewriter/native/src/rewriter.rs`
- [Coverage analysis](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/rewriter/coverage-macro/src/analyze.rs): `packages/core/rewriter/coverage-macro/src/analyze.rs`
- [Sandbox client](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/client/client.ts): `packages/core/src/client/client.ts`
- [Client entry](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/client/entry.ts): `packages/core/src/client/entry.ts`
- [DOM emulation](https://github.com/mercuryworkshop/scramjet/tree/main/packages/core/src/client/dom): `packages/core/src/client/dom`
- [Browser API interception](https://github.com/mercuryworkshop/scramjet/tree/main/packages/core/src/client/shared): `packages/core/src/client/shared`
- [Source maps](https://github.com/mercuryworkshop/scramjet/blob/main/packages/core/src/client/shared/sourcemaps.ts): `packages/core/src/client/shared/sourcemaps.ts`

### Browser extensions

- [Event handler plugin](https://github.com/mercuryworkshop/scramjet/blob/main/packages/utils/src/event-handler-plugin.ts): `packages/utils/src/event-handler-plugin.ts`
- [Late event listeners](https://github.com/mercuryworkshop/scramjet/blob/main/packages/utils/src/alwaysLastBubble.ts): `packages/utils/src/alwaysLastBubble.ts`
- [Link handler plugin](https://github.com/mercuryworkshop/scramjet/blob/main/packages/utils/src/link-handler-plugin.ts): `packages/utils/src/link-handler-plugin.ts`

### Other components

- **Site visitor**
- **Remote website**

## Connections

- Site visitor → Bootstrap client: starts proxy
- Bootstrap client → Service worker setup: registers worker (evidence: `packages/bootstrap/src/client.ts`)
- Bootstrap client → Controller and frames: creates controller (evidence: `packages/bootstrap/src/client.ts`)
- Bootstrap server → Bootstrap client: serves bootstrap (evidence: `packages/bootstrap/src/server.ts`)
- Controller and frames → Proxy fetch handler: creates handler (evidence: `packages/controller/src/index.ts`)
- Controller and frames → Proxy transport: configures transport (evidence: `packages/controller/src/index.ts`)
- Controller and frames → RPC helpers: uses RPC (evidence: `packages/controller/src/index.ts`)
- Proxy fetch handler → Fetch parsing: uses parsing
- Proxy fetch handler → HTTP headers: handles headers
- Proxy fetch handler → Remote website: fetches remote content
- Proxy fetch handler → Content rewriters: rewrites responses
- Content rewriters → HTML rewriting: includes
- Content rewriters → JavaScript rewriting: includes
- Content rewriters → Wasm rewriting: includes
- Native rewriter → Coverage analysis: analyzes coverage
- Client entry → Sandbox client: initializes (evidence: `packages/core/src/client/client.ts`)
- Sandbox client → DOM emulation: emulates DOM
- Sandbox client → Browser API interception: intercepts APIs (evidence: `packages/core/src/client/client.ts`)
- Sandbox client → Source maps: uses source maps (evidence: `packages/core/src/client/singletonbox.ts`)
- Event handler plugin → Late event listeners: sets up listeners (evidence: `packages/utils/src/event-handler-plugin.ts`)
- Link handler plugin → Event handler plugin: registers click handlers (evidence: `packages/utils/src/link-handler-plugin.ts`)