# krau/saveany-bot architecture

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

- Interactive diagram: https://gitdiagram.com/krau/saveany-bot
- Repository: https://github.com/krau/saveany-bot

## Overview

Save Any Bot accepts Telegram messages and API requests, turns selected files, links, or transfer requests into tasks, and saves the resulting content to configured storage. The main stages are request handling, task execution or parsing/downloading, and storage upload; Telegram watching and the HTTP API are additional entry points. Storage backends are registered behind a shared interface. The README documents capabilities whose implementation was not sampled; edges based on it are identified accordingly, and unsampled internals are not inferred.

Main entry points: [`core/tasks`](https://github.com/krau/saveany-bot/tree/main/core/tasks) (Task engines), [`core/core.go`](https://github.com/krau/saveany-bot/blob/main/core/core.go) (Task coordinator), [`storage/storage.go`](https://github.com/krau/saveany-bot/blob/main/storage/storage.go) (Storage registry), [`client/bot/handlers`](https://github.com/krau/saveany-bot/tree/main/client/bot/handlers) (Bot handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_bot["Bot handlers"]
  node_watcher["Chat watcher<br/>[watch.go]"]
  node_http_api["HTTP API<br/>[handlers.go]"]
  node_api_server["API server<br/>[server.go]"]
end

subgraph group_tasks["Task processing"]
  node_task_core["Task coordinator<br/>[core.go]"]
  node_task_engines["Task engines"]
  node_parsers["Site parsers<br/>[parser.go]"]
  node_aria2["Aria2 downloader<br/>[client.go]"]
  node_ytdlp["yt-dlp downloads"]
  node_telegraph["Telegraph handling"]
end

subgraph group_storage["Storage"]
  node_storage_registry["Storage registry<br/>[storage.go]"]
  node_local_storage["Local storage<br/>[local.go]"]
  node_cloud_storage["Cloud backends<br/>[alist.go]"]
  node_telegram_storage["Telegram storage<br/>[telegram.go]"]
end

subgraph group_platform["Configuration and state"]
  node_database[("Persistent data<br/>[db.go]")]
  node_config["Configuration"]
end

node_telegram_user(("Telegram user"))
node_api_caller(("API caller"))
node_telegram_service(("Telegram"))
node_websites(("Websites and URLs"))
node_storage_services(("Storage services"))

node_telegram_user -->|"sends requests"| node_bot
node_bot -.->|"submits tasks"| node_task_core
node_telegram_user -.->|"posts media"| node_watcher
node_watcher -.->|"auto-saves"| node_task_core
node_api_caller -->|"sends requests"| node_api_server
node_api_server -->|"routes requests"| node_http_api
node_http_api -->|"creates tasks"| node_task_core
node_bot -->|"cancels tasks"| node_task_core
node_task_core -.->|"dispatches tasks"| node_task_engines
node_task_engines -.->|"saves results"| node_storage_registry
node_task_engines -.->|"parses links"| node_parsers
node_task_engines -.->|"downloads URLs"| node_aria2
node_task_engines -.->|"downloads media"| node_ytdlp
node_task_engines -.->|"handles pages"| node_telegraph
node_storage_registry -->|"constructs backend"| node_local_storage
node_storage_registry -->|"constructs backend"| node_cloud_storage
node_storage_registry -->|"constructs backend"| node_telegram_storage
node_local_storage -.->|"writes files"| node_storage_services
node_cloud_storage -.->|"writes files"| node_storage_services
node_telegram_storage -->|"uploads media"| node_telegram_service
node_parsers -.->|"fetches content"| node_websites
node_config -->|"configures backends"| node_storage_registry
node_task_core -.->|"uses task state"| node_database

click node_bot "https://github.com/krau/saveany-bot/tree/main/client/bot/handlers"
click node_watcher "https://github.com/krau/saveany-bot/blob/main/client/user/watch.go"
click node_http_api "https://github.com/krau/saveany-bot/blob/main/api/handlers.go"
click node_api_server "https://github.com/krau/saveany-bot/blob/main/api/server.go"
click node_task_core "https://github.com/krau/saveany-bot/blob/main/core/core.go"
click node_task_engines "https://github.com/krau/saveany-bot/tree/main/core/tasks"
click node_parsers "https://github.com/krau/saveany-bot/blob/main/parsers/parser.go"
click node_aria2 "https://github.com/krau/saveany-bot/blob/main/pkg/aria2/client.go"
click node_ytdlp "https://github.com/krau/saveany-bot/tree/main/core/tasks/ytdlp"
click node_telegraph "https://github.com/krau/saveany-bot/tree/main/core/tasks/telegraph"
click node_storage_registry "https://github.com/krau/saveany-bot/blob/main/storage/storage.go"
click node_local_storage "https://github.com/krau/saveany-bot/blob/main/storage/local/local.go"
click node_cloud_storage "https://github.com/krau/saveany-bot/blob/main/storage/alist/alist.go"
click node_telegram_storage "https://github.com/krau/saveany-bot/blob/main/storage/telegram/telegram.go"
click node_database "https://github.com/krau/saveany-bot/blob/main/database/db.go"
click node_config "https://github.com/krau/saveany-bot/tree/main/config"

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_bot,node_watcher,node_http_api,node_api_server,node_telegram_user toneBlue
class node_task_core,node_task_engines,node_parsers,node_aria2,node_ytdlp,node_telegraph,node_storage_services toneAmber
class node_storage_registry,node_local_storage,node_cloud_storage,node_telegram_storage,node_api_caller toneMint
class node_database,node_config toneRose
class node_telegram_service,node_websites toneIndigo
```

## Components

### Entry points

- [Bot handlers](https://github.com/krau/saveany-bot/tree/main/client/bot/handlers): `client/bot/handlers`
- [Chat watcher](https://github.com/krau/saveany-bot/blob/main/client/user/watch.go): `client/user/watch.go`
- [HTTP API](https://github.com/krau/saveany-bot/blob/main/api/handlers.go): `api/handlers.go`
- [API server](https://github.com/krau/saveany-bot/blob/main/api/server.go): `api/server.go`

### Task processing

- [Task coordinator](https://github.com/krau/saveany-bot/blob/main/core/core.go): `core/core.go`
- [Task engines](https://github.com/krau/saveany-bot/tree/main/core/tasks): `core/tasks`
- [Site parsers](https://github.com/krau/saveany-bot/blob/main/parsers/parser.go): `parsers/parser.go`
- [Aria2 downloader](https://github.com/krau/saveany-bot/blob/main/pkg/aria2/client.go): `pkg/aria2/client.go`
- [yt-dlp downloads](https://github.com/krau/saveany-bot/tree/main/core/tasks/ytdlp): `core/tasks/ytdlp`
- [Telegraph handling](https://github.com/krau/saveany-bot/tree/main/core/tasks/telegraph): `core/tasks/telegraph`

### Storage

- [Storage registry](https://github.com/krau/saveany-bot/blob/main/storage/storage.go): `storage/storage.go`
- [Local storage](https://github.com/krau/saveany-bot/blob/main/storage/local/local.go): `storage/local/local.go`
- [Cloud backends](https://github.com/krau/saveany-bot/blob/main/storage/alist/alist.go): `storage/alist/alist.go`
- [Telegram storage](https://github.com/krau/saveany-bot/blob/main/storage/telegram/telegram.go): `storage/telegram/telegram.go`

### Configuration and state

- [Persistent data](https://github.com/krau/saveany-bot/blob/main/database/db.go): `database/db.go`
- [Configuration](https://github.com/krau/saveany-bot/tree/main/config): `config`

### Other components

- **Telegram user**
- **API caller**
- **Telegram**
- **Websites and URLs**
- **Storage services**

## Connections

- Telegram user → Bot handlers: sends requests
- Bot handlers → Task coordinator: submits tasks
- Telegram user → Chat watcher: posts media
- Chat watcher → Task coordinator: auto-saves
- API caller → API server: sends requests (evidence: `api/server.go`)
- API server → HTTP API: routes requests (evidence: `api/server.go`)
- HTTP API → Task coordinator: creates tasks (evidence: `api/handlers.go`)
- Bot handlers → Task coordinator: cancels tasks (evidence: `client/bot/handlers/tasks.go`)
- Task coordinator → Task engines: dispatches tasks
- Task engines → Storage registry: saves results
- Task engines → Site parsers: parses links
- Task engines → Aria2 downloader: downloads URLs
- Task engines → yt-dlp downloads: downloads media
- Task engines → Telegraph handling: handles pages
- Storage registry → Local storage: constructs backend (evidence: `storage/storage.go`)
- Storage registry → Cloud backends: constructs backend (evidence: `storage/storage.go`)
- Storage registry → Telegram storage: constructs backend (evidence: `storage/storage.go`)
- Local storage → Storage services: writes files
- Cloud backends → Storage services: writes files
- Telegram storage → Telegram: uploads media (evidence: `storage/telegram/telegram.go`)
- Site parsers → Websites and URLs: fetches content
- Configuration → Storage registry: configures backends (evidence: `storage/storage.go`)
- Task coordinator → Persistent data: uses task state
