# titaniumnetwork-dev/ultraviolet architecture

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

- Interactive diagram: https://gitdiagram.com/titaniumnetwork-dev/ultraviolet
- Repository: https://github.com/titaniumnetwork-dev/ultraviolet

## Overview

Ultraviolet is a browser-side web proxy for accessing remote sites through a controlled sandbox. The documented flow is browser requests intercepted by a service worker, then proxy handling and response rewriting before content reaches the browser. The client layer adapts DOM, URL, storage, worker, and network APIs; the rewrite layer covers HTML, CSS, JavaScript, URLs, and cookies. The README establishes service-worker interception, while some handler and service-worker wiring is not visible in excerpts, so those links are marked unverified.

Main entry points: [`src/rewrite/index.js`](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/index.js) (Rewrite engine), [`src/client/index.js`](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/index.js) (Client setup), [`src/uv.handler.js`](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/uv.handler.js) (Proxy handler), [`src/sw.js`](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/sw.js) (Service worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_proxy["Proxy runtime"]
  node_sw["Service worker<br/>[sw.js]"]
  node_sw_runtime["Worker runtime<br/>[uv.sw.js]"]
  node_request_handler["Proxy handler<br/>[uv.handler.js]"]
end

subgraph group_rewrite["Content rewriting"]
  node_rewriter["Rewrite engine<br/>[index.js]"]
  node_html_rewrite["HTML rewrite<br/>[html.js]"]
  node_html_rules["HTML rules<br/>[rewrite.html.js]"]
  node_script_rules["Script rules<br/>[rewrite.script.js]"]
  node_css_rewrite["CSS rewrite<br/>[css.js]"]
  node_js_rewrite["JavaScript rewrite<br/>[js.js]"]
  node_url_cookie_codec["URL and cookie codecs<br/>[codecs.js]"]
end

subgraph group_client["Browser client"]
  node_client_core["Client setup<br/>[index.js]"]
  node_network["Network adapters"]
  node_worker_hooks["Worker adapters<br/>[worker.js]"]
  node_dom_hooks["DOM adapters"]
  node_location_hooks["Location and history<br/>[location.js]"]
  node_storage_hooks["Storage adapters<br/>[storage.js]"]
end

subgraph group_hooks["Client hooks"]
  node_hook_event["Interception event<br/>[hook.js]"]
end

node_browser(("Browser"))
node_remote_site(("Remote site"))
node_bare_mux["Bare mux"]

node_browser -->|"sends requests"| node_sw
node_sw -.->|"dispatches to"| node_sw_runtime
node_sw_runtime -.->|"routes requests"| node_request_handler
node_request_handler -.->|"fetches content"| node_remote_site
node_request_handler -.->|"rewrites responses"| node_rewriter
node_rewriter -->|"uses parser"| node_html_rewrite
node_rewriter -->|"uses"| node_css_rewrite
node_rewriter -->|"uses"| node_js_rewrite
node_rewriter -->|"registers rules"| node_html_rules
node_rewriter -->|"registers rules"| node_script_rules
node_rewriter -->|"uses codecs"| node_url_cookie_codec
node_browser -.->|"runs client hooks"| node_client_core
node_client_core -->|"initializes adapters"| node_network
node_client_core -->|"initializes adapters"| node_dom_hooks
node_client_core -->|"initializes adapters"| node_location_hooks
node_client_core -.->|"initializes adapters"| node_storage_hooks
node_client_core -.->|"initializes adapter"| node_worker_hooks
node_dom_hooks -->|"emits events"| node_hook_event
node_storage_hooks -->|"creates events"| node_hook_event
node_worker_hooks -->|"creates connection"| node_bare_mux
node_network -.->|"uses transport"| node_bare_mux

click node_sw "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/sw.js"
click node_sw_runtime "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/uv.sw.js"
click node_request_handler "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/uv.handler.js"
click node_rewriter "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/index.js"
click node_html_rewrite "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/html.js"
click node_html_rules "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/rewrite.html.js"
click node_script_rules "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/rewrite.script.js"
click node_css_rewrite "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/css.js"
click node_js_rewrite "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/js.js"
click node_url_cookie_codec "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/codecs.js"
click node_client_core "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/index.js"
click node_network "https://github.com/titaniumnetwork-dev/ultraviolet/tree/main/src/client/requests"
click node_worker_hooks "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/worker.js"
click node_dom_hooks "https://github.com/titaniumnetwork-dev/ultraviolet/tree/main/src/client/dom"
click node_location_hooks "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/location.js"
click node_storage_hooks "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/storage.js"
click node_hook_event "https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/hook.js"

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_sw,node_sw_runtime,node_request_handler,node_browser toneBlue
class node_rewriter,node_html_rewrite,node_html_rules,node_script_rules,node_css_rewrite,node_js_rewrite,node_url_cookie_codec toneAmber
class node_client_core,node_network,node_worker_hooks,node_dom_hooks,node_location_hooks,node_storage_hooks toneMint
class node_hook_event toneRose
class node_remote_site,node_bare_mux toneIndigo
```

## Components

### Proxy runtime

- [Service worker](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/sw.js): `src/sw.js`
- [Worker runtime](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/uv.sw.js): `src/uv.sw.js`
- [Proxy handler](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/uv.handler.js): `src/uv.handler.js`

### Content rewriting

- [Rewrite engine](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/index.js): `src/rewrite/index.js`
- [HTML rewrite](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/html.js): `src/rewrite/html.js`
- [HTML rules](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/rewrite.html.js): `src/rewrite/rewrite.html.js`
- [Script rules](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/rewrite.script.js): `src/rewrite/rewrite.script.js`
- [CSS rewrite](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/css.js): `src/rewrite/css.js`
- [JavaScript rewrite](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/js.js): `src/rewrite/js.js`
- [URL and cookie codecs](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/rewrite/codecs.js): `src/rewrite/codecs.js`

### Browser client

- [Client setup](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/index.js): `src/client/index.js`
- [Network adapters](https://github.com/titaniumnetwork-dev/ultraviolet/tree/main/src/client/requests): `src/client/requests`
- [Worker adapters](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/worker.js): `src/client/worker.js`
- [DOM adapters](https://github.com/titaniumnetwork-dev/ultraviolet/tree/main/src/client/dom): `src/client/dom`
- [Location and history](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/location.js): `src/client/location.js`
- [Storage adapters](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/storage.js): `src/client/storage.js`

### Client hooks

- [Interception event](https://github.com/titaniumnetwork-dev/ultraviolet/blob/main/src/client/hook.js): `src/client/hook.js`

### Other components

- **Browser**
- **Remote site**
- **Bare mux**

## Connections

- Browser → Service worker: sends requests (evidence: `README.md`)
- Service worker → Worker runtime: dispatches to
- Worker runtime → Proxy handler: routes requests
- Proxy handler → Remote site: fetches content
- Proxy handler → Rewrite engine: rewrites responses
- Rewrite engine → HTML rewrite: uses parser (evidence: `src/rewrite/index.js`)
- Rewrite engine → CSS rewrite: uses (evidence: `src/rewrite/index.js`)
- Rewrite engine → JavaScript rewrite: uses (evidence: `src/rewrite/index.js`)
- Rewrite engine → HTML rules: registers rules (evidence: `src/rewrite/index.js`)
- Rewrite engine → Script rules: registers rules (evidence: `src/rewrite/index.js`)
- Rewrite engine → URL and cookie codecs: uses codecs (evidence: `src/rewrite/index.js`)
- Browser → Client setup: runs client hooks
- Client setup → Network adapters: initializes adapters (evidence: `src/client/index.js`)
- Client setup → DOM adapters: initializes adapters (evidence: `src/client/index.js`)
- Client setup → Location and history: initializes adapters (evidence: `src/client/index.js`)
- Client setup → Storage adapters: initializes adapters (evidence: `src/client/index.js`)
- Client setup → Worker adapters: initializes adapter (evidence: `src/client/index.js`)
- DOM adapters → Interception event: emits events (evidence: `src/client/dom/document.js`)
- Storage adapters → Interception event: creates events (evidence: `src/client/storage.js`)
- Worker adapters → Bare mux: creates connection (evidence: `src/client/worker.js`)
- Network adapters → Bare mux: uses transport
