# webtorrent/webtorrent architecture

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

- Interactive diagram: https://gitdiagram.com/webtorrent/webtorrent
- Repository: https://github.com/webtorrent/webtorrent

## Overview

WebTorrent is a JavaScript BitTorrent client for Node.js and browsers. Its main workflow is to add or seed a torrent, discover peers, exchange and verify pieces, then expose files as streams or HTTP responses. The README also documents magnet metadata, DHT/tracker/LSD/PEX discovery, protocol extensions, and browser WebRTC. Edges reflect sampled calls and explicit README statements; some documented integrations are not directly shown in the excerpts.

Main entry points: [`lib/torrent.js`](https://github.com/webtorrent/webtorrent/blob/master/lib/torrent.js) (Torrent lifecycle), [`index.js`](https://github.com/webtorrent/webtorrent/blob/master/index.js) (WebTorrent client), [`lib/file.js`](https://github.com/webtorrent/webtorrent/blob/master/lib/file.js) (Torrent files), [`lib/peer.js`](https://github.com/webtorrent/webtorrent/blob/master/lib/peer.js) (Peer protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and torrents"]
  node_client["WebTorrent client<br/>[index.js]"]
  node_torrent["Torrent lifecycle<br/>[torrent.js]"]
end

subgraph group_network["Peer networking"]
  node_discovery["Peer discovery<br/>[torrent.js]"]
  node_trackers{{"Trackers and DHT"}}
  node_lsd{{"Local discovery"}}
  node_webconn["WebRTC transport<br/>[webconn.js]"]
  node_connpool["TCP and uTP pool<br/>[conn-pool.js]"]
  node_peer["Peer protocol<br/>[peer.js]"]
end

subgraph group_transfer["Pieces and files"]
  node_selection["Piece selection<br/>[selections.js]"]
  node_rarity["Rarity map<br/>[rarity-map.js]"]
  node_storage[("Piece storage<br/>[torrent.js]")]
  node_file["Torrent files<br/>[file.js]"]
  node_iterator["File iterator<br/>[file-iterator.js]"]
end

subgraph group_serving["File serving"]
  node_httpserver["HTTP file server<br/>[server.js]"]
  node_worker["Service worker<br/>[worker.js]"]
  node_workerroute["Worker request relay<br/>[worker-server.js]"]
end

node_user(("Application"))
node_reader(("File consumer"))

node_user -->|"adds or seeds"| node_client
node_client -->|"creates"| node_torrent
node_client -->|"initializes"| node_connpool
node_torrent -->|"finds peers"| node_discovery
node_discovery -->|"queries"| node_trackers
node_discovery -->|"discovers locally"| node_lsd
node_torrent -->|"manages peers"| node_peer
node_connpool -->|"creates incoming peers"| node_peer
node_webconn -.->|"uses WebRTC peers"| node_peer
node_peer -.->|"exchanges pieces"| node_torrent
node_torrent -->|"selects pieces"| node_selection
node_torrent -->|"ranks pieces"| node_rarity
node_torrent -->|"verifies and stores"| node_storage
node_torrent -->|"creates files"| node_file
node_file -->|"creates iterator"| node_iterator
node_file -->|"reads pieces"| node_storage
node_reader -->|"reads stream"| node_file
node_client -->|"serves files"| node_httpserver
node_httpserver -->|"streams file"| node_file
node_worker -->|"routes fetch"| node_workerroute
node_workerroute -->|"relays request"| node_client

click node_client "https://github.com/webtorrent/webtorrent/blob/master/index.js"
click node_torrent "https://github.com/webtorrent/webtorrent/blob/master/lib/torrent.js"
click node_discovery "https://github.com/webtorrent/webtorrent/blob/master/lib/torrent.js"
click node_webconn "https://github.com/webtorrent/webtorrent/blob/master/lib/webconn.js"
click node_connpool "https://github.com/webtorrent/webtorrent/blob/master/lib/conn-pool.js"
click node_peer "https://github.com/webtorrent/webtorrent/blob/master/lib/peer.js"
click node_selection "https://github.com/webtorrent/webtorrent/blob/master/lib/selections.js"
click node_rarity "https://github.com/webtorrent/webtorrent/blob/master/lib/rarity-map.js"
click node_storage "https://github.com/webtorrent/webtorrent/blob/master/lib/torrent.js"
click node_file "https://github.com/webtorrent/webtorrent/blob/master/lib/file.js"
click node_iterator "https://github.com/webtorrent/webtorrent/blob/master/lib/file-iterator.js"
click node_httpserver "https://github.com/webtorrent/webtorrent/blob/master/lib/server.js"
click node_worker "https://github.com/webtorrent/webtorrent/blob/master/lib/worker.js"
click node_workerroute "https://github.com/webtorrent/webtorrent/blob/master/lib/worker-server.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_client,node_torrent toneBlue
class node_discovery,node_trackers,node_lsd,node_webconn,node_connpool,node_peer toneAmber
class node_selection,node_rarity,node_storage,node_file,node_iterator toneMint
class node_httpserver,node_worker,node_workerroute toneRose
class node_user,node_reader toneIndigo
```

## Components

### Client and torrents

- [WebTorrent client](https://github.com/webtorrent/webtorrent/blob/master/index.js): `index.js`
- [Torrent lifecycle](https://github.com/webtorrent/webtorrent/blob/master/lib/torrent.js): `lib/torrent.js`

### Peer networking

- [Peer discovery](https://github.com/webtorrent/webtorrent/blob/master/lib/torrent.js): `lib/torrent.js`
- **Trackers and DHT**
- **Local discovery**
- [WebRTC transport](https://github.com/webtorrent/webtorrent/blob/master/lib/webconn.js): `lib/webconn.js`
- [TCP and uTP pool](https://github.com/webtorrent/webtorrent/blob/master/lib/conn-pool.js): `lib/conn-pool.js`
- [Peer protocol](https://github.com/webtorrent/webtorrent/blob/master/lib/peer.js): `lib/peer.js`

### Pieces and files

- [Piece selection](https://github.com/webtorrent/webtorrent/blob/master/lib/selections.js): `lib/selections.js`
- [Rarity map](https://github.com/webtorrent/webtorrent/blob/master/lib/rarity-map.js): `lib/rarity-map.js`
- [Piece storage](https://github.com/webtorrent/webtorrent/blob/master/lib/torrent.js): `lib/torrent.js`
- [Torrent files](https://github.com/webtorrent/webtorrent/blob/master/lib/file.js): `lib/file.js`
- [File iterator](https://github.com/webtorrent/webtorrent/blob/master/lib/file-iterator.js): `lib/file-iterator.js`

### File serving

- [HTTP file server](https://github.com/webtorrent/webtorrent/blob/master/lib/server.js): `lib/server.js`
- [Service worker](https://github.com/webtorrent/webtorrent/blob/master/lib/worker.js): `lib/worker.js`
- [Worker request relay](https://github.com/webtorrent/webtorrent/blob/master/lib/worker-server.js): `lib/worker-server.js`

### Other components

- **Application**
- **File consumer**

## Connections

- Application → WebTorrent client: adds or seeds (evidence: `README.md`)
- WebTorrent client → Torrent lifecycle: creates (evidence: `index.js`)
- WebTorrent client → TCP and uTP pool: initializes (evidence: `index.js`)
- Torrent lifecycle → Peer discovery: finds peers (evidence: `README.md`)
- Peer discovery → Trackers and DHT: queries (evidence: `README.md`)
- Peer discovery → Local discovery: discovers locally (evidence: `README.md`)
- Torrent lifecycle → Peer protocol: manages peers (evidence: `lib/torrent.js`)
- TCP and uTP pool → Peer protocol: creates incoming peers (evidence: `lib/conn-pool.js`)
- WebRTC transport → Peer protocol: uses WebRTC peers
- Peer protocol → Torrent lifecycle: exchanges pieces (evidence: `lib/torrent.js`)
- Torrent lifecycle → Piece selection: selects pieces (evidence: `lib/torrent.js`)
- Torrent lifecycle → Rarity map: ranks pieces (evidence: `lib/torrent.js`)
- Torrent lifecycle → Piece storage: verifies and stores (evidence: `lib/torrent.js`)
- Torrent lifecycle → Torrent files: creates files (evidence: `lib/torrent.js`)
- Torrent files → File iterator: creates iterator (evidence: `lib/file.js`)
- Torrent files → Piece storage: reads pieces (evidence: `lib/file.js`)
- File consumer → Torrent files: reads stream (evidence: `README.md`)
- WebTorrent client → HTTP file server: serves files (evidence: `index.js`)
- HTTP file server → Torrent files: streams file (evidence: `lib/server.js`)
- Service worker → Worker request relay: routes fetch (evidence: `lib/worker.js`)
- Worker request relay → WebTorrent client: relays request (evidence: `lib/worker-server.js`)
