# viperadnan-git/telegram-forwarder-bot architecture

> Architecture diagram of the GitHub repository viperadnan-git/telegram-forwarder-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/viperadnan-git/telegram-forwarder-bot
- Repository: https://github.com/viperadnan-git/telegram-forwarder-bot

## Overview

##### Project Overview
- This project is a Telegram bot built using the grammy framework and written in TypeScript.
- Its main purpose is to forward messages from one Telegram channel to one or more channels/groups.
- The bot uses webhooks to receive updates from Telegram servers and relies on environment variables (as shown in .env.sample) for configuration.
- A Redis database is used for storing channel IDs and configurations.

##### Main Components
a. Telegram Server:
- Represents the external Telegram API server responsible for sending webhook updates.

b. Webhook Server / Bot Entry Point:
- Use the main file (src/index.ts) as the entry point where the webhook endpoint is established.
- That the application is listening for incoming updates.

c. Bot Core / Command Handlers:
- Bot core (src/bot.ts) that initializes the grammy framework and sets up the webhook.
- Various command handlers located in the src/handlers directory:
- /start → handled in src/handlers/start.ts
- /help → handled in src/handlers/help.ts
- /set, /rem, /get → handled in src/handlers/set_chat.ts, rem_chat.ts, get_chat.ts, etc.
- /set_owner, /owner_only, etc.
- That these handlers process commands, perform validations (like owner-only commands), and forward messages.

d. Database / Storage Layer:
- Redis database connection integrated via src/database.ts.

e. Utility and Logging Modules:
- Auxiliary modules found in src/modules:
- Logger (src/modules/logger.ts) for logging operations.
- Utils (src/modules/utils.ts) for common utility functions.
- These support debugging and operational logging.

##### Relationships and Interactions
- How the Telegram server sends updates via webhooks to the Webhook Server.
- From the Webhook Server, the bot core dispatches incoming messages to the appropriate command handlers.
- The command handlers may interact with the Redis database to read or update configuration details.
- Feedback loop where processed messages or notifications are sent back to users via the Telegram API.
- Interactions between each handler and the shared modules (logger and utils) for common tasks.

##### Architectural Patterns & Design Principles
- The design follows a modular and layered architecture:
- Separation of concerns: command handlers, database interactions, and utility modules are in separate files.
- The project adheres to a clear command pattern where each bot command is encapsulated in its corresponding handler.
- Dependency Injection can be implied for passing configuration and database connections to various modules.
- Decoupling: the Telegram API interface is clearly separated from business logic (command processing) and data storage.

##### Final Summary
- External integrations (Telegram API, Redis)
- Internal architecture layers (webhook entry point, bot core, individual command handlers)
- Supporting modules (logger, utils)
- Data and command flow between the components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        T["Telegram API Server"]:::external
    end

    %% Internal Architecture
    subgraph "Internal Architecture"
        WE["Webhook Endpoint (src/index.ts)"]:::entry
        BC["Bot Core (src/bot.ts)"]:::core

        subgraph "Command Handlers"
            S["/start Handler"]:::handler
            H["/help Handler"]:::handler
            SET["/set Handler"]:::handler
            REM["/rem Handler"]:::handler
            GET["/get Handler"]:::handler
            SO["/set_owner Handler"]:::handler
            OO["/owner_only Handler"]:::handler
            MSG["/message Handler"]:::handler
        end

        DB["Redis Database"]:::database

        subgraph "Utility & Logging Modules"
            L["Logger Module"]:::utility
            U["Utils Module"]:::utility
        end
    end

    %% Relationships and Interactions
    T -->|"WebhookUpdate"| WE
    WE -->|"InitializeBot"| BC
    
    %% Dispatch commands from Bot Core to respective Handlers
    BC -->|"DispatchCommand"| S
    BC -->|"DispatchCommand"| H
    BC -->|"DispatchCommand"| SET
    BC -->|"DispatchCommand"| REM
    BC -->|"DispatchCommand"| GET
    BC -->|"DispatchCommand"| SO
    BC -->|"DispatchCommand"| OO
    BC -->|"DispatchCommand"| MSG

    %% Command Handlers interacting with Redis Database and Utility Modules
    S -->|"Read/UpdateConfig"| DB
    H -->|"Read/UpdateConfig"| DB
    SET -->|"Read/UpdateConfig"| DB
    REM -->|"Read/UpdateConfig"| DB
    GET -->|"Read/UpdateConfig"| DB
    SO -->|"Read/UpdateConfig"| DB
    OO -->|"Read/UpdateConfig"| DB
    MSG -->|"Read/UpdateConfig"| DB
    
    S ---|"Log/Utilize"| L
    H ---|"Log/Utilize"| L
    SET ---|"Log/Utilize"| L
    REM ---|"Log/Utilize"| L
    GET ---|"Log/Utilize"| L
    SO ---|"Log/Utilize"| L
    OO ---|"Log/Utilize"| L
    MSG ---|"Log/Utilize"| L

    S ---|"Log/Utilize"| U
    H ---|"Log/Utilize"| U
    SET ---|"Log/Utilize"| U
    REM ---|"Log/Utilize"| U
    GET ---|"Log/Utilize"| U
    SO ---|"Log/Utilize"| U
    OO ---|"Log/Utilize"| U
    MSG ---|"Log/Utilize"| U

    %% Feedback loop from Bot Core back to Telegram API Server for responses
    BC -->|"SendResponse"| T

    %% Click Events for Component Mapping
    click WE "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/index.ts"
    click BC "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/bot.ts"
    click S "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/handlers/start.ts"
    click H "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/handlers/help.ts"
    click SET "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/handlers/set_chat.ts"
    click REM "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/handlers/rem_chat.ts"
    click GET "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/handlers/get_chat.ts"
    click SO "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/handlers/set_owner.ts"
    click OO "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/handlers/owner_only.ts"
    click MSG "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/handlers/message.ts"
    click DB "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/database.ts"
    click L "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/modules/logger.ts"
    click U "https://github.com/viperadnan-git/telegram-forwarder-bot/blob/main/src/modules/utils.ts"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef entry fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef core fill:#66CDAA,stroke:#000,stroke-width:2px;
    classDef handler fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef database fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
