# soul7hu/walrus architecture

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

- Interactive diagram: https://gitdiagram.com/soul7hu/walrus
- Repository: https://github.com/soul7hu/walrus

## Overview

Walrus is a Telegram-controlled transfer bot: users submit Telegram files or direct links, the bot downloads and queues them, and a separate worker uploads them to a chosen Rubika destination. The queue and task files persist transfer state shared across the processes. The README documents account setup, destination selection, retries, cancellation, progress, cleanup, and large-file archive volumes. Some implementation details are unsampled, so undocumented wiring is omitted.

Main entry points: [`telegram_bot.py`](https://github.com/soul7hu/walrus/blob/main/telegram_bot.py) (Bot controls), [`task_store.py`](https://github.com/soul7hu/walrus/blob/main/task_store.py) (Queue and task state), [`rubika_worker.py`](https://github.com/soul7hu/walrus/blob/main/rubika_worker.py) (Upload worker), [`rubika_auth_helper.py`](https://github.com/soul7hu/walrus/blob/main/rubika_auth_helper.py) (Rubika account setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Telegram Intake"]
  node_bot["Bot controls<br/>[telegram_bot.py]"]
  node_tgfiles["Telegram files<br/>[telegram_bot.py]"]
  node_linkdownload["Direct-link download<br/>[telegram_bot.py]"]
  node_batch["Link batches<br/>[telegram_bot.py]"]
end

subgraph group_transfer["Transfer Processing"]
  node_worker["Upload worker<br/>[rubika_worker.py]"]
  node_archive["Volume archiving<br/>[rubika_worker.py]"]
  node_progress["Progress and retry<br/>[rubika_worker.py]"]
  node_cleanup["Cleanup and recovery<br/>[telegram_bot.py]"]
end

subgraph group_state["Task State"]
  node_taskstore[("Queue and task state<br/>[task_store.py]")]
  node_localfiles["Downloaded files<br/>[task_store.py]"]
end

subgraph group_rubika["Rubika Integration"]
  node_auth["Rubika account setup"]
  node_destination["Destination settings<br/>[telegram_bot.py]"]
end

node_user(("Telegram user"))
node_rubikaapi{{"Rubika service"}}
node_telegramapi{{"Telegram service"}}
node_sevenzip{{"7-Zip"}}

node_user -->|"submits commands"| node_bot
node_bot -->|"accepts files"| node_tgfiles
node_bot -->|"downloads links"| node_linkdownload
node_bot -->|"queues links"| node_batch
node_tgfiles -->|"queues tasks"| node_taskstore
node_linkdownload -->|"queues tasks"| node_taskstore
node_batch -->|"queues tasks"| node_taskstore
node_linkdownload -->|"writes downloads"| node_localfiles
node_taskstore -->|"tracks paths"| node_localfiles
node_worker -->|"reads queue"| node_taskstore
node_worker -->|"reads task files"| node_localfiles
node_worker -->|"prepares volumes"| node_archive
node_archive -->|"runs archives"| node_sevenzip
node_worker -->|"updates transfers"| node_progress
node_worker -->|"uploads files"| node_rubikaapi
node_worker -->|"sends updates"| node_telegramapi
node_bot -->|"handles bot UI"| node_telegramapi
node_bot -->|"manages transfer state"| node_taskstore
node_bot -->|"offers cleanup"| node_cleanup
node_cleanup -->|"removes safe files"| node_localfiles
node_bot -->|"changes destination"| node_destination
node_destination -->|"saves settings"| node_taskstore
node_user -.->|"provides login details"| node_auth
node_auth -.->|"authenticates account"| node_rubikaapi
node_progress -.->|"records outcomes"| node_taskstore

click node_bot "https://github.com/soul7hu/walrus/blob/main/telegram_bot.py"
click node_tgfiles "https://github.com/soul7hu/walrus/blob/main/telegram_bot.py"
click node_linkdownload "https://github.com/soul7hu/walrus/blob/main/telegram_bot.py"
click node_batch "https://github.com/soul7hu/walrus/blob/main/telegram_bot.py"
click node_taskstore "https://github.com/soul7hu/walrus/blob/main/task_store.py"
click node_localfiles "https://github.com/soul7hu/walrus/blob/main/task_store.py"
click node_worker "https://github.com/soul7hu/walrus/blob/main/rubika_worker.py"
click node_archive "https://github.com/soul7hu/walrus/blob/main/rubika_worker.py"
click node_progress "https://github.com/soul7hu/walrus/blob/main/rubika_worker.py"
click node_cleanup "https://github.com/soul7hu/walrus/blob/main/telegram_bot.py"
click node_auth "https://github.com/soul7hu/walrus/blob/main/rubika_auth_helper.py"
click node_destination "https://github.com/soul7hu/walrus/blob/main/telegram_bot.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_bot,node_tgfiles,node_linkdownload,node_batch,node_user toneBlue
class node_worker,node_archive,node_progress,node_cleanup toneAmber
class node_taskstore,node_localfiles toneMint
class node_auth,node_destination toneRose
class node_rubikaapi,node_telegramapi,node_sevenzip toneIndigo
```

## Components

### Telegram Intake

- [Bot controls](https://github.com/soul7hu/walrus/blob/main/telegram_bot.py): `telegram_bot.py`
- [Telegram files](https://github.com/soul7hu/walrus/blob/main/telegram_bot.py): `telegram_bot.py`
- [Direct-link download](https://github.com/soul7hu/walrus/blob/main/telegram_bot.py): `telegram_bot.py`
- [Link batches](https://github.com/soul7hu/walrus/blob/main/telegram_bot.py): `telegram_bot.py`

### Transfer Processing

- [Upload worker](https://github.com/soul7hu/walrus/blob/main/rubika_worker.py): `rubika_worker.py`
- [Volume archiving](https://github.com/soul7hu/walrus/blob/main/rubika_worker.py): `rubika_worker.py`
- [Progress and retry](https://github.com/soul7hu/walrus/blob/main/rubika_worker.py): `rubika_worker.py`
- [Cleanup and recovery](https://github.com/soul7hu/walrus/blob/main/telegram_bot.py): `telegram_bot.py`

### Task State

- [Queue and task state](https://github.com/soul7hu/walrus/blob/main/task_store.py): `task_store.py`
- [Downloaded files](https://github.com/soul7hu/walrus/blob/main/task_store.py): `task_store.py`

### Rubika Integration

- [Rubika account setup](https://github.com/soul7hu/walrus/blob/main/rubika_auth_helper.py): `rubika_auth_helper.py`
- [Destination settings](https://github.com/soul7hu/walrus/blob/main/telegram_bot.py): `telegram_bot.py`

### Other components

- **Telegram user**
- **Rubika service**
- **Telegram service**
- **7-Zip**

## Connections

- Telegram user → Bot controls: submits commands (evidence: `README.md`)
- Bot controls → Telegram files: accepts files (evidence: `README.md`)
- Bot controls → Direct-link download: downloads links (evidence: `telegram_bot.py`)
- Bot controls → Link batches: queues links (evidence: `README.md`)
- Telegram files → Queue and task state: queues tasks (evidence: `README.md`)
- Direct-link download → Queue and task state: queues tasks (evidence: `README.md`)
- Link batches → Queue and task state: queues tasks (evidence: `README.md`)
- Direct-link download → Downloaded files: writes downloads (evidence: `telegram_bot.py`)
- Queue and task state → Downloaded files: tracks paths (evidence: `task_store.py`)
- Upload worker → Queue and task state: reads queue (evidence: `rubika_worker.py`)
- Upload worker → Downloaded files: reads task files (evidence: `rubika_worker.py`)
- Upload worker → Volume archiving: prepares volumes (evidence: `rubika_worker.py`)
- Volume archiving → 7-Zip: runs archives (evidence: `rubika_worker.py`)
- Upload worker → Progress and retry: updates transfers (evidence: `rubika_worker.py`)
- Upload worker → Rubika service: uploads files (evidence: `README.md`)
- Upload worker → Telegram service: sends updates (evidence: `rubika_worker.py`)
- Bot controls → Telegram service: handles bot UI (evidence: `README.md`)
- Bot controls → Queue and task state: manages transfer state (evidence: `telegram_bot.py`)
- Bot controls → Cleanup and recovery: offers cleanup (evidence: `README.md`)
- Cleanup and recovery → Downloaded files: removes safe files (evidence: `telegram_bot.py`)
- Bot controls → Destination settings: changes destination (evidence: `README.md`)
- Destination settings → Queue and task state: saves settings (evidence: `task_store.py`)
- Telegram user → Rubika account setup: provides login details
- Rubika account setup → Rubika service: authenticates account
- Progress and retry → Queue and task state: records outcomes (evidence: `rubika_worker.py`)
