# starkbotsindustries/restrictedcontentsaver architecture

> Architecture diagram of the GitHub repository starkbotsindustries/restrictedcontentsaver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/starkbotsindustries/restrictedcontentsaver
- Repository: https://github.com/starkbotsindustries/restrictedcontentsaver

## Overview

##### Project Type and Purpose
- This is a monolithic, Python-based Telegram Bot (“Restricted Content Saver Bot”) built with the Pyrogram library.
- Purpose: Receive restricted-media links from users, save the content via a userbot into a “universal cache” channel, and retrieve it on demand.

##### File Structure
- Top-level:
- Unlock/           — main Python package
– __main__.py     — bot entry point (python –m Unlock)
– modules/        — code organized by feature
- start.py      — handles /start, /help, /repo, /tos commands
- send_restricted.py — /save command logic
- UserBot/      — userbot integration
· saver.py    — sends/receives media via userbot session
· Special/UniversalDatabase.py — cache manager abstraction
- Config & Deployment:
- .env.example    — environment variables template
- requirements.txt — Python dependencies
- Support:
- tests/test_bot.py — basic unit test for core functionality

##### Extract Insights from README
- Uses Pyrogram to interact with both Bot API and a userbot session.
- Requires Telegram Bot Token, API_ID, API_HASH, StringSession (for userbot).
- Caching strategy: bot itself cannot bypass restrictions, so it uses an admin userbot in a cache channel to store and serve content.

##### Main Components
a. External Entities:
- Telegram User (client)
- Telegram Servers (Bot API endpoint + userbot endpoint)
- Universal Cache Channel (on Telegram)
b. Internal Components:
- Configuration Loader (.env → runtime settings)
- Bot Application (Unlock/__main__.py)
- Command Handlers (modules/start.py, modules/send_restricted.py)
- UserBot Manager (modules/UserBot/saver.py)
- Cache Abstraction (modules/UserBot/Special/UniversalDatabase.py)
- Logging Subsystem
- Dependencies: Pyrogram library, python-dotenv
c. Data Stores:
- In-memory/session state (handled by Pyrogram)
- Telegram cache channel (persistent store)
d. External Services:
- Telegram Bot API
- Telegram API (for userbot)

##### Relationships and Data Flow
1. Telegram User → sends “/save <link>” → Telegram Bot API
2. Bot Application (/start or /save handler) receives Update via Pyrogram
3. send_restricted.py parses link and enqueues request to saver.py
4. saver.py (UserBot) uses the userbot session to forward/download media into Universal Cache Channel
5. UniversalDatabase abstraction confirms caching, stores metadata if needed
6. Bot Application retrieves the cached media link/id from the channel
7. Bot Application sends media back to user via Bot API
8. All steps are logged via built-in logging

##### Architectural Patterns and Principles
- Modular Handler Pattern: each command lives in its own module.
- Single Process, Event-Driven: Pyrogram event loop dispatches updates to handlers.
- Separation of Concerns:
- Config management (.env)
- Command routing (Unlock/__main__.py)
- Business logic (modules)
- External integration (UserBot)
- Cache abstraction (UniversalDatabase)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    User["Telegram User"]:::external
    BotAPI["Telegram Bot API"]:::external
    TgAPI["Telegram API (UserBot)"]:::external
    CacheChannel["Universal Cache Channel"]:::cache

    %% Internal Components
    subgraph "Configuration"
        ConfigLoader["Config Loader"]:::core
    end
    subgraph "Dependencies"
        Requirements["Dependency Specification"]:::core
    end
    subgraph "Application"
        EntryPoint["Unlock (Entry Point)"]:::core
        subgraph "Command Handlers"
            StartHandler["Start/TOS/Help/Repo Handler"]:::core
            SaveHandler["Save Restricted Media Handler"]:::core
        end
        subgraph "UserBot Integration"
            Saver["UserBot Manager"]:::core
            UniversalDB["Cache Abstraction"]:::core
        end
        Logging["Logging Subsystem"]:::core
    end
    subgraph "Support"
        TestSuite["Test Suite"]:::core
    end

    %% Data Flows
    User -->|"/save or /start"| BotAPI
    BotAPI -->|"HTTPS/JSON"| EntryPoint
    EntryPoint --> StartHandler
    EntryPoint --> SaveHandler
    SaveHandler -->|"enqueue request"| Saver
    Saver -->|"MTProto"| TgAPI
    TgAPI -->|"store media"| CacheChannel
    CacheChannel -->|"media id"| Saver
    Saver --> UniversalDB
    UniversalDB --> EntryPoint
    EntryPoint -->|"HTTPS/JSON"| BotAPI
    BotAPI --> User
    %% Logging
    EntryPoint --> Logging
    StartHandler --> Logging
    SaveHandler --> Logging
    Saver --> Logging
    UniversalDB --> Logging

    %% Side Notes
    ConfigLoader --> EntryPoint
    Requirements --> EntryPoint
    TestSuite --> EntryPoint

    %% Click Events
    click ConfigLoader "https://github.com/starkbotsindustries/restrictedcontentsaver/blob/main/.env.example"
    click Requirements "https://github.com/starkbotsindustries/restrictedcontentsaver/blob/main/requirements.txt"
    click EntryPoint "https://github.com/starkbotsindustries/restrictedcontentsaver/blob/main/Unlock/__main__.py"
    click StartHandler "https://github.com/starkbotsindustries/restrictedcontentsaver/blob/main/Unlock/modules/start.py"
    click SaveHandler "https://github.com/starkbotsindustries/restrictedcontentsaver/blob/main/Unlock/modules/send_restricted.py"
    click Saver "https://github.com/starkbotsindustries/restrictedcontentsaver/blob/main/Unlock/modules/UserBot/saver.py"
    click UniversalDB "https://github.com/starkbotsindustries/restrictedcontentsaver/blob/main/Unlock/modules/UserBot/Special/UniversalDatabase.py"
    click TestSuite "https://github.com/starkbotsindustries/restrictedcontentsaver/blob/main/tests/test_bot.py"

    %% Styles
    classDef external fill:#a8f0c6,stroke:#2d8f42,stroke-width:2px;
    classDef core fill:#c6d8ff,stroke:#1f4e79,stroke-width:2px;
    classDef cache fill:#ffd9a6,stroke:#b27300,stroke-width:2px;
```
