# chyyynh/media-tool architecture

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

- Interactive diagram: https://gitdiagram.com/chyyynh/media-tool
- Repository: https://github.com/chyyynh/media-tool

## Overview

##### Project Type and Purpose
- The project is centered around a Telegram bot that processes article or YouTube links posted in Telegram chats. It retrieves the article, translates it, posts the translated version to HackMD, and provides a text file (and/or integration with YouTube, Supabase, etc.).
- The README is brief but clear about the core functionality: users post an article link to the Telegram bot, and the bot responds by providing content (translated article) on HackMD or processing YouTube links to generate text.
- Multiple scripts in the root (e.g., hackmd_to_supabase.js, hackmdtranslate.js, telegram_bot.js) and the dedicated worker folder (tgbot-worker) indicate that the project contains different modules or services to handle various tasks (translation, integration, crawling, etc.).

##### Analyzing the File Structure
- Top-Level Files & Scripts: There are several JavaScript files, each hinting at a separate functionality:
– audiototext.js: Possibly converts audio content to text.
– hackmd_to_supabase.js: Seems to handle data transfer between HackMD and Supabase.
– hackmdtranslate.js and hackmdtranslatedGo.js: Likely manage content translation via HackMD.
– telegram_bot.js: Main entry for handling Telegram bot interactions.
– Additional scripts (e.g., twittercrawl.js, translate2hackmdAz.js, translate2hackmdGo.js) indicate extended features, such as processing Twitter feeds or additional translation pathways.
- The 'tgbot-worker' Directory:
– Structured with TypeScript files (index.ts, utils.ts) and testing/config files, reinforcing that a dedicated worker handles asynchronous or background tasks.
– Configuration files (wrangler.jsonc, .editorconfig, etc.) suggest that this component might be deployed as a serverless worker or microservice.
- Configuration and Package Files: Presence of package.json, pnpm-lock.yaml, etc., suggesting dependency management for a Node.js environment.

a. Main Components to Include:
– Telegram Bot Interface: Represents the entry point where users post article or YouTube links.
– Gateway/API Layer: A service layer (or scripts) that accepts the bot commands/messages and routes them to appropriate modules.
– Translation & Content Processing Modules:
- Translation Scripts: hackmdtranslate.js, translate2hackmdAz.js, translate2hackmdGo.js.
- Article Retrieval & Processing: Scripts to extract content from article links (could also involve audiototext.js if audio content is involved).
– HackMD Integration: Modules that post or interact with HackMD (e.g., hackmd_to_supabase.js, hackmdtranslatedGo.js).
– Supabase Integration: If data persistence or additional analytics are needed (as seen in testSupabaseUpload.js).
– tgbot-worker Service: A dedicated worker module that manages asynchronous tasks, error handling, scheduling, or retries. It’s implemented in TypeScript and might be designed to scale independently.
– External Services:
- YouTube API: To process YouTube links and extract text.
- Twitter Service: Indicated by twittercrawl.js for any related functionality.

b. Relationships and Interactions:
– From the Gateway, branch out to:
- The Translation Module for translation logic.
- The HackMD Integration module to post or retrieve content.
- The YouTube/Article Extraction module for processing different link types.
– The tgbot-worker interacts with these modules to handle background tasks like parsing, uploading, or error logging.
– There might be data flow from HackMD Integration → Supabase (and vice versa) if content or metadata is stored.

c. Architectural Patterns:
– Separation of concerns: Different scripts for translation, integration with third-party services, and asynchronous processing imply a modular backend architecture.
– Use of a worker service: The tgbot-worker component indicates that some processing is offloaded from the main Telegram bot flow.
– Microservice or modular scripting: Each script or module targets a specific task (e.g., translation, data extraction, content posting).

d. Technologies and Frameworks:
– Node.js (Primary language through JavaScript and TypeScript files).
– TypeScript: Evident in the tgbot-worker folder.
– Telegram Bot API: For interacting with Telegram.
– HackMD API: For the posting and retrieval of content.
– Supabase: For potential backend data handling.
– Possibly additional APIs (YouTube, Twitter) based on the purpose of specific scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Facing Component
    A["Telegram Bot Interface"]:::user

    %% API / Message Router Layer
    B["API/Message Router"]:::api

    %% Processing Modules
    subgraph "Processing Modules"
        C["Translation Service"]:::service
        D["Article & Audio Processing"]:::service
        E["HackMD Integration Module"]:::service
        F["Twitter Service Integration"]:::service
        G["tgbot-worker (Async Processor)"]:::worker
    end

    %% External Services
    subgraph "External Services"
        H["HackMD API"]:::external
        I["Supabase"]:::external
        J["YouTube API"]:::external
    end

    %% Data Flow
    A -->|"receivesMessage"| B
    B -->|"routeToTranslation"| C
    B -->|"routeToArticleProcessing"| D
    B -->|"routeToHackMD"| E
    B -->|"routeToTwitter"| F
    B -->|"routeToWorker"| G

    C -->|"sendToHackMD"| H
    E -->|"postToHackMD"| H
    E -->|"updateData"| I
    I -->|"fetchMeta"| E

    D -.->|"audioToText"| J
    F -->|"twitterData"| J

    G -->|"backgroundTasks"| C
    G -->|"backgroundTasks"| E

    %% Response flow back to user (implicit)
    H -->|"responseData"| A
    I -->|"confirmData"| A

    %% Click Events for Component Mappings
    click A "https://github.com/chyyynh/media-tool/blob/main/telegram_bot.js"
    click C "https://github.com/chyyynh/media-tool/blob/main/hackmdtranslate.js"
    click C "https://github.com/chyyynh/media-tool/blob/main/translate2hackmdAz.js"
    click C "https://github.com/chyyynh/media-tool/blob/main/translate2hackmdGo.js"
    click D "https://github.com/chyyynh/media-tool/blob/main/audiototext.js"
    click E "https://github.com/chyyynh/media-tool/blob/main/hackmd_to_supabase.js"
    click E "https://github.com/chyyynh/media-tool/blob/main/hackmdtranslatedGo.js"
    click F "https://github.com/chyyynh/media-tool/blob/main/twittercrawl.js"
    click G "https://github.com/chyyynh/media-tool/tree/main/tgbot-worker/"
    click I "https://github.com/chyyynh/media-tool/blob/main/testSupabaseUpload.js"
    click I "https://github.com/chyyynh/media-tool/blob/main/supabase.js"

    %% Styles
    classDef user fill:#D1E8FF,stroke:#007ACC,stroke-width:2px;
    classDef api fill:#FFF4C2,stroke:#D4A017,stroke-width:2px;
    classDef service fill:#DFF0D8,stroke:#3C763D,stroke-width:2px;
    classDef worker fill:#D0E6FF,stroke:#5B9BD5,stroke-width:2px;
    classDef external fill:#F2DEDE,stroke:#A94442,stroke-width:2px;
```
