# shdwofm/music-bot architecture

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

## Overview

This Telegram bot accepts a streaming-service track URL, queries Odesli for cross-platform matches, excludes the source platform, and replies with formatted links. The main flow is split between Telegram handling in `bot.py` and conversion logic in `link_converter.py`; the latter detects the source, performs the API request, and selects available results. README-documented platform coverage is represented by the converter’s supported-platform stage. The shown source establishes these calls; Telegram transport behavior is represented by its polling and message handlers.

Main entry points: [`link_converter.py`](https://github.com/shdwofm/music-bot/blob/main/link_converter.py) (Link converter), [`bot.py`](https://github.com/shdwofm/music-bot/blob/main/bot.py) (Message handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram interaction"]
  node_handler["Message handlers<br/>[bot.py]"]
  node_presentation["Reply formatting<br/>[bot.py]"]
end

subgraph group_conversion["Link conversion"]
  node_converter["Link converter<br/>[link_converter.py]"]
  node_source_detection["Source detection<br/>[link_converter.py]"]
  node_platform_selection["Platform selection<br/>[link_converter.py]"]
end

subgraph group_services["External services"]
  node_telegram_api["Telegram API"]
  node_odesli["Odesli API"]
end

node_user(("Telegram user"))

node_user -->|"sends URL"| node_handler
node_handler -->|"requests links"| node_converter
node_converter -->|"detects source"| node_source_detection
node_converter -->|"requests matches"| node_odesli
node_converter -->|"filters results"| node_platform_selection
node_converter -->|"returns links"| node_handler
node_handler -->|"formats links"| node_presentation
node_handler -->|"polls and replies"| node_telegram_api
node_presentation -->|"sends results"| node_user

click node_handler "https://github.com/shdwofm/music-bot/blob/main/bot.py"
click node_presentation "https://github.com/shdwofm/music-bot/blob/main/bot.py"
click node_converter "https://github.com/shdwofm/music-bot/blob/main/link_converter.py"
click node_source_detection "https://github.com/shdwofm/music-bot/blob/main/link_converter.py"
click node_platform_selection "https://github.com/shdwofm/music-bot/blob/main/link_converter.py"

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_handler,node_presentation,node_user toneBlue
class node_converter,node_source_detection,node_platform_selection toneAmber
class node_telegram_api,node_odesli toneMint
```

## Components

### Telegram interaction

- [Message handlers](https://github.com/shdwofm/music-bot/blob/main/bot.py): `bot.py`
- [Reply formatting](https://github.com/shdwofm/music-bot/blob/main/bot.py): `bot.py`

### Link conversion

- [Link converter](https://github.com/shdwofm/music-bot/blob/main/link_converter.py): `link_converter.py`
- [Source detection](https://github.com/shdwofm/music-bot/blob/main/link_converter.py): `link_converter.py`
- [Platform selection](https://github.com/shdwofm/music-bot/blob/main/link_converter.py): `link_converter.py`

### External services

- **Telegram API**
- **Odesli API**

### Other components

- **Telegram user**

## Connections

- Telegram user → Message handlers: sends URL (evidence: `bot.py`)
- Message handlers → Link converter: requests links (evidence: `bot.py`)
- Link converter → Source detection: detects source (evidence: `link_converter.py`)
- Link converter → Odesli API: requests matches (evidence: `link_converter.py`)
- Link converter → Platform selection: filters results (evidence: `link_converter.py`)
- Link converter → Message handlers: returns links (evidence: `bot.py`)
- Message handlers → Reply formatting: formats links (evidence: `bot.py`)
- Message handlers → Telegram API: polls and replies (evidence: `bot.py`)
- Reply formatting → Telegram user: sends results (evidence: `bot.py`)
