# sudor2spr/1tamilmv_v2_bot architecture

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

- Interactive diagram: https://gitdiagram.com/sudor2spr/1tamilmv_v2_bot
- Repository: https://github.com/sudor2spr/1tamilmv_v2_bot

## Overview

##### Project type and purpose
- This is a single-service, webhook-driven Telegram bot (“tamilmv_v2_Bot”) written in Python.
- Purpose: Listen for user commands in Telegram, scrape Tamil movie torrent magnet links from a target site (TAMILMV_URL), and send them back to users.

##### File structure
- Top‐level config files:
- Dockerfile, docker-compose.yml, heroku.yml → containerization & deployment
- .github/workflows/*.yml → CI/CD pipelines (code scanning, PyPI publish)
- runtime.txt, requirements.txt, pyproject.toml, setup.py → Python environment & dependencies
- Source code directory:
- tamilmvbot/angel.py → main entry point (webhook server, command handler, scraper)
- Deployment helpers: run cmd.txt, Dockerignore

##### README for additional insights
- Defines required ENV variables: TOKEN, WEBHOOK_URL, TAMILMV_URL, PORT
- Deployment recipes for Render.com, Heroku, Koyeb
- Usage commands (`/start`, `/view`) and build/start commands

a. Main components
- Telegram Users (end users with Telegram client)
- Telegram Bot API / Telegram Servers (external webhook provider)
- Bot Service (Docker container hosting `tamilmvbot.angel`):
– Webhook Listener (HTTP server on PORT)
– Command Processor
– Scraper Module (HTTP client fetching data from TAMILMV_URL)
- External TamilMV Website (source of torrent links)
- CI/CD Pipeline (GitHub Actions building docker image, pushing, deploying)
- Hosting Platform (Render.com or Heroku)
b. Relationships & interactions
1. User sends message → Telegram Servers
2. Telegram Servers → POST webhook to Bot Service
3. Webhook Listener → Command Processor → invokes Scraper Module → HTTP GET to TamilMV_URL
4. Scraper extracts magnet links → Command Processor → sends HTTPS POST message back via Telegram Bot API
5. CI/CD workflows trigger on commit → build container → deploy to hosting
c. Architectural patterns & design principles
- Event-driven microservice (webhooks)
- Single responsibility: separate modules for HTTP, processing, scraping
- Container-based deployment (immutable infrastructure)
- Infrastructure as code (Docker, Docker Compose, Heroku/YML)
d. Key technologies & libraries
- Python 3.x (defined in runtime.txt/pyproject.toml)
- python-telegram-bot or similar HTTP webhook library
- requests or aiohttp for scraping
- Docker, Docker Compose, GitHub Actions, Render/Heroku

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        direction TB
        TelegramUsers("Telegram Users"):::external
        TelegramServers("Telegram Servers / Bot API"):::external
        TamilMV("TamilMV Website<br/>(TAMILMV_URL)"):::external
    end

    %% Bot Service
    subgraph "Bot Service"
        direction TB
        WebhookListener("Webhook Listener<br/>(PORT)"):::internal
        CommandProcessor("Command Processor"):::internal
        Scraper("Scraper Module<br/>(HTTP to TAMILMV_URL)"):::internal
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        GitHub("GitHub Repo"):::infra
        CodeScan("Code Scan & Auto PR Workflow"):::infra
        PyPIPublish("PyPI Publish Workflow"):::infra
        ContainerRegistry("Container Registry"):::infra
        Hosting("Hosting Platform<br/>(Render/Heroku)"):::infra
        DockerfileNode("Dockerfile"):::infra
        DockerCompose("docker-compose.yml"):::infra
        HerokuYml("heroku.yml"):::infra
        RuntimeTxt("runtime.txt"):::infra
        Requirements("requirements.txt"):::infra
        Pyproject("pyproject.toml"):::infra
        Setup("setup.py"):::infra
        RunCmd("run cmd.txt"):::infra
    end

    %% Data Flows
    TelegramUsers -->|"sends command"| TelegramServers
    TelegramServers -->|"POST webhook"| WebhookListener
    WebhookListener -->|"process"| CommandProcessor
    CommandProcessor -->|"invoke"| Scraper
    Scraper -->|"GET TAMILMV_URL"| TamilMV
    TamilMV -->|"magnet links"| Scraper
    Scraper -->|"results"| CommandProcessor
    CommandProcessor -->|"HTTPS POST"| TelegramServers

    %% CI/CD & Deployment Flows
    GitHub -->|on commit| CodeScan
    GitHub -->|on commit| PyPIPublish
    CodeScan -->|build image| ContainerRegistry
    PyPIPublish -->|publish package| ContainerRegistry
    ContainerRegistry -->|deploy image| Hosting
    Hosting -->|runs| WebhookListener

    %% Click Events
    click Scraper "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/tamilmvbot/angel.py"
    click WebhookListener "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/tamilmvbot/angel.py"
    click CommandProcessor "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/tamilmvbot/angel.py"
    click DockerfileNode "https://github.com/sudor2spr/1tamilmv_v2_bot/tree/master/Dockerfile"
    click DockerCompose "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/docker-compose.yml"
    click HerokuYml "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/heroku.yml"
    click CodeScan "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/.github/workflows/code-scan-and-auto-pr.yml"
    click PyPIPublish "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/.github/workflows/pypi-publish.yml"
    click RuntimeTxt "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/runtime.txt"
    click Requirements "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/requirements.txt"
    click Pyproject "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/pyproject.toml"
    click Setup "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/setup.py"
    click RunCmd "https://github.com/sudor2spr/1tamilmv_v2_bot/blob/master/run cmd.txt"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef internal fill:#9f9,stroke:#333,stroke-width:1px
    classDef infra fill:#ff9,stroke:#333,stroke-width:1px
```
