# acharyasoumya02/telegram-music-addon-main architecture

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

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

## Overview

This is a self-hosted BitChord music-provider addon: a private Telegram channel is the library, and BitChord resolves tracks through the addon before requesting byte-range audio. The main runtime is concentrated in `index.js`, which handles channel indexing, metadata, matching, caching, and HTTP endpoints; `downloader.js` supports channel search and imports from MusicsHunters. The README documents additional deduplication, Atmos detection, and chatter-cleaning capabilities. Excerpts are partial, so some subsystem links are documented rather than verified in source.

Main entry points: [`index.js`](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js) (HTTP API), [`downloader.js`](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/downloader.js) (Channel Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client_api["BitChord API"]
  node_http_api["HTTP API<br/>[index.js]"]
  node_track_search["Track Search<br/>[index.js]"]
  node_isrc_lookup["ISRC Lookup<br/>[index.js]"]
  node_stream_resolution["Stream Resolution<br/>[index.js]"]
end

subgraph group_library_runtime["Library and Playback"]
  node_audio_delivery["Range Audio<br/>[index.js]"]
  node_telegram_library[("Telegram Library")]
  node_library_index["Library Index<br/>[index.js]"]
  node_metadata_atmos["Metadata and Atmos<br/>[index.js]"]
  node_preamble_cache["Preamble Cache<br/>[index.js]"]
end

subgraph group_channel_tools["Channel Tools"]
  node_channel_listener["Channel Listener<br/>[index.js]"]
  node_dedup_cleanup["Dedup and Cleanup<br/>[index.js]"]
end

subgraph group_search_import["Search and Import"]
  node_music_search["Channel Search<br/>[downloader.js]"]
  node_picker_download["Picker and Download<br/>[downloader.js]"]
end

node_bitchord(("BitChord"))
node_musicshunters(("MusicsHunters Bot"))
node_telegram_user(("Channel User"))

node_bitchord -->|"requests endpoints"| node_http_api
node_http_api -->|"routes search"| node_track_search
node_http_api -->|"routes ISRC"| node_isrc_lookup
node_http_api -->|"routes stream"| node_stream_resolution
node_track_search -->|"matches tracks"| node_library_index
node_track_search -->|"prewarms match"| node_preamble_cache
node_isrc_lookup -.->|"resolves recording"| node_library_index
node_stream_resolution -->|"finds track"| node_library_index
node_stream_resolution -->|"provides audio URL"| node_audio_delivery
node_audio_delivery -->|"reads byte ranges"| node_telegram_library
node_audio_delivery -->|"serves cached start"| node_preamble_cache
node_telegram_user -->|"uploads audio"| node_telegram_library
node_telegram_library -.->|"delivers channel events"| node_channel_listener
node_channel_listener -->|"parses audio"| node_metadata_atmos
node_metadata_atmos -->|"indexes metadata"| node_library_index
node_channel_listener -->|"checks duplicates"| node_dedup_cleanup
node_dedup_cleanup -->|"deletes duplicates"| node_telegram_library
node_telegram_user -->|"sends search command"| node_music_search
node_music_search -->|"searches bot"| node_musicshunters
node_music_search -->|"opens picker"| node_picker_download
node_picker_download -->|"requests selected audio"| node_musicshunters
node_picker_download -->|"forwards audio"| node_telegram_library

click node_http_api "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js"
click node_track_search "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js"
click node_isrc_lookup "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js"
click node_stream_resolution "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js"
click node_audio_delivery "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js"
click node_library_index "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js"
click node_metadata_atmos "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js"
click node_preamble_cache "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js"
click node_channel_listener "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js"
click node_dedup_cleanup "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js"
click node_music_search "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/downloader.js"
click node_picker_download "https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/downloader.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_http_api,node_track_search,node_isrc_lookup,node_stream_resolution,node_telegram_user toneBlue
class node_audio_delivery,node_telegram_library,node_library_index,node_metadata_atmos,node_preamble_cache toneAmber
class node_channel_listener,node_dedup_cleanup toneMint
class node_music_search,node_picker_download toneRose
class node_bitchord,node_musicshunters toneIndigo
```

## Components

### BitChord API

- [HTTP API](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js): `index.js`
- [Track Search](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js): `index.js`
- [ISRC Lookup](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js): `index.js`
- [Stream Resolution](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js): `index.js`

### Library and Playback

- [Range Audio](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js): `index.js`
- **Telegram Library**
- [Library Index](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js): `index.js`
- [Metadata and Atmos](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js): `index.js`
- [Preamble Cache](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js): `index.js`

### Channel Tools

- [Channel Listener](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js): `index.js`
- [Dedup and Cleanup](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/index.js): `index.js`

### Search and Import

- [Channel Search](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/downloader.js): `downloader.js`
- [Picker and Download](https://github.com/acharyasoumya02/telegram-music-addon-main/blob/main/downloader.js): `downloader.js`

### Other components

- **BitChord**
- **MusicsHunters Bot**
- **Channel User**

## Connections

- BitChord → HTTP API: requests endpoints (evidence: `README.md`)
- HTTP API → Track Search: routes search (evidence: `index.js`)
- HTTP API → ISRC Lookup: routes ISRC (evidence: `index.js`)
- HTTP API → Stream Resolution: routes stream (evidence: `index.js`)
- Track Search → Library Index: matches tracks (evidence: `index.js`)
- Track Search → Preamble Cache: prewarms match (evidence: `index.js`)
- ISRC Lookup → Library Index: resolves recording (evidence: `index.js`)
- Stream Resolution → Library Index: finds track (evidence: `index.js`)
- Stream Resolution → Range Audio: provides audio URL (evidence: `README.md`)
- Range Audio → Telegram Library: reads byte ranges (evidence: `README.md`)
- Range Audio → Preamble Cache: serves cached start (evidence: `index.js`)
- Channel User → Telegram Library: uploads audio (evidence: `README.md`)
- Telegram Library → Channel Listener: delivers channel events
- Channel Listener → Metadata and Atmos: parses audio (evidence: `README.md`)
- Metadata and Atmos → Library Index: indexes metadata (evidence: `README.md`)
- Channel Listener → Dedup and Cleanup: checks duplicates (evidence: `README.md`)
- Dedup and Cleanup → Telegram Library: deletes duplicates (evidence: `README.md`)
- Channel User → Channel Search: sends search command (evidence: `README.md`)
- Channel Search → MusicsHunters Bot: searches bot (evidence: `downloader.js`)
- Channel Search → Picker and Download: opens picker (evidence: `downloader.js`)
- Picker and Download → MusicsHunters Bot: requests selected audio (evidence: `downloader.js`)
- Picker and Download → Telegram Library: forwards audio (evidence: `downloader.js`)