# imnotshashwat/telegram-music-addon architecture

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

- Interactive diagram: https://gitdiagram.com/imnotshashwat/telegram-music-addon
- Repository: https://github.com/imnotshashwat/telegram-music-addon

## Overview

Telegram Music Addon is a self-hosted BitChord provider that indexes audio in a private Telegram channel and serves it directly, including range-based playback and WebDAV. The main playback path is BitChord request → track lookup → Telegram-backed audio stream. A separate setup flow authorizes Telegram, selects a channel, and configures network access. Several capabilities are documented but their implementations were not excerpted; those links rely on README evidence, and unsampled details are not inferred.

Main entry points: [`index.js`](https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js) (Track catalog and index), [`setup-api.js`](https://github.com/imnotshashwat/telegram-music-addon/blob/main/setup-api.js) (Setup API), [`setup.js`](https://github.com/imnotshashwat/telegram-music-addon/blob/main/setup.js) (Terminal setup), [`login.js`](https://github.com/imnotshashwat/telegram-music-addon/blob/main/login.js) (Telegram login)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Configuration"]
  node_setup_ui["Web setup wizard<br/>[setup.js]"]
  node_setup_api["Setup API<br/>[setup-api.js]"]
  node_cli_setup["Terminal setup<br/>[setup.js]"]
  node_login["Telegram login<br/>[login.js]"]
  node_env["Runtime configuration<br/>[setup-api.js]"]
  node_qr["Setup QR code<br/>[setup-api.js]"]
end

subgraph group_library["Library and upkeep"]
  node_catalog["Track catalog and index<br/>[index.js]"]
  node_metadata["Audio metadata parsing<br/>[index.js]"]
  node_dedupe["Duplicate management<br/>[index.js]"]
  node_chat_cleaner["Chat cleaner<br/>[index.js]"]
  node_cache[("LRU and preamble cache<br/>[index.js]")]
end

subgraph group_delivery["Playback delivery"]
  node_search["Search and ISRC lookup<br/>[index.js]"]
  node_manifest["Addon manifest<br/>[index.js]"]
  node_audio["Range audio streaming<br/>[index.js]"]
  node_webdav["WebDAV server<br/>[index.js]"]
end

subgraph group_access["Remote access"]
  node_tunnel["Cloudflare tunnel<br/>[tunnel.js]"]
end

node_user(("Addon operator"))
node_bitchord(("BitChord player"))
node_telegram["Telegram MTProto"]
node_channel[("Private audio channel")]

node_user -->|"configures"| node_setup_ui
node_setup_ui -->|"calls setup endpoints"| node_setup_api
node_setup_api -->|"reads and writes"| node_env
node_setup_api -->|"authorizes and resolves"| node_telegram
node_setup_api -->|"starts tunnel"| node_tunnel
node_setup_api -->|"generates QR"| node_qr
node_user -->|"configures"| node_cli_setup
node_cli_setup -->|"logs in and selects channel"| node_telegram
node_cli_setup -->|"writes settings"| node_env
node_cli_setup -->|"starts tunnel"| node_tunnel
node_user -->|"authorizes account"| node_login
node_login -->|"creates session"| node_telegram
node_login -->|"saves credentials"| node_env
node_channel -->|"stores audio"| node_telegram
node_telegram -->|"provides channel media"| node_catalog
node_catalog -->|"parses track files"| node_metadata
node_metadata -->|"builds search index"| node_catalog
node_catalog -->|"checks duplicates"| node_dedupe
node_catalog -->|"maintains channel"| node_chat_cleaner
node_catalog -->|"caches metadata and preambles"| node_cache
node_bitchord -->|"requests manifest"| node_manifest
node_bitchord -->|"searches tracks"| node_search
node_search -->|"looks up tracks"| node_catalog
node_bitchord -->|"requests audio ranges"| node_audio
node_audio -->|"resolves track"| node_catalog
node_audio -->|"reads preamble cache"| node_cache
node_audio -->|"downloads audio ranges"| node_telegram
node_bitchord -->|"uses WebDAV"| node_webdav
node_webdav -->|"resolves media files"| node_catalog
node_webdav -->|"streams channel media"| node_telegram
node_tunnel -.->|"exposes HTTPS access"| node_bitchord

click node_setup_ui "https://github.com/imnotshashwat/telegram-music-addon/blob/main/public/setup.js"
click node_setup_api "https://github.com/imnotshashwat/telegram-music-addon/blob/main/setup-api.js"
click node_cli_setup "https://github.com/imnotshashwat/telegram-music-addon/blob/main/setup.js"
click node_login "https://github.com/imnotshashwat/telegram-music-addon/blob/main/login.js"
click node_env "https://github.com/imnotshashwat/telegram-music-addon/blob/main/setup-api.js"
click node_catalog "https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js"
click node_metadata "https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js"
click node_dedupe "https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js"
click node_chat_cleaner "https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js"
click node_cache "https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js"
click node_search "https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js"
click node_manifest "https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js"
click node_audio "https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js"
click node_webdav "https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js"
click node_tunnel "https://github.com/imnotshashwat/telegram-music-addon/blob/main/tunnel.js"
click node_qr "https://github.com/imnotshashwat/telegram-music-addon/blob/main/setup-api.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_setup_ui,node_setup_api,node_cli_setup,node_login,node_env,node_qr toneBlue
class node_catalog,node_metadata,node_dedupe,node_chat_cleaner,node_cache,node_channel toneAmber
class node_search,node_manifest,node_audio,node_webdav toneMint
class node_tunnel toneRose
class node_user,node_bitchord,node_telegram toneIndigo
```

## Components

### Configuration

- [Web setup wizard](https://github.com/imnotshashwat/telegram-music-addon/blob/main/public/setup.js): `public/setup.js`
- [Setup API](https://github.com/imnotshashwat/telegram-music-addon/blob/main/setup-api.js): `setup-api.js`
- [Terminal setup](https://github.com/imnotshashwat/telegram-music-addon/blob/main/setup.js): `setup.js`
- [Telegram login](https://github.com/imnotshashwat/telegram-music-addon/blob/main/login.js): `login.js`
- [Runtime configuration](https://github.com/imnotshashwat/telegram-music-addon/blob/main/setup-api.js): `setup-api.js`
- [Setup QR code](https://github.com/imnotshashwat/telegram-music-addon/blob/main/setup-api.js): `setup-api.js`

### Library and upkeep

- [Track catalog and index](https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js): `index.js`
- [Audio metadata parsing](https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js): `index.js`
- [Duplicate management](https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js): `index.js`
- [Chat cleaner](https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js): `index.js`
- [LRU and preamble cache](https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js): `index.js`

### Playback delivery

- [Search and ISRC lookup](https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js): `index.js`
- [Addon manifest](https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js): `index.js`
- [Range audio streaming](https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js): `index.js`
- [WebDAV server](https://github.com/imnotshashwat/telegram-music-addon/blob/main/index.js): `index.js`

### Remote access

- [Cloudflare tunnel](https://github.com/imnotshashwat/telegram-music-addon/blob/main/tunnel.js): `tunnel.js`

### Other components

- **Addon operator**
- **BitChord player**
- **Telegram MTProto**
- **Private audio channel**

## Connections

- Addon operator → Web setup wizard: configures (evidence: `README.md`)
- Web setup wizard → Setup API: calls setup endpoints (evidence: `public/setup.js`)
- Setup API → Runtime configuration: reads and writes (evidence: `setup-api.js`)
- Setup API → Telegram MTProto: authorizes and resolves (evidence: `setup-api.js`)
- Setup API → Cloudflare tunnel: starts tunnel (evidence: `setup-api.js`)
- Setup API → Setup QR code: generates QR (evidence: `setup-api.js`)
- Addon operator → Terminal setup: configures (evidence: `README.md`)
- Terminal setup → Telegram MTProto: logs in and selects channel (evidence: `setup.js`)
- Terminal setup → Runtime configuration: writes settings (evidence: `setup.js`)
- Terminal setup → Cloudflare tunnel: starts tunnel (evidence: `setup.js`)
- Addon operator → Telegram login: authorizes account (evidence: `login.js`)
- Telegram login → Telegram MTProto: creates session (evidence: `login.js`)
- Telegram login → Runtime configuration: saves credentials (evidence: `login.js`)
- Private audio channel → Telegram MTProto: stores audio (evidence: `README.md`)
- Telegram MTProto → Track catalog and index: provides channel media (evidence: `README.md`)
- Track catalog and index → Audio metadata parsing: parses track files (evidence: `README.md`)
- Audio metadata parsing → Track catalog and index: builds search index (evidence: `README.md`)
- Track catalog and index → Duplicate management: checks duplicates (evidence: `README.md`)
- Track catalog and index → Chat cleaner: maintains channel (evidence: `README.md`)
- Track catalog and index → LRU and preamble cache: caches metadata and preambles (evidence: `index.js`)
- BitChord player → Addon manifest: requests manifest (evidence: `README.md`)
- BitChord player → Search and ISRC lookup: searches tracks (evidence: `README.md`)
- Search and ISRC lookup → Track catalog and index: looks up tracks (evidence: `README.md`)
- BitChord player → Range audio streaming: requests audio ranges (evidence: `README.md`)
- Range audio streaming → Track catalog and index: resolves track (evidence: `index.js`)
- Range audio streaming → LRU and preamble cache: reads preamble cache (evidence: `index.js`)
- Range audio streaming → Telegram MTProto: downloads audio ranges (evidence: `README.md`)
- BitChord player → WebDAV server: uses WebDAV (evidence: `README.md`)
- WebDAV server → Track catalog and index: resolves media files (evidence: `README.md`)
- WebDAV server → Telegram MTProto: streams channel media (evidence: `README.md`)
- Cloudflare tunnel → BitChord player: exposes HTTPS access (evidence: `README.md`)
