# subinps/teleplay architecture

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

- Interactive diagram: https://gitdiagram.com/subinps/teleplay
- Repository: https://github.com/subinps/teleplay

## Overview

TelePlay is a Telegram-backed personal media server with a FastAPI backend, browser app, and Android TV/mobile clients. The main workflow is upload through the Telegram bot, organize files in the web or device library, then stream from Telegram on demand; Android mobile also supports offline downloads. The backend provides login, file/folder management, streaming, and TV-specific endpoints, with database metadata and watch progress. README statements establish the product-level flow; source excerpts and the index support selected internal links, but several client and backend modules were not sampled.

Main entry points: [`backend/app/database.py`](https://github.com/subinps/teleplay/blob/main/backend/app/database.py) (Metadata database), [`backend/app/main.py`](https://github.com/subinps/teleplay/blob/main/backend/app/main.py) (API application), [`backend/app/bot.py`](https://github.com/subinps/teleplay/blob/main/backend/app/bot.py) (Telegram bot), [`web/src/App.tsx`](https://github.com/subinps/teleplay/blob/main/web/src/App.tsx) (Web routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Backend platform"]
  node_api_app["API application<br/>[main.py]"]
  node_auth_api["Login API<br/>[auth.py]"]
  node_auth_core["JWT authentication<br/>[auth.py]"]
  node_file_api["File API<br/>[files.py]"]
  node_folder_api["Folder API<br/>[folders.py]"]
  node_stream_api["Streaming API<br/>[streaming.py]"]
  node_tv_api["TV API<br/>[tv.py]"]
  node_streaming["Stream engine<br/>[streaming.py]"]
  node_services["Media queries<br/>[services.py]"]
end

subgraph group_telegram["Telegram integration"]
  node_bot["Telegram bot<br/>[bot.py]"]
  node_telegram_cloud[("Telegram cloud")]
  node_tg_adapter["Telegram adapter<br/>[telegram.py]"]
end

subgraph group_web["Web app"]
  node_web_app["Web routes<br/>[App.tsx]"]
  node_web_browser["File browser<br/>[FileBrowser.tsx]"]
  node_web_api["Web API client<br/>[api.ts]"]
  node_web_player["Web player<br/>[MediaPlayer.tsx]"]
end

subgraph group_android["Android clients"]
  node_android_login["Android login<br/>[AuthRepository.kt]"]
  node_android_api["Android API<br/>[TelePlayApi.kt]"]
  node_android_browse["TV library<br/>[HomeScreen.kt]"]
  node_android_player["TV player<br/>[PlayerScreen.kt]"]
  node_downloader["Offline downloader<br/>[FileDownloader.kt]"]
  node_download_service["Download service<br/>[DownloadService.kt]"]
  node_audio_service["Audio service"]
end

subgraph group_storage["Metadata and state"]
  node_db[("Metadata database<br/>[database.py]")]
  node_models["Media models<br/>[models.py]"]
end

node_user(("User"))

node_user -->|"uploads files"| node_bot
node_bot -->|"stores media"| node_telegram_cloud
node_bot -->|"records metadata"| node_db
node_api_app -->|"initializes"| node_db
node_api_app -->|"starts client"| node_tg_adapter
node_api_app -.->|"mounts routes"| node_auth_api
node_auth_api -->|"validates tokens"| node_auth_core
node_auth_core -->|"loads user"| node_db
node_folder_api -->|"queries folders"| node_db
node_services -->|"queries media"| node_models
node_stream_api -.->|"serves streams"| node_streaming
node_streaming -->|"fetches chunks"| node_telegram_cloud
node_user -->|"opens browser"| node_web_app
node_web_app -->|"routes library"| node_web_browser
node_web_app -->|"requests login"| node_web_api
node_web_browser -->|"requests files"| node_web_api
node_user -->|"signs in"| node_android_login
node_android_login -.->|"authenticates"| node_android_api
node_user -->|"browses library"| node_android_browse
node_user -->|"plays media"| node_android_player
node_android_player -->|"requests stream"| node_stream_api
node_android_browse -.->|"loads library"| node_android_api
node_downloader -->|"observed by"| node_download_service
node_user -->|"downloads offline"| node_downloader

click node_bot "https://github.com/subinps/teleplay/blob/main/backend/app/bot.py"
click node_tg_adapter "https://github.com/subinps/teleplay/blob/main/backend/app/telegram.py"
click node_api_app "https://github.com/subinps/teleplay/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/subinps/teleplay/blob/main/backend/app/routers/auth.py"
click node_auth_core "https://github.com/subinps/teleplay/blob/main/backend/app/auth.py"
click node_file_api "https://github.com/subinps/teleplay/blob/main/backend/app/routers/files.py"
click node_folder_api "https://github.com/subinps/teleplay/blob/main/backend/app/routers/folders.py"
click node_stream_api "https://github.com/subinps/teleplay/blob/main/backend/app/routers/streaming.py"
click node_tv_api "https://github.com/subinps/teleplay/blob/main/backend/app/routers/tv.py"
click node_streaming "https://github.com/subinps/teleplay/blob/main/backend/app/streaming.py"
click node_services "https://github.com/subinps/teleplay/blob/main/backend/app/services.py"
click node_db "https://github.com/subinps/teleplay/blob/main/backend/app/database.py"
click node_models "https://github.com/subinps/teleplay/blob/main/backend/app/models.py"
click node_web_app "https://github.com/subinps/teleplay/blob/main/web/src/App.tsx"
click node_web_browser "https://github.com/subinps/teleplay/blob/main/web/src/components/FileBrowser.tsx"
click node_web_api "https://github.com/subinps/teleplay/blob/main/web/src/lib/api.ts"
click node_web_player "https://github.com/subinps/teleplay/blob/main/web/src/components/MediaPlayer.tsx"
click node_android_login "https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/data/repository/AuthRepository.kt"
click node_android_api "https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/data/api/TelePlayApi.kt"
click node_android_browse "https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/ui/home/HomeScreen.kt"
click node_android_player "https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/ui/player/PlayerScreen.kt"
click node_downloader "https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/download/FileDownloader.kt"
click node_download_service "https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/service/DownloadService.kt"
click node_audio_service "https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/service/AudioPlaybackService.kt"

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_app,node_auth_api,node_auth_core,node_file_api,node_folder_api,node_stream_api,node_tv_api,node_streaming,node_services,node_user toneBlue
class node_bot,node_telegram_cloud,node_tg_adapter toneAmber
class node_web_app,node_web_browser,node_web_api,node_web_player toneMint
class node_android_login,node_android_api,node_android_browse,node_android_player,node_downloader,node_download_service,node_audio_service toneRose
class node_db,node_models toneIndigo
```

## Components

### Backend platform

- [API application](https://github.com/subinps/teleplay/blob/main/backend/app/main.py): `backend/app/main.py`
- [Login API](https://github.com/subinps/teleplay/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [JWT authentication](https://github.com/subinps/teleplay/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [File API](https://github.com/subinps/teleplay/blob/main/backend/app/routers/files.py): `backend/app/routers/files.py`
- [Folder API](https://github.com/subinps/teleplay/blob/main/backend/app/routers/folders.py): `backend/app/routers/folders.py`
- [Streaming API](https://github.com/subinps/teleplay/blob/main/backend/app/routers/streaming.py): `backend/app/routers/streaming.py`
- [TV API](https://github.com/subinps/teleplay/blob/main/backend/app/routers/tv.py): `backend/app/routers/tv.py`
- [Stream engine](https://github.com/subinps/teleplay/blob/main/backend/app/streaming.py): `backend/app/streaming.py`
- [Media queries](https://github.com/subinps/teleplay/blob/main/backend/app/services.py): `backend/app/services.py`

### Telegram integration

- [Telegram bot](https://github.com/subinps/teleplay/blob/main/backend/app/bot.py): `backend/app/bot.py`
- **Telegram cloud**
- [Telegram adapter](https://github.com/subinps/teleplay/blob/main/backend/app/telegram.py): `backend/app/telegram.py`

### Web app

- [Web routes](https://github.com/subinps/teleplay/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [File browser](https://github.com/subinps/teleplay/blob/main/web/src/components/FileBrowser.tsx): `web/src/components/FileBrowser.tsx`
- [Web API client](https://github.com/subinps/teleplay/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Web player](https://github.com/subinps/teleplay/blob/main/web/src/components/MediaPlayer.tsx): `web/src/components/MediaPlayer.tsx`

### Android clients

- [Android login](https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/data/repository/AuthRepository.kt): `android/app/src/main/java/com/telegramtv/data/repository/AuthRepository.kt`
- [Android API](https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/data/api/TelePlayApi.kt): `android/app/src/main/java/com/telegramtv/data/api/TelePlayApi.kt`
- [TV library](https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/ui/home/HomeScreen.kt): `android/app/src/main/java/com/telegramtv/ui/home/HomeScreen.kt`
- [TV player](https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/ui/player/PlayerScreen.kt): `android/app/src/main/java/com/telegramtv/ui/player/PlayerScreen.kt`
- [Offline downloader](https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/download/FileDownloader.kt): `android/app/src/main/java/com/telegramtv/download/FileDownloader.kt`
- [Download service](https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/service/DownloadService.kt): `android/app/src/main/java/com/telegramtv/service/DownloadService.kt`
- [Audio service](https://github.com/subinps/teleplay/blob/main/android/app/src/main/java/com/telegramtv/service/AudioPlaybackService.kt): `android/app/src/main/java/com/telegramtv/service/AudioPlaybackService.kt`

### Metadata and state

- [Metadata database](https://github.com/subinps/teleplay/blob/main/backend/app/database.py): `backend/app/database.py`
- [Media models](https://github.com/subinps/teleplay/blob/main/backend/app/models.py): `backend/app/models.py`

### Other components

- **User**

## Connections

- User → Telegram bot: uploads files (evidence: `README.md`)
- Telegram bot → Telegram cloud: stores media (evidence: `README.md`)
- Telegram bot → Metadata database: records metadata (evidence: `README.md`)
- API application → Metadata database: initializes (evidence: `backend/app/main.py`)
- API application → Telegram adapter: starts client (evidence: `backend/app/main.py`)
- API application → Login API: mounts routes
- Login API → JWT authentication: validates tokens (evidence: `backend/app/routers/auth.py`)
- JWT authentication → Metadata database: loads user (evidence: `backend/app/auth.py`)
- Folder API → Metadata database: queries folders (evidence: `backend/app/routers/folders.py`)
- Media queries → Media models: queries media (evidence: `backend/app/services.py`)
- Streaming API → Stream engine: serves streams
- Stream engine → Telegram cloud: fetches chunks (evidence: `README.md`)
- User → Web routes: opens browser (evidence: `README.md`)
- Web routes → File browser: routes library (evidence: `web/src/App.tsx`)
- Web routes → Web API client: requests login (evidence: `web/src/App.tsx`)
- File browser → Web API client: requests files (evidence: `web/src/components/FileBrowser.tsx`)
- User → Android login: signs in (evidence: `README.md`)
- Android login → Android API: authenticates
- User → TV library: browses library (evidence: `README.md`)
- User → TV player: plays media (evidence: `README.md`)
- TV player → Streaming API: requests stream (evidence: `README.md`)
- TV library → Android API: loads library
- Offline downloader → Download service: observed by (evidence: `android/app/src/main/java/com/telegramtv/service/DownloadService.kt`)
- User → Offline downloader: downloads offline (evidence: `README.md`)