# unblockneteasemusic/server architecture

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

- Interactive diagram: https://gitdiagram.com/unblockneteasemusic/server
- Repository: https://github.com/unblockneteasemusic/server

## Overview

UnblockNeteaseMusic is a Node.js HTTP/HTTPS proxy that restores unavailable Netease Cloud Music tracks by matching them against alternate music providers. The main flow is client traffic through the proxy and Netease request hook, which invokes provider matching and returns a replacement audio URL; the proxy also supports general traffic forwarding, PAC, authentication, filtering, and relay configuration. Sampled source supports the main runtime calls; provider coverage and several proxy capabilities are documented in the README, while some provider implementations were not sampled.

Main entry points: [`src/server.js`](https://github.com/unblockneteasemusic/server/blob/enhanced/src/server.js) (HTTP/S proxy), [`src/provider`](https://github.com/unblockneteasemusic/server/tree/enhanced/src/provider) (Music source adapters), [`src/request.js`](https://github.com/unblockneteasemusic/server/blob/enhanced/src/request.js) (HTTP request client), [`src/app.js`](https://github.com/unblockneteasemusic/server/blob/enhanced/src/app.js) (Application setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and proxy"]
  node_app["Application setup<br/>[app.js]"]
  node_cli["CLI configuration<br/>[cli.js]"]
  node_proxy["HTTP/S proxy<br/>[server.js]"]
  node_hook["Request interception<br/>[hook.js]"]
end

subgraph group_music["Track matching"]
  node_matcher["Song matching<br/>[match.js]"]
  node_provider_catalog["Provider selection<br/>[consts.js]"]
end

subgraph group_providers["Music providers"]
  node_provider_impl["Music source adapters"]
  node_provider_insure["Relay adapter<br/>[insure.js]"]
end

subgraph group_support["Shared services"]
  node_request["HTTP request client<br/>[request.js]"]
  node_cache[("Cache storage<br/>[cache.js]")]
  node_crypto["Provider cryptography<br/>[crypto.js]"]
  node_kwdes["Kuwo cipher<br/>[kwDES.js]"]
  node_utilities["Request utilities<br/>[utilities.js]"]
  node_logger["Logging<br/>[logger.js]"]
end

node_client(("Music client"))
node_netease(("Netease API"))
node_external_sources(("Alternate music services"))

node_client -->|"sends traffic"| node_proxy
node_app -->|"parses options"| node_cli
node_app -->|"configures and starts"| node_proxy
node_proxy -->|"intercepts requests"| node_hook
node_hook -->|"forwards requests"| node_netease
node_hook -->|"requests replacement"| node_matcher
node_matcher -->|"reads source list"| node_provider_catalog
node_matcher -->|"queries providers"| node_provider_impl
node_provider_impl -->|"searches and retrieves audio"| node_external_sources
node_provider_impl -->|"makes service requests"| node_request
node_provider_impl -->|"caches provider results"| node_cache
node_provider_impl -->|"signs provider requests"| node_crypto
node_provider_insure -->|"calls relay"| node_request
node_matcher -->|"validates audio URL"| node_request
node_hook -->|"decrypts and encrypts payloads"| node_crypto
node_proxy -->|"forwards upstream"| node_request
node_proxy -->|"checks hosts"| node_utilities
node_crypto -->|"loads cipher"| node_kwdes
node_app -->|"schedules cleanup"| node_cache
node_app -->|"queries DNS services"| node_request
node_proxy -->|"logs proxy activity"| node_logger
node_cache -->|"logs cache activity"| node_logger

click node_app "https://github.com/unblockneteasemusic/server/blob/enhanced/src/app.js"
click node_cli "https://github.com/unblockneteasemusic/server/blob/enhanced/src/cli.js"
click node_proxy "https://github.com/unblockneteasemusic/server/blob/enhanced/src/server.js"
click node_hook "https://github.com/unblockneteasemusic/server/blob/enhanced/src/hook.js"
click node_matcher "https://github.com/unblockneteasemusic/server/blob/enhanced/src/provider/match.js"
click node_provider_catalog "https://github.com/unblockneteasemusic/server/blob/enhanced/src/consts.js"
click node_provider_impl "https://github.com/unblockneteasemusic/server/tree/enhanced/src/provider"
click node_provider_insure "https://github.com/unblockneteasemusic/server/blob/enhanced/src/provider/insure.js"
click node_request "https://github.com/unblockneteasemusic/server/blob/enhanced/src/request.js"
click node_cache "https://github.com/unblockneteasemusic/server/blob/enhanced/src/cache.js"
click node_crypto "https://github.com/unblockneteasemusic/server/blob/enhanced/src/crypto.js"
click node_kwdes "https://github.com/unblockneteasemusic/server/blob/enhanced/src/kwDES.js"
click node_utilities "https://github.com/unblockneteasemusic/server/blob/enhanced/src/utilities.js"
click node_logger "https://github.com/unblockneteasemusic/server/blob/enhanced/src/logger.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_cli,node_proxy,node_hook,node_client toneBlue
class node_matcher,node_provider_catalog toneAmber
class node_provider_impl,node_provider_insure,node_netease toneMint
class node_request,node_cache,node_crypto,node_kwdes,node_utilities,node_logger toneRose
class node_external_sources toneIndigo
```

## Components

### Runtime and proxy

- [Application setup](https://github.com/unblockneteasemusic/server/blob/enhanced/src/app.js): `src/app.js`
- [CLI configuration](https://github.com/unblockneteasemusic/server/blob/enhanced/src/cli.js): `src/cli.js`
- [HTTP/S proxy](https://github.com/unblockneteasemusic/server/blob/enhanced/src/server.js): `src/server.js`
- [Request interception](https://github.com/unblockneteasemusic/server/blob/enhanced/src/hook.js): `src/hook.js`

### Track matching

- [Song matching](https://github.com/unblockneteasemusic/server/blob/enhanced/src/provider/match.js): `src/provider/match.js`
- [Provider selection](https://github.com/unblockneteasemusic/server/blob/enhanced/src/consts.js): `src/consts.js`

### Music providers

- [Music source adapters](https://github.com/unblockneteasemusic/server/tree/enhanced/src/provider): `src/provider`
- [Relay adapter](https://github.com/unblockneteasemusic/server/blob/enhanced/src/provider/insure.js): `src/provider/insure.js`

### Shared services

- [HTTP request client](https://github.com/unblockneteasemusic/server/blob/enhanced/src/request.js): `src/request.js`
- [Cache storage](https://github.com/unblockneteasemusic/server/blob/enhanced/src/cache.js): `src/cache.js`
- [Provider cryptography](https://github.com/unblockneteasemusic/server/blob/enhanced/src/crypto.js): `src/crypto.js`
- [Kuwo cipher](https://github.com/unblockneteasemusic/server/blob/enhanced/src/kwDES.js): `src/kwDES.js`
- [Request utilities](https://github.com/unblockneteasemusic/server/blob/enhanced/src/utilities.js): `src/utilities.js`
- [Logging](https://github.com/unblockneteasemusic/server/blob/enhanced/src/logger.js): `src/logger.js`

### Other components

- **Music client**
- **Netease API**
- **Alternate music services**

## Connections

- Music client → HTTP/S proxy: sends traffic
- Application setup → CLI configuration: parses options (evidence: `src/app.js`)
- Application setup → HTTP/S proxy: configures and starts (evidence: `src/app.js`)
- HTTP/S proxy → Request interception: intercepts requests (evidence: `src/server.js`)
- Request interception → Netease API: forwards requests
- Request interception → Song matching: requests replacement (evidence: `src/hook.js`)
- Song matching → Provider selection: reads source list (evidence: `src/provider/match.js`)
- Song matching → Music source adapters: queries providers (evidence: `src/provider/match.js`)
- Music source adapters → Alternate music services: searches and retrieves audio
- Music source adapters → HTTP request client: makes service requests (evidence: `src/provider/bilivideo.js`)
- Music source adapters → Cache storage: caches provider results (evidence: `src/provider/bilivideo.js`)
- Music source adapters → Provider cryptography: signs provider requests (evidence: `src/provider/bilivideo.js`)
- Relay adapter → HTTP request client: calls relay (evidence: `src/provider/insure.js`)
- Song matching → HTTP request client: validates audio URL (evidence: `src/provider/match.js`)
- Request interception → Provider cryptography: decrypts and encrypts payloads (evidence: `src/hook.js`)
- HTTP/S proxy → HTTP request client: forwards upstream (evidence: `src/server.js`)
- HTTP/S proxy → Request utilities: checks hosts (evidence: `src/server.js`)
- Provider cryptography → Kuwo cipher: loads cipher (evidence: `src/crypto.js`)
- Application setup → Cache storage: schedules cleanup (evidence: `src/app.js`)
- Application setup → HTTP request client: queries DNS services (evidence: `src/app.js`)
- HTTP/S proxy → Logging: logs proxy activity (evidence: `src/server.js`)
- Cache storage → Logging: logs cache activity (evidence: `src/cache.js`)
