# samir9156/senpaifilestroring architecture

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

## Overview

Telegram File Store Bot lets admins store files in a private Telegram channel and distribute them through shareable or protected links. Users start a link, pass the Force-Sub check when applicable, and receive copied files with optional timed deletion. Admin workflows also manage channels, batches, buttons, messages, and statistics; an auto-uploader is a separate capability. Edges reflect shown calls or README-documented behavior; unsampled plugin internals are represented without inferred connections.

Main entry points: [`database.py`](https://github.com/samir9156/senpaifilestroring/blob/main/database.py) (Channel JSON DB), [`main.py`](https://github.com/samir9156/senpaifilestroring/blob/main/main.py) (Bot Startup), [`helpers.py`](https://github.com/samir9156/senpaifilestroring/blob/main/helpers.py) (Link Delivery), [`plugins/links.py`](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/links.py) (Link and Batch Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_entry["Bot Startup<br/>[main.py]"]
  node_helpers["Shared Helpers<br/>[helpers.py]"]
end

subgraph group_storage["Configuration and Storage"]
  node_settings["Bot Settings<br/>[config.py]"]
  node_database[("Channel JSON DB<br/>[database.py]")]
end

subgraph group_delivery["Links and Delivery"]
  node_link_admin["Link and Batch Commands<br/>[links.py]"]
  node_link_delivery["Link Delivery<br/>[helpers.py]"]
  node_delete_scheduler["Timed Deletion<br/>[scheduler.py]"]
  node_start_handler["Start Handler<br/>[start.py]"]
  node_batch_finish["Batch Completion<br/>[done.py]"]
end

subgraph group_forcesub["Force-Sub Channels"]
  node_force_admin["Channel Management<br/>[forcesub.py]"]
  node_force_check["Membership Checks<br/>[helpers.py]"]
  node_channel_autodetect["Channel Auto-Detection<br/>[autodetect.py]"]
end

subgraph group_admin_tools["Admin Tools"]
  node_buttons["Post Buttons<br/>[buttons.py]"]
  node_rename_upload["Manual Rename Upload<br/>[rename_upload.py]"]
  node_auto_uploader["Episode Auto-Uploader<br/>[autouploader.py]"]
  node_admin_commands["Admin Controls<br/>[admin.py]"]
  node_message_settings["Custom Messages<br/>[messages.py]"]
  node_statistics["Usage Statistics<br/>[stats.py]"]
end

node_admin(("Admin"))
node_user(("Link User"))
node_telegram["Telegram API"]

node_admin -->|"starts bot"| node_entry
node_entry -->|"reads settings"| node_settings
node_entry -->|"loads database"| node_database
node_entry -->|"starts poller"| node_channel_autodetect
node_entry -->|"starts deletion loop"| node_delete_scheduler
node_entry -->|"sets command menu"| node_helpers
node_entry -->|"starts client"| node_telegram
node_database -->|"reads and writes channel file"| node_telegram
node_admin -->|"creates links"| node_link_admin
node_link_admin -->|"stores link metadata"| node_database
node_link_admin -->|"copies files to storage"| node_telegram
node_admin -->|"finishes batch"| node_batch_finish
node_batch_finish -->|"delegates batch finish"| node_link_admin
node_user -->|"opens link"| node_start_handler
node_start_handler -.->|"checks eligibility"| node_force_check
node_force_check -.->|"permits or limits delivery"| node_link_delivery
node_link_delivery -->|"reads link and messages"| node_database
node_link_delivery -->|"sends copied files"| node_telegram
node_link_delivery -->|"schedules deletion"| node_delete_scheduler
node_delete_scheduler -->|"reads pending deletions"| node_database
node_delete_scheduler -->|"deletes delivered messages"| node_telegram
node_admin -->|"manages channels"| node_force_admin
node_force_admin -->|"updates channel records"| node_database
node_force_admin -->|"registers channel"| node_channel_autodetect
node_channel_autodetect -->|"saves channel changes"| node_database
node_admin -->|"configures post buttons"| node_buttons
node_admin -->|"renames and uploads media"| node_rename_upload
node_auto_uploader -.->|"processes channel media"| node_telegram
node_admin -.->|"configures auto-upload"| node_auto_uploader
node_admin -->|"uses admin commands"| node_admin_commands
node_admin -->|"sets message text"| node_message_settings
node_admin -->|"requests statistics"| node_statistics
node_admin_commands -.->|"manages stored state"| node_database
node_message_settings -.->|"stores message settings"| node_database
node_statistics -.->|"reports stored counts"| node_database

click node_entry "https://github.com/samir9156/senpaifilestroring/blob/main/main.py"
click node_settings "https://github.com/samir9156/senpaifilestroring/blob/main/config.py"
click node_database "https://github.com/samir9156/senpaifilestroring/blob/main/database.py"
click node_helpers "https://github.com/samir9156/senpaifilestroring/blob/main/helpers.py"
click node_link_admin "https://github.com/samir9156/senpaifilestroring/blob/main/plugins/links.py"
click node_link_delivery "https://github.com/samir9156/senpaifilestroring/blob/main/helpers.py"
click node_delete_scheduler "https://github.com/samir9156/senpaifilestroring/blob/main/scheduler.py"
click node_start_handler "https://github.com/samir9156/senpaifilestroring/blob/main/plugins/start.py"
click node_force_admin "https://github.com/samir9156/senpaifilestroring/blob/main/plugins/forcesub.py"
click node_force_check "https://github.com/samir9156/senpaifilestroring/blob/main/helpers.py"
click node_channel_autodetect "https://github.com/samir9156/senpaifilestroring/blob/main/autodetect.py"
click node_batch_finish "https://github.com/samir9156/senpaifilestroring/blob/main/plugins/done.py"
click node_buttons "https://github.com/samir9156/senpaifilestroring/blob/main/plugins/buttons.py"
click node_rename_upload "https://github.com/samir9156/senpaifilestroring/blob/main/plugins/rename_upload.py"
click node_auto_uploader "https://github.com/samir9156/senpaifilestroring/blob/main/plugins/autouploader.py"
click node_admin_commands "https://github.com/samir9156/senpaifilestroring/blob/main/plugins/admin.py"
click node_message_settings "https://github.com/samir9156/senpaifilestroring/blob/main/plugins/messages.py"
click node_statistics "https://github.com/samir9156/senpaifilestroring/blob/main/plugins/stats.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_entry,node_helpers,node_user toneBlue
class node_settings,node_database toneAmber
class node_link_admin,node_link_delivery,node_delete_scheduler,node_start_handler,node_batch_finish,node_telegram toneMint
class node_force_admin,node_force_check,node_channel_autodetect toneRose
class node_buttons,node_rename_upload,node_auto_uploader,node_admin_commands,node_message_settings,node_statistics,node_admin toneIndigo
```

## Components

### Bot Runtime

- [Bot Startup](https://github.com/samir9156/senpaifilestroring/blob/main/main.py): `main.py`
- [Shared Helpers](https://github.com/samir9156/senpaifilestroring/blob/main/helpers.py): `helpers.py`

### Configuration and Storage

- [Bot Settings](https://github.com/samir9156/senpaifilestroring/blob/main/config.py): `config.py`
- [Channel JSON DB](https://github.com/samir9156/senpaifilestroring/blob/main/database.py): `database.py`

### Links and Delivery

- [Link and Batch Commands](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/links.py): `plugins/links.py`
- [Link Delivery](https://github.com/samir9156/senpaifilestroring/blob/main/helpers.py): `helpers.py`
- [Timed Deletion](https://github.com/samir9156/senpaifilestroring/blob/main/scheduler.py): `scheduler.py`
- [Start Handler](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/start.py): `plugins/start.py`
- [Batch Completion](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/done.py): `plugins/done.py`

### Force-Sub Channels

- [Channel Management](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/forcesub.py): `plugins/forcesub.py`
- [Membership Checks](https://github.com/samir9156/senpaifilestroring/blob/main/helpers.py): `helpers.py`
- [Channel Auto-Detection](https://github.com/samir9156/senpaifilestroring/blob/main/autodetect.py): `autodetect.py`

### Admin Tools

- [Post Buttons](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/buttons.py): `plugins/buttons.py`
- [Manual Rename Upload](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/rename_upload.py): `plugins/rename_upload.py`
- [Episode Auto-Uploader](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/autouploader.py): `plugins/autouploader.py`
- [Admin Controls](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/admin.py): `plugins/admin.py`
- [Custom Messages](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/messages.py): `plugins/messages.py`
- [Usage Statistics](https://github.com/samir9156/senpaifilestroring/blob/main/plugins/stats.py): `plugins/stats.py`

### Other components

- **Admin**
- **Link User**
- **Telegram API**

## Connections

- Admin → Bot Startup: starts bot (evidence: `README.md`)
- Bot Startup → Bot Settings: reads settings (evidence: `main.py`)
- Bot Startup → Channel JSON DB: loads database (evidence: `main.py`)
- Bot Startup → Channel Auto-Detection: starts poller (evidence: `main.py`)
- Bot Startup → Timed Deletion: starts deletion loop (evidence: `main.py`)
- Bot Startup → Shared Helpers: sets command menu (evidence: `main.py`)
- Bot Startup → Telegram API: starts client (evidence: `main.py`)
- Channel JSON DB → Telegram API: reads and writes channel file (evidence: `database.py`)
- Admin → Link and Batch Commands: creates links (evidence: `README.md`)
- Link and Batch Commands → Channel JSON DB: stores link metadata (evidence: `plugins/links.py`)
- Link and Batch Commands → Telegram API: copies files to storage (evidence: `plugins/links.py`)
- Admin → Batch Completion: finishes batch (evidence: `README.md`)
- Batch Completion → Link and Batch Commands: delegates batch finish (evidence: `plugins/done.py`)
- Link User → Start Handler: opens link (evidence: `README.md`)
- Start Handler → Membership Checks: checks eligibility (evidence: `plugins/start.py`)
- Membership Checks → Link Delivery: permits or limits delivery (evidence: `helpers.py`)
- Link Delivery → Channel JSON DB: reads link and messages (evidence: `helpers.py`)
- Link Delivery → Telegram API: sends copied files (evidence: `helpers.py`)
- Link Delivery → Timed Deletion: schedules deletion (evidence: `helpers.py`)
- Timed Deletion → Channel JSON DB: reads pending deletions (evidence: `scheduler.py`)
- Timed Deletion → Telegram API: deletes delivered messages (evidence: `scheduler.py`)
- Admin → Channel Management: manages channels (evidence: `README.md`)
- Channel Management → Channel JSON DB: updates channel records (evidence: `plugins/forcesub.py`)
- Channel Management → Channel Auto-Detection: registers channel (evidence: `plugins/forcesub.py`)
- Channel Auto-Detection → Channel JSON DB: saves channel changes (evidence: `autodetect.py`)
- Admin → Post Buttons: configures post buttons (evidence: `README.md`)
- Admin → Manual Rename Upload: renames and uploads media (evidence: `plugins/rename_upload.py`)
- Episode Auto-Uploader → Telegram API: processes channel media
- Admin → Episode Auto-Uploader: configures auto-upload
- Admin → Admin Controls: uses admin commands (evidence: `README.md`)
- Admin → Custom Messages: sets message text (evidence: `README.md`)
- Admin → Usage Statistics: requests statistics (evidence: `README.md`)
- Admin Controls → Channel JSON DB: manages stored state (evidence: `plugins/admin.py`)
- Custom Messages → Channel JSON DB: stores message settings (evidence: `plugins/messages.py`)
- Usage Statistics → Channel JSON DB: reports stored counts (evidence: `plugins/stats.py`)