# stremio/stremio-core-web architecture

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

- Interactive diagram: https://gitdiagram.com/stremio/stremio-core-web
- Repository: https://github.com/stremio/stremio-core-web

## Overview

1. **Overall role**
   - This repository is a **WebAssembly bridge package** between the Rust-based `stremio-core` and the JavaScript application `stremio-web`.
   - Its job is not to implement the whole product, but to **adapt core domain data and events into a web-friendly boundary** that can be consumed from JS/npm.

2. **Top-level runtime split**
   - The codebase is split into a **Rust/WASM side** and a **JavaScript integration side**.
   - Rust owns the domain-facing logic and serialization adapters.
   - JS owns the package entry points and worker/bridge glue used by the web app.

3. **Rust crate as the main architecture center**
   - `Cargo.toml`, `Cargo.lock`, `rust-toolchain.toml`, and `src/lib.rs` indicate the primary deliverable is a **Rust library compiled to WASM**.
   - `src/stremio_core_web.rs` is likely the crate façade that exposes the web bridge API.
   - `src/env.rs` and `src/event.rs` suggest the bridge depends on a controlled runtime environment and an event channel for notifications back to the web layer.

4. **Boundary between core models and web serialization**
   - The `src/model/` directory is the most important subsystem.
   - It contains a set of **serializer/adaptor modules** such as `serialize_library.rs`, `serialize_player.rs`, `serialize_streaming_server.rs`, `serialize_discover.rs`, and others.
   - This indicates the repo translates internal `stremio-core` structures into **JS/WASM-safe shapes** for specific product areas instead of exposing raw core types.

5. **Feature-oriented model adapters**
   - `src/model/model.rs` and `src/model/mod.rs` likely define the shared model layer and module wiring.
   - The various `serialize_*` files map to distinct product domains: library, discover, player, local search, remote addons, installed addons, data export, meta details, continue-watching preview, and catalogs.
   - This means the architecture is organized around **use-case slices**, not around generic transport helpers.

6. **Deep-link support as a dedicated extension layer**
   - `src/model/deep_links_ext/` is a separate subsystem for deep-link handling.
   - Files like `video_deep_links.rs`, `stream_deep_links.rs`, `library_deep_links.rs`, and `search_history_deep_links.rs` show that navigation/state-entry points are modeled explicitly.
   - This layer likely converts app-specific routes or intents into core actions and serializable link targets.

7. **JavaScript bridge and worker boundary**
   - `src/bridge.js` and `src/worker.js` are the browser-side integration points.
   - Their presence strongly suggests the WASM module runs behind a **worker-based or message-passing bridge**, isolating heavy core logic from the UI thread.
   - This is the main boundary where JS communicates with Rust-generated behavior.

8. **Data flow through the package**
   - The likely flow is: **stremio-web sends requests/events into the JS bridge → JS forwards them to the WASM/Rust layer → Rust uses core-derived models and env/event abstractions → results are serialized back to JS**.
   - The `event` module implies asynchronous updates are pushed back out, not just request/response calls.
   - The model serializers are the main output boundary for these flows.

9. **Build and packaging architecture**
   - `package.json`, `package-lock.json`, `.babelrc`, and `.npmignore` show this repo is packaged for the **npm ecosystem**.
   - `scripts/build.sh` and the README’s build flow indicate a production build compiles the Rust crate to WASM and then prepares JS/package artifacts.
   - The repo is therefore a **cross-language build pipeline**, not a single-language library.

10. **Development and debug mode**
   - The README notes a `--dev` build path and a `cargo wasm-watch` workflow from `.cargo/config.toml`.
   - That implies the package supports **incremental recompilation and verbose debug logging** during development, with a warning that debug logs may include sensitive data.
   - This is a tooling concern that affects how the bridge is operated locally.

11. **CI/CD and release lifecycle**
   - `.github/workflows/build.yml`, `prerelease.yml`, and `publish.yml` define automated build and release flows.
   - Publishing targets both **GitHub Releases** and the **npm registry**.
   - Versioning is coordinated across Cargo and npm manifests, so release management is part of the repo’s operational architecture.

12. **External dependencies and product boundaries**
   - The repository depends structurally on **`stremio-core`** and is consumed by **`stremio-web`**.
   - That makes it an adapter layer between a shared domain core and a web client, with a stable contract defined by WASM exports, JS bridges, and serialized model shapes.
   - For an architecture diagram, this repo should be shown as a **middle-tier packaging/interop layer** rather than an end-user application or backend service.

Main entry points: [`src/model/mod.rs`](https://github.com/stremio/stremio-core-web/blob/development/src/model/mod.rs) (Model layer), [`src/stremio_core_web.rs`](https://github.com/stremio/stremio-core-web/blob/development/src/stremio_core_web.rs) (Web facade), [`scripts/build.sh`](https://github.com/stremio/stremio-core-web/blob/development/scripts/build.sh) (Build script), [`.github/workflows/publish.yml`](https://github.com/stremio/stremio-core-web/blob/development/.github/workflows/publish.yml) (Publish)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_js["JavaScript bridge"]
  node_bridge_js["Bridge<br/>js entry<br/>[bridge.js]"]
  node_worker_js["Worker<br/>[worker.js]"]
end

subgraph group_rust["Rust/WASM core"]
  node_lib_rs["Library<br/>wasm lib<br/>[lib.rs]"]
  node_web_fa["Web facade<br/>bridge facade"]
  node_env_rs["Env<br/>[env.rs]"]
  node_event_rs["Events<br/>event channel<br/>[event.rs]"]
end

subgraph group_model["Model adapters"]
  node_model_mod["Model layer<br/>adapter module<br/>[mod.rs]"]
  node_model_rs["Shared model<br/>model core<br/>[model.rs]"]
  node_serialize_ctx["Context<br/>serializer ctx<br/>[serialize_ctx.rs]"]
  node_serialize_library["Library data<br/>serializer"]
  node_serialize_player["Player data<br/>serializer"]
  node_serialize_discover["Discover data<br/>serializer"]
  node_serialize_streaming["Streaming server<br/>serializer"]
  node_serialize_remote_addons["Remote addons<br/>serializer"]
  node_deep_links["Deep links<br/>link extensions<br/>[mod.rs]"]
  node_video_links["Video links<br/>deep-link adapter"]
end

subgraph group_tooling["Build and release"]
  node_build_sh["Build script<br/>[build.sh]"]
  node_cargo_toml["Cargo<br/>rust package<br/>[Cargo.toml]"]
  node_build_wf["CI build<br/>workflow<br/>[build.yml]"]
  node_prerelease_wf["Pre-release<br/>workflow<br/>[prerelease.yml]"]
  node_publish_wf["Publish<br/>workflow<br/>[publish.yml]"]
end

node_stremio_web(("stremio-web<br/>external app"))
node_stremio_core(("stremio-core<br/>external core"))

node_stremio_web -->|"uses"| node_bridge_js
node_bridge_js -->|"spawns"| node_worker_js
node_worker_js -->|"loads WASM"| node_lib_rs
node_lib_rs -->|"exposes"| node_web_fa
node_web_fa -->|"uses"| node_env_rs
node_web_fa -->|"emits"| node_event_rs
node_web_fa -->|"adapts"| node_model_mod
node_model_mod -->|"shares"| node_model_rs
node_model_mod -->|"builds on"| node_serialize_ctx
node_model_mod -->|"includes"| node_serialize_library
node_model_mod -->|"includes"| node_serialize_player
node_model_mod -->|"includes"| node_serialize_discover
node_model_mod -->|"includes"| node_serialize_streaming
node_model_mod -->|"includes"| node_serialize_remote_addons
node_model_mod -->|"extends"| node_deep_links
node_deep_links -->|"specializes"| node_video_links
node_web_fa -->|"adapts"| node_stremio_core
node_build_sh -->|"drives"| node_cargo_toml
node_build_wf -->|"runs"| node_build_sh
node_prerelease_wf -->|"runs"| node_build_sh
node_publish_wf -->|"packages"| node_cargo_toml
node_publish_wf -->|"delivers to"| node_stremio_web

click node_bridge_js "https://github.com/stremio/stremio-core-web/blob/development/src/bridge.js"
click node_worker_js "https://github.com/stremio/stremio-core-web/blob/development/src/worker.js"
click node_lib_rs "https://github.com/stremio/stremio-core-web/blob/development/src/lib.rs"
click node_web_fa "https://github.com/stremio/stremio-core-web/blob/development/src/stremio_core_web.rs"
click node_env_rs "https://github.com/stremio/stremio-core-web/blob/development/src/env.rs"
click node_event_rs "https://github.com/stremio/stremio-core-web/blob/development/src/event.rs"
click node_model_mod "https://github.com/stremio/stremio-core-web/blob/development/src/model/mod.rs"
click node_model_rs "https://github.com/stremio/stremio-core-web/blob/development/src/model/model.rs"
click node_serialize_ctx "https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_ctx.rs"
click node_serialize_library "https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_library.rs"
click node_serialize_player "https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_player.rs"
click node_serialize_discover "https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_discover.rs"
click node_serialize_streaming "https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_streaming_server.rs"
click node_serialize_remote_addons "https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_remote_addons.rs"
click node_deep_links "https://github.com/stremio/stremio-core-web/blob/development/src/model/deep_links_ext/mod.rs"
click node_video_links "https://github.com/stremio/stremio-core-web/blob/development/src/model/deep_links_ext/video_deep_links.rs"
click node_build_sh "https://github.com/stremio/stremio-core-web/blob/development/scripts/build.sh"
click node_cargo_toml "https://github.com/stremio/stremio-core-web/blob/development/Cargo.toml"
click node_build_wf "https://github.com/stremio/stremio-core-web/blob/development/.github/workflows/build.yml"
click node_prerelease_wf "https://github.com/stremio/stremio-core-web/blob/development/.github/workflows/prerelease.yml"
click node_publish_wf "https://github.com/stremio/stremio-core-web/blob/development/.github/workflows/publish.yml"

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_bridge_js,node_worker_js toneBlue
class node_lib_rs,node_web_fa,node_env_rs,node_event_rs toneAmber
class node_model_mod,node_model_rs,node_serialize_ctx,node_serialize_library,node_serialize_player,node_serialize_discover,node_serialize_streaming,node_serialize_remote_addons,node_deep_links,node_video_links toneMint
class node_build_sh,node_cargo_toml,node_build_wf,node_prerelease_wf,node_publish_wf toneRose
class node_stremio_web,node_stremio_core toneNeutral
```

## Components

### JavaScript bridge

Package entry points and worker boundary used by the web app.

- [Bridge](https://github.com/stremio/stremio-core-web/blob/development/src/bridge.js): js entry · JavaScript-side integration entry point. · `src/bridge.js`
- [Worker](https://github.com/stremio/stremio-core-web/blob/development/src/worker.js): js worker · Message-passing runtime boundary for WASM execution. · `src/worker.js`

### Rust/WASM core

Primary library compiled to WebAssembly and hosting bridge logic.

- [Library](https://github.com/stremio/stremio-core-web/blob/development/src/lib.rs): wasm lib · Crate root and WASM-exported public surface. · `src/lib.rs`
- [Web facade](https://github.com/stremio/stremio-core-web/blob/development/src/stremio_core_web.rs): bridge facade · High-level Rust facade for the web bridge API. · `src/stremio_core_web.rs`
- [Env](https://github.com/stremio/stremio-core-web/blob/development/src/env.rs): runtime env · Controlled execution environment for bridge operations. · `src/env.rs`
- [Events](https://github.com/stremio/stremio-core-web/blob/development/src/event.rs): event channel · Async event channel back to the JavaScript layer. · `src/event.rs`

### Model adapters

Feature-oriented serializers and deep-link extensions.

- [Model layer](https://github.com/stremio/stremio-core-web/blob/development/src/model/mod.rs): adapter module · Module wiring for all web-safe model adapters. · `src/model/mod.rs`
- [Shared model](https://github.com/stremio/stremio-core-web/blob/development/src/model/model.rs): model core · Common model definitions and adapter support. · `src/model/model.rs`
- [Context](https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_ctx.rs): serializer ctx · Shared serialization context and helpers. · `src/model/serialize_ctx.rs`
- [Library data](https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_library.rs): serializer · Library domain serialization for web consumption. · `src/model/serialize_library.rs`
- [Player data](https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_player.rs): serializer · Player-related serialization boundary. · `src/model/serialize_player.rs`
- [Discover data](https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_discover.rs): serializer · Discovery/catalog browsing serialization. · `src/model/serialize_discover.rs`
- [Streaming server](https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_streaming_server.rs): serializer · Streaming-server and playback-adjacent serialization. · `src/model/serialize_streaming_server.rs`
- [Remote addons](https://github.com/stremio/stremio-core-web/blob/development/src/model/serialize_remote_addons.rs): serializer · Remote addon listing and shape conversion. · `src/model/serialize_remote_addons.rs`
- [Deep links](https://github.com/stremio/stremio-core-web/blob/development/src/model/deep_links_ext/mod.rs): link extensions · Route and intent adapters for entry-point links. · `src/model/deep_links_ext/mod.rs`
- [Video links](https://github.com/stremio/stremio-core-web/blob/development/src/model/deep_links_ext/video_deep_links.rs): deep-link adapter · Video-level deep-link handling. · `src/model/deep_links_ext/video_deep_links.rs`

### Build and release

Cross-language build, packaging, and publishing pipeline.

- [Build script](https://github.com/stremio/stremio-core-web/blob/development/scripts/build.sh): build script · Repository build orchestration for Rust-to-WASM packaging. · `scripts/build.sh`
- [Cargo](https://github.com/stremio/stremio-core-web/blob/development/Cargo.toml): rust package · Crate configuration and dependency boundary. · `Cargo.toml`
- [CI build](https://github.com/stremio/stremio-core-web/blob/development/.github/workflows/build.yml): workflow · Automated build and verification pipeline. · `.github/workflows/build.yml`
- [Pre-release](https://github.com/stremio/stremio-core-web/blob/development/.github/workflows/prerelease.yml): workflow · Pre-release automation for distributable artifacts. · `.github/workflows/prerelease.yml`
- [Publish](https://github.com/stremio/stremio-core-web/blob/development/.github/workflows/publish.yml): workflow · Release publishing to package and release channels. · `.github/workflows/publish.yml`

### Other components

- **stremio-web**: external app · Browser client consuming the bridge package.
- **stremio-core**: external core · Shared Rust domain core adapted by this package.

## Connections

- stremio-web → Bridge: uses · Web app calls into the package bridge.
- Bridge → Worker: spawns · JS bridge delegates heavy work to the worker boundary.
- Worker → Library: loads WASM · Worker communicates with the Rust/WASM library.
- Library → Web facade: exposes · Public facade for web-facing bridge behavior.
- Web facade → Env: uses · Facade relies on controlled runtime environment.
- Web facade → Events: emits · Facade forwards async events back to JS.
- Web facade → Model layer: adapts · Facade uses the model adapter layer.
- Model layer → Shared model: shares · Common model definitions underpin serializers.
- Model layer → Context: builds on · Serializer wiring uses shared context helpers.
- Model layer → Library data: includes · Library-domain serialization boundary.
- Model layer → Player data: includes · Player-domain serialization boundary.
- Model layer → Discover data: includes · Discover-domain serialization boundary.
- Model layer → Streaming server: includes · Streaming-server serialization boundary.
- Model layer → Remote addons: includes · Remote-addon serialization boundary.
- Model layer → Deep links: extends · Wires in explicit deep-link handling.
- Deep links → Video links: specializes · One representative deep-link adapter.
- Web facade → stremio-core: adapts · Rust bridge translates shared core domain into web-safe shapes.
- Build script → Cargo: drives · Build script orchestrates the Rust/WASM package build.
- CI build → Build script: runs · CI executes the build pipeline.
- Pre-release → Build script: runs · Pre-release automation reuses the build pipeline.
- Publish → Cargo: packages · Release workflow coordinates Rust package versioning.
- Publish → stremio-web: delivers to · Published artifacts are intended for the web client ecosystem.