# enniuu/waves architecture

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

- Interactive diagram: https://gitdiagram.com/enniuu/waves
- Repository: https://github.com/enniuu/waves

## Overview

1. **Overall shape**
   - This repo is a browser-based web proxy called **waves!!**.
   - It is split into three main execution zones: a **TypeScript/React browser UI**, a **service-worker-based proxy/interception layer**, and several **Rust services/crates** that handle proxy transport and cloud sync.

2. **Frontend application**
   - The `src/assets/scripts` tree is the main UI app, built with **React + TypeScript + Vite**.
   - `App.tsx` and the components under `components/` render the proxy’s user-facing surfaces: bookmarks, games, settings, navigation, search, sidebar/top bar, and toast notifications.
   - `state/store.ts` and the `core/` modules provide client state, config, history, iframe management, registration/loading, and shared UI signals.

3. **Client-side proxy boundary**
   - `src/b/sw.js` and the files under `src/b/sw/` form a **service worker proxy layer**.
   - This layer intercepts browser requests, rewrites network traffic, injects scripts, applies adblock logic, decodes/re-encodes content, and coordinates messaging/state with the UI.
   - This is the critical boundary between the browser and the proxied web: the UI talks to the service worker, and the service worker owns request interception.

4. **Proxy runtime assets**
   - `public/b/...` contains prebuilt runtime artifacts, including JS bundles and a WASM file (`jetty.wasm.wasm`).
   - These assets are likely shipped to the browser as part of the proxy engine/runtime, so the client can execute some proxy logic locally and efficiently.

5. **Rust proxy services**
   - The Rust crates appear to split the server-side networking responsibilities:
     - **`mochi`**: proxy/content-handling logic, with modules for cache, encoding, rewrite, websocket support, state, and tuning.
     - **`nuru`**: lower-level listener/route/upgrade handling and streaming stats, with support for websocket proxying and a `wisp` protocol family.
   - Architecturally, these crates likely sit behind or alongside the client-side proxy layer to manage transport, upgrades, rewriting, and streaming connection state.

6. **Content transformation and transport**
   - In `mochi`, the presence of `rewrite.rs`, `encoding.rs`, `cache.rs`, `websocket.rs`, and `proxy.rs` indicates a pipeline that:
     - receives proxied requests,
     - rewrites responses/resources for browser compatibility,
     - handles websocket traffic,
     - and caches reusable content.
   - In `nuru`, `handle/wisp/`, `wsproxy.rs`, `upgrade.rs`, and `stream.rs` suggest connection upgrade handling and websocket-based proxy transport, with routing/statistics around those streams.

7. **Cloud sync subsystem**
   - The `cloudsync` crate is a separate service for synchronizing user data.
   - Its `auth.rs`, `db.rs`, and `sync.rs` modules indicate a classic backend split: authenticate users, persist data, and reconcile synced state.
   - Per the README, this sync layer covers **games data, browsing data, settings, and other client state**.

8. **Feature-level data flow**
   - The frontend feature modules under `features/` connect the UI to the underlying systems:
     - `cloudsync.ts` talks to the sync service.
     - `games.ts` powers the games catalog/launcher UI.
     - `settings.ts` manages local configuration and syncable preferences.
     - `toast.ts` provides user feedback.
   - Search and discovery flow through `search/search.ts` and the relevant UI components.

9. **Request lifecycle**
   - A typical request flow is: browser UI action → service worker intercepts or rewrites the request → proxy runtime handles transport/rewriting/caching → remote origin is fetched → transformed response is returned to the browser.
   - Separate from browsing traffic, cloud-sync traffic goes from the UI to the `cloudsync` service to persist or restore user state.

10. **Build and delivery**
   - The project mixes **Node/Vite** tooling for the frontend with **Cargo** builds for the Rust services.
   - `build.js`, `setup.sh`, `index.mjs`, and `others/patch.js` are repository-level automation/helpers, while the runtime-facing build output is split between the frontend bundle and the Rust binaries.
   - This means deployment likely involves both static assets and backend services rather than a single monolith.

11. **External dependencies that matter architecturally**
   - The README credits multiple game sources, which explains why the games subsystem is an aggregator rather than a single curated catalog.
   - The project also references upstream proxy technologies and WASM-based components, indicating a layered architecture: browser runtime + proxy engine + Rust transport/services.

12. **Diagram takeaway**
   - If you draw this repo, place **the browser UI and service worker on one side**, **the proxy runtimes (`mochi`/`nuru`) in the middle**, and **`cloudsync` as a separate state backend**.
   - The central concept is that the browser never talks directly to the origin web in the normal way; it talks through the proxy boundary, while user state can optionally be persisted through cloud sync.

Main entry points: [`build.js`](https://github.com/enniuu/waves/blob/prod/build.js) (Build Tools), [`src/b/sw.js`](https://github.com/enniuu/waves/blob/prod/src/b/sw.js) (SW Proxy), [`src/assets/scripts/features`](https://github.com/enniuu/waves/tree/prod/src/assets/scripts/features) (Features), [`src/assets/scripts/App.tsx`](https://github.com/enniuu/waves/blob/prod/src/assets/scripts/App.tsx) (App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser UI"]
  node_app["App<br/>React shell<br/>[App.tsx]"]
  node_ui_components["UI Panels<br/>React components"]
  node_ui_state["UI State<br/>store/config<br/>[store.ts]"]
  node_ui_core["Core Logic<br/>client core"]
  node_features["Features<br/>feature modules"]
  node_search["Search<br/>[search.ts]"]
  node_service_worker["SW Proxy<br/>intercept layer<br/>[sw.js]"]
  node_sw_network["Network<br/>request rewrite<br/>[network.js]"]
  node_sw_transform["Transform<br/>adblock/decode/inject<br/>[handler.js]"]
  node_sw_state["SW State<br/>messaging/state<br/>[state.js]"]
  node_sw_utils["SW Utils<br/>helpers<br/>[utils.js]"]
end

subgraph group_runtime["Proxy Runtime"]
  node_jetty_assets[("Jetty Assets<br/>runtime bundle<br/>[jetty.wasm.wasm]")]
end

subgraph group_rust["Rust Services"]
  node_mochi["Mochi<br/>proxy engine<br/>[main.rs]"]
  node_mochi_pipeline["Content Pipeline<br/>rewrite/cache/encode<br/>[rewrite.rs]"]
  node_mochi_ws["WebSocket<br/>ws handling<br/>[websocket.rs]"]
  node_nuru["Nuru<br/>transport service<br/>[main.rs]"]
  node_nuru_wisp["Wisp Handlers<br/>ws/upgrade protocol<br/>[mod.rs]"]
  node_nuru_stream["Stream State<br/>routing/stats<br/>[stream.rs]"]
  node_cloudsync["Cloud Sync<br/>sync service<br/>[main.rs]"]
  node_cloudsync_data["Sync Data<br/>auth/db/sync<br/>[sync.rs]"]
end

subgraph group_build["Build & Delivery"]
  node_build_tools["Build Tools<br/>repo automation<br/>[build.js]"]
end

node_app -->|"renders"| node_ui_components
node_app -->|"binds"| node_ui_state
node_ui_components -->|"uses"| node_features
node_ui_core -->|"coordinates"| node_ui_state
node_features -->|"searches"| node_search
node_features -->|"syncs"| node_cloudsync
node_service_worker -->|"intercepts"| node_sw_network
node_service_worker -->|"rewrites"| node_sw_transform
node_service_worker -->|"syncs"| node_sw_state
node_sw_network -->|"loads"| node_jetty_assets
node_sw_transform -->|"executes"| node_jetty_assets
node_sw_state -->|"mirrors"| node_ui_state
node_sw_utils -->|"supports"| node_sw_network
node_nuru -->|"handles"| node_nuru_wisp
node_nuru -->|"tracks"| node_nuru_stream
node_mochi -->|"processes"| node_mochi_pipeline
node_mochi -->|"proxies"| node_mochi_ws
node_cloudsync -->|"persists"| node_cloudsync_data
node_build_tools -->|"builds"| node_app
node_build_tools -->|"builds"| node_mochi
node_build_tools -->|"builds"| node_nuru
node_build_tools -->|"builds"| node_cloudsync

click node_app "https://github.com/enniuu/waves/blob/prod/src/assets/scripts/App.tsx"
click node_ui_components "https://github.com/enniuu/waves/tree/prod/src/assets/scripts/components"
click node_ui_state "https://github.com/enniuu/waves/blob/prod/src/assets/scripts/state/store.ts"
click node_ui_core "https://github.com/enniuu/waves/tree/prod/src/assets/scripts/core"
click node_features "https://github.com/enniuu/waves/tree/prod/src/assets/scripts/features"
click node_search "https://github.com/enniuu/waves/blob/prod/src/assets/scripts/search/search.ts"
click node_service_worker "https://github.com/enniuu/waves/blob/prod/src/b/sw.js"
click node_sw_network "https://github.com/enniuu/waves/blob/prod/src/b/sw/network.js"
click node_sw_transform "https://github.com/enniuu/waves/blob/prod/src/b/sw/handler.js"
click node_sw_state "https://github.com/enniuu/waves/blob/prod/src/b/sw/state.js"
click node_sw_utils "https://github.com/enniuu/waves/blob/prod/src/b/sw/utils.js"
click node_jetty_assets "https://github.com/enniuu/waves/blob/prod/public/b/s/jetty.wasm.wasm"
click node_mochi "https://github.com/enniuu/waves/blob/prod/mochi/src/main.rs"
click node_mochi_pipeline "https://github.com/enniuu/waves/blob/prod/mochi/src/rewrite.rs"
click node_mochi_ws "https://github.com/enniuu/waves/blob/prod/mochi/src/websocket.rs"
click node_nuru "https://github.com/enniuu/waves/blob/prod/nuru/src/main.rs"
click node_nuru_wisp "https://github.com/enniuu/waves/blob/prod/nuru/src/handle/wisp/mod.rs"
click node_nuru_stream "https://github.com/enniuu/waves/blob/prod/nuru/src/stream.rs"
click node_cloudsync "https://github.com/enniuu/waves/blob/prod/cloudsync/src/main.rs"
click node_cloudsync_data "https://github.com/enniuu/waves/blob/prod/cloudsync/src/sync.rs"
click node_build_tools "https://github.com/enniuu/waves/blob/prod/build.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_app,node_ui_components,node_ui_state,node_ui_core,node_features,node_search,node_service_worker,node_sw_network,node_sw_transform,node_sw_state,node_sw_utils toneBlue
class node_jetty_assets toneAmber
class node_mochi,node_mochi_pipeline,node_mochi_ws,node_nuru,node_nuru_wisp,node_nuru_stream,node_cloudsync,node_cloudsync_data toneMint
class node_build_tools toneRose
```

## Components

### Browser UI

React app and service-worker boundary inside the browser.

- [App](https://github.com/enniuu/waves/blob/prod/src/assets/scripts/App.tsx): React shell · Top-level UI composition for the browser-based proxy experience. · `src/assets/scripts/App.tsx`
- [UI Panels](https://github.com/enniuu/waves/tree/prod/src/assets/scripts/components): React components · Bookmarks, games, navigation, settings, sidebar, top bar, and toast surfaces. · `src/assets/scripts/components`
- [UI State](https://github.com/enniuu/waves/blob/prod/src/assets/scripts/state/store.ts): store/config · Shared client state for config, history, iframes, and registration/loading signals. · `src/assets/scripts/state/store.ts`
- [Core Logic](https://github.com/enniuu/waves/tree/prod/src/assets/scripts/core): client core · Client-side helpers for config, history, iframe management, loading, and UI signals. · `src/assets/scripts/core`
- [Features](https://github.com/enniuu/waves/tree/prod/src/assets/scripts/features): feature modules · Feature-level wiring for cloud sync, games, settings, and toast feedback. · `src/assets/scripts/features`
- [Search](https://github.com/enniuu/waves/blob/prod/src/assets/scripts/search/search.ts): search flow · Search/discovery logic used by the UI and search components. · `src/assets/scripts/search/search.ts`
- [SW Proxy](https://github.com/enniuu/waves/blob/prod/src/b/sw.js): intercept layer · Service worker entrypoint that sits on the browser network boundary. · `src/b/sw.js`
- [Network](https://github.com/enniuu/waves/blob/prod/src/b/sw/network.js): request rewrite · Request interception, routing, and transport handling for proxied traffic. · `src/b/sw/network.js`
- [Transform](https://github.com/enniuu/waves/blob/prod/src/b/sw/handler.js): adblock/decode/inject · Adblock, decoding, content rewriting, and script injection pipeline. · `src/b/sw/handler.js`
- [SW State](https://github.com/enniuu/waves/blob/prod/src/b/sw/state.js): messaging/state · Shared service-worker state and message coordination with the UI. · `src/b/sw/state.js`
- [SW Utils](https://github.com/enniuu/waves/blob/prod/src/b/sw/utils.js): helpers · Constants, initialization, and shared utility helpers for the proxy boundary. · `src/b/sw/utils.js`

### Proxy Runtime

Prebuilt client-side proxy assets delivered to the browser.

- [Jetty Assets](https://github.com/enniuu/waves/blob/prod/public/b/s/jetty.wasm.wasm): runtime bundle · Prebuilt JS and WASM proxy runtime assets shipped to the browser. · `public/b/s/jetty.wasm.wasm`

### Rust Services

Server-side crates for transport, proxying, and sync.

- [Mochi](https://github.com/enniuu/waves/blob/prod/mochi/src/main.rs): proxy engine · Proxy content pipeline for cache, encoding, rewrite, websocket, and state handling. · `mochi/src/main.rs`
- [Content Pipeline](https://github.com/enniuu/waves/blob/prod/mochi/src/rewrite.rs): rewrite/cache/encode · Representative internal pipeline for response rewriting, encoding, caching, and proxy logic. · `mochi/src/rewrite.rs`
- [WebSocket](https://github.com/enniuu/waves/blob/prod/mochi/src/websocket.rs): ws handling · WebSocket-specific proxy handling and streaming support inside Mochi. · `mochi/src/websocket.rs`
- [Nuru](https://github.com/enniuu/waves/blob/prod/nuru/src/main.rs): transport service · Listener and routing service for upgrades, streaming, and proxy transport. · `nuru/src/main.rs`
- [Wisp Handlers](https://github.com/enniuu/waves/blob/prod/nuru/src/handle/wisp/mod.rs): ws/upgrade protocol · Wisp protocol handling, websocket proxying, and upgrade coordination. · `nuru/src/handle/wisp/mod.rs`
- [Stream State](https://github.com/enniuu/waves/blob/prod/nuru/src/stream.rs): routing/stats · Streaming, routing, and statistics around active proxy connections. · `nuru/src/stream.rs`
- [Cloud Sync](https://github.com/enniuu/waves/blob/prod/cloudsync/src/main.rs): sync service · Backend service that authenticates users and reconciles synced client data. · `cloudsync/src/main.rs`
- [Sync Data](https://github.com/enniuu/waves/blob/prod/cloudsync/src/sync.rs): auth/db/sync · Authentication, persistence, and synchronization logic for games, browsing data, and settings. · `cloudsync/src/sync.rs`

### Build & Delivery

Repository-level automation and delivery entrypoints.

- [Build Tools](https://github.com/enniuu/waves/blob/prod/build.js): repo automation · Repository-level scripts and automation used to build and prepare the app and services. · `build.js`

## Connections

- App → UI Panels: renders · App composes the primary UI surfaces.
- App → UI State: binds · App reads and updates shared client state.
- UI Panels → Features: uses · Panels delegate domain actions to feature modules.
- Core Logic → UI State: coordinates · Core logic manages shared state and UI signals.
- Features → Search: searches · Features route discovery and search behavior.
- Features → Cloud Sync: syncs · Feature module talks to the cloud sync backend.
- SW Proxy → Network: intercepts · Service worker hands request control to the network layer.
- SW Proxy → Transform: rewrites · Service worker applies transformation and injection logic.
- SW Proxy → SW State: syncs · Service worker exchanges state and messages with the UI.
- Network → Jetty Assets: loads · Network/runtime behavior relies on bundled proxy assets.
- Transform → Jetty Assets: executes · Transform logic is supported by shipped runtime artifacts.
- SW State → UI State: mirrors · Browser UI and service worker coordinate shared session state.
- SW Utils → Network: supports · Shared helpers and constants support request handling.
- Nuru → Wisp Handlers: handles · Nuru routes upgrades and protocol-specific handlers.
- Nuru → Stream State: tracks · Nuru maintains stream routing and connection stats.
- Mochi → Content Pipeline: processes · Mochi runs the main content transformation pipeline.
- Mochi → WebSocket: proxies · Mochi handles websocket traffic as part of proxying.
- Cloud Sync → Sync Data: persists · Cloud sync authenticates, stores, and reconciles user state.
- Build Tools → App: builds · Repository automation prepares the browser application.
- Build Tools → Mochi: builds · Automation also prepares the Rust proxy services.
- Build Tools → Nuru: builds · Automation also prepares the transport service.
- Build Tools → Cloud Sync: builds · Automation also prepares the sync service.