# websockets/ws architecture

> Architecture diagram of the GitHub repository websockets/ws, 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/websockets/ws
- Repository: https://github.com/websockets/ws

## Overview

ws is a Node.js WebSocket client and server library. A client initiates a connection or a server accepts an HTTP upgrade; the WebSocket runtime then sends and receives protocol frames and exposes messages, events, and an optional stream interface. Server-side handshake negotiation includes subprotocols and optional permessage-deflate compression. The graph reflects the sampled runtime modules and README capabilities; unsampled internals are represented only where the tree or README supports them, so some relationships are intentionally omitted.

Main entry points: [`lib/websocket.js`](https://github.com/websockets/ws/blob/master/lib/websocket.js) (WebSocket API), [`lib/websocket-server.js`](https://github.com/websockets/ws/blob/master/lib/websocket-server.js) (Server Upgrade), [`lib/receiver.js`](https://github.com/websockets/ws/blob/master/lib/receiver.js) (Frame Receiver), [`lib/permessage-deflate.js`](https://github.com/websockets/ws/blob/master/lib/permessage-deflate.js) (Message Compression)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["WebSocket API<br/>[websocket.js]"]
  node_server["WebSocket Server"]
  node_streams["Stream Adapter<br/>[stream.js]"]
end

subgraph group_connection["Connection Handshake"]
  node_client_handshake["Client Handshake<br/>[websocket.js]"]
  node_server_upgrade["Server Upgrade"]
  node_extension_negotiation["Extension Negotiation<br/>[extension.js]"]
  node_subprotocol["Subprotocols<br/>[subprotocol.js]"]
end

subgraph group_protocol["WebSocket Protocol"]
  node_sender["Frame Sender<br/>[sender.js]"]
  node_receiver["Frame Receiver<br/>[receiver.js]"]
  node_compression["Message Compression"]
  node_events["Event Target<br/>[event-target.js]"]
end

subgraph group_support["Runtime Support"]
  node_buffer["Buffer Utilities<br/>[buffer-util.js]"]
  node_validation["Protocol Validation<br/>[validation.js]"]
  node_limiter["Zlib Limiter<br/>[limiter.js]"]
end

node_user(("Application"))
node_http["Node HTTP/S"]

node_user -->|"opens client"| node_api
node_user -->|"creates server"| node_server
node_api -->|"initiates"| node_client_handshake
node_http -->|"provides upgrades"| node_server
node_server -->|"handles upgrades"| node_server_upgrade
node_server_upgrade -->|"creates connection"| node_api
node_server_upgrade -->|"negotiates extensions"| node_extension_negotiation
node_server_upgrade -->|"parses protocols"| node_subprotocol
node_api -->|"sends frames"| node_sender
node_api -->|"receives frames"| node_receiver
node_sender -->|"compresses payloads"| node_compression
node_receiver -->|"inflates payloads"| node_compression
node_sender -->|"masks data"| node_buffer
node_receiver -->|"unmasks data"| node_buffer
node_receiver -->|"validates frames"| node_validation
node_subprotocol -->|"uses tokens"| node_validation
node_extension_negotiation -->|"uses tokens"| node_validation
node_compression -->|"joins buffers"| node_buffer
node_compression -->|"limits concurrency"| node_limiter
node_api -->|"exposes events"| node_events
node_api -->|"adapts connection"| node_streams
node_api -->|"uses extensions"| node_extension_negotiation

click node_api "https://github.com/websockets/ws/blob/master/lib/websocket.js"
click node_server "https://github.com/websockets/ws/blob/master/lib/websocket-server.js"
click node_streams "https://github.com/websockets/ws/blob/master/lib/stream.js"
click node_client_handshake "https://github.com/websockets/ws/blob/master/lib/websocket.js"
click node_server_upgrade "https://github.com/websockets/ws/blob/master/lib/websocket-server.js"
click node_extension_negotiation "https://github.com/websockets/ws/blob/master/lib/extension.js"
click node_subprotocol "https://github.com/websockets/ws/blob/master/lib/subprotocol.js"
click node_sender "https://github.com/websockets/ws/blob/master/lib/sender.js"
click node_receiver "https://github.com/websockets/ws/blob/master/lib/receiver.js"
click node_compression "https://github.com/websockets/ws/blob/master/lib/permessage-deflate.js"
click node_events "https://github.com/websockets/ws/blob/master/lib/event-target.js"
click node_buffer "https://github.com/websockets/ws/blob/master/lib/buffer-util.js"
click node_validation "https://github.com/websockets/ws/blob/master/lib/validation.js"
click node_limiter "https://github.com/websockets/ws/blob/master/lib/limiter.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_api,node_server,node_streams toneBlue
class node_client_handshake,node_server_upgrade,node_extension_negotiation,node_subprotocol toneAmber
class node_sender,node_receiver,node_compression,node_events toneMint
class node_buffer,node_validation,node_limiter toneRose
class node_user,node_http toneIndigo
```

## Components

### Public API

- [WebSocket API](https://github.com/websockets/ws/blob/master/lib/websocket.js): `lib/websocket.js`
- [WebSocket Server](https://github.com/websockets/ws/blob/master/lib/websocket-server.js): `lib/websocket-server.js`
- [Stream Adapter](https://github.com/websockets/ws/blob/master/lib/stream.js): `lib/stream.js`

### Connection Handshake

- [Client Handshake](https://github.com/websockets/ws/blob/master/lib/websocket.js): `lib/websocket.js`
- [Server Upgrade](https://github.com/websockets/ws/blob/master/lib/websocket-server.js): `lib/websocket-server.js`
- [Extension Negotiation](https://github.com/websockets/ws/blob/master/lib/extension.js): `lib/extension.js`
- [Subprotocols](https://github.com/websockets/ws/blob/master/lib/subprotocol.js): `lib/subprotocol.js`

### WebSocket Protocol

- [Frame Sender](https://github.com/websockets/ws/blob/master/lib/sender.js): `lib/sender.js`
- [Frame Receiver](https://github.com/websockets/ws/blob/master/lib/receiver.js): `lib/receiver.js`
- [Message Compression](https://github.com/websockets/ws/blob/master/lib/permessage-deflate.js): `lib/permessage-deflate.js`
- [Event Target](https://github.com/websockets/ws/blob/master/lib/event-target.js): `lib/event-target.js`

### Runtime Support

- [Buffer Utilities](https://github.com/websockets/ws/blob/master/lib/buffer-util.js): `lib/buffer-util.js`
- [Protocol Validation](https://github.com/websockets/ws/blob/master/lib/validation.js): `lib/validation.js`
- [Zlib Limiter](https://github.com/websockets/ws/blob/master/lib/limiter.js): `lib/limiter.js`

### Other components

- **Application**
- **Node HTTP/S**

## Connections

- Application → WebSocket API: opens client (evidence: `README.md`)
- Application → WebSocket Server: creates server (evidence: `README.md`)
- WebSocket API → Client Handshake: initiates (evidence: `lib/websocket.js`)
- Node HTTP/S → WebSocket Server: provides upgrades (evidence: `lib/websocket-server.js`)
- WebSocket Server → Server Upgrade: handles upgrades (evidence: `lib/websocket-server.js`)
- Server Upgrade → WebSocket API: creates connection (evidence: `lib/websocket-server.js`)
- Server Upgrade → Extension Negotiation: negotiates extensions (evidence: `lib/websocket-server.js`)
- Server Upgrade → Subprotocols: parses protocols (evidence: `lib/websocket-server.js`)
- WebSocket API → Frame Sender: sends frames (evidence: `lib/websocket.js`)
- WebSocket API → Frame Receiver: receives frames (evidence: `lib/websocket.js`)
- Frame Sender → Message Compression: compresses payloads (evidence: `lib/sender.js`)
- Frame Receiver → Message Compression: inflates payloads (evidence: `lib/receiver.js`)
- Frame Sender → Buffer Utilities: masks data (evidence: `lib/sender.js`)
- Frame Receiver → Buffer Utilities: unmasks data (evidence: `lib/receiver.js`)
- Frame Receiver → Protocol Validation: validates frames (evidence: `lib/receiver.js`)
- Subprotocols → Protocol Validation: uses tokens (evidence: `lib/subprotocol.js`)
- Extension Negotiation → Protocol Validation: uses tokens (evidence: `lib/extension.js`)
- Message Compression → Buffer Utilities: joins buffers (evidence: `lib/permessage-deflate.js`)
- Message Compression → Zlib Limiter: limits concurrency (evidence: `lib/permessage-deflate.js`)
- WebSocket API → Event Target: exposes events (evidence: `lib/websocket.js`)
- WebSocket API → Stream Adapter: adapts connection (evidence: `lib/stream.js`)
- WebSocket API → Extension Negotiation: uses extensions (evidence: `lib/websocket.js`)
