How enniuu/waves works
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 Build Tools · sw.js SW Proxy · features Features · App.tsx App
Components 21
Browser UI
React app and service-worker boundary inside the browser.
- App · Top-level UI composition for the browser-based proxy experience.
src/assets/scripts/App.tsx - UI Panels · Bookmarks, games, navigation, settings, sidebar, top bar, and toast surfaces.
src/assets/scripts/components - UI State · Shared client state for config, history, iframes, and registration/loading signals.
src/assets/scripts/state/store.ts - Core Logic · Client-side helpers for config, history, iframe management, loading, and UI signals.
src/assets/scripts/core - Features · Feature-level wiring for cloud sync, games, settings, and toast feedback.
src/assets/scripts/features - Search · Search/discovery logic used by the UI and search components.
src/assets/scripts/search/search.ts - SW Proxy · Service worker entrypoint that sits on the browser network boundary.
src/b/sw.js - Network · Request interception, routing, and transport handling for proxied traffic.
src/b/sw/network.js - Transform · Adblock, decoding, content rewriting, and script injection pipeline.
src/b/sw/handler.js - SW State · Shared service-worker state and message coordination with the UI.
src/b/sw/state.js - SW Utils · 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 · 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 · Proxy content pipeline for cache, encoding, rewrite, websocket, and state handling.
mochi/src/main.rs - Content Pipeline · Representative internal pipeline for response rewriting, encoding, caching, and proxy logic.
mochi/src/rewrite.rs - WebSocket · WebSocket-specific proxy handling and streaming support inside Mochi.
mochi/src/websocket.rs - Nuru · Listener and routing service for upgrades, streaming, and proxy transport.
nuru/src/main.rs - Wisp Handlers · Wisp protocol handling, websocket proxying, and upgrade coordination.
nuru/src/handle/wisp/mod.rs - Stream State · Streaming, routing, and statistics around active proxy connections.
nuru/src/stream.rs - Cloud Sync · Backend service that authenticates users and reconciles synced client data.
cloudsync/src/main.rs - Sync Data · 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 · Repository-level scripts and automation used to build and prepare the app and services.
build.js
Connections 22
- 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.