# krex381/youtube-sub-checker architecture

> Architecture diagram of the GitHub repository krex381/youtube-sub-checker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krex381/youtube-sub-checker
- Repository: https://github.com/krex381/youtube-sub-checker

## Overview

##### Project type and purpose
- This is a full-stack Node.js application combining a Discord bot with a lightweight web interface to verify YouTube channel subscriptions.
- Purpose: guide Discord users through a screenshot-based verification process, detect fraud via OCR and watermarks, then assign roles in a Discord guild.

##### File structure
- Top-level files:
– server.js: Express server entry point
– discord-bot.js: Discord.js bot logic
– config.json & banned-users.json: runtime configuration and simple JSON datastore
– translations.json: i18n support
– package.json / package-lock.json: dependencies and scripts
- Directories:
– frontend/: static web UI (HTML, CSS, JS) served by Express
– utils/: core modules (youtube API integration, watermark detection)
– watermarks/: watermark images or reference assets
- No separate “database” directory: simple JSON files are used for storage.

##### README for additional insights
- Tech stack: Node.js v16+, Discord.js, YouTube Data API v3, OCR (e.g., Tesseract)
- Key features: screenshot watermark detection, anti-fraud measures, secure token system, real-time processing
- Commands: /verify, /setup, /watermark

##### How to represent this architecture
a. Main components
– Discord Bot Service (discord-bot.js)
– Web Server (server.js + Express)
– Frontend UI (frontend/index.html, script.js, style.css)
– OCR & Watermark Detection Module (utils/youtube.js, utils/watermarks)
– JSON Data Store (config.json, banned-users.json, translations.json)
– External Services: Discord API, YouTube Data API, OCR engine
b. Relationships & data flow
1. User invokes /verify in Discord → Discord Bot generates a secure token → replies with a verification link to Web UI
2. User opens Web UI → frontend collects screenshot and token → POST to Web Server
3. Web Server validates token → invokes OCR & watermark detection → queries YouTube Data API to confirm subscription → updates banned-users.json or assigns a Discord role
4. On success: Web Server calls Discord API via the Bot Service to assign “subscribed” role
c. Architectural patterns & design principles
– Event-driven design: Discord webhook events trigger workflows
– Modular design: utility modules isolated under utils/ for YouTube and watermark logic
– Separation of concerns: frontend static assets vs. backend API
– Secure token pattern: one-time tokens stored in memory or JSON for session management
d. Key technologies & frameworks
– Node.js + Express for backend
– discord.js for bot interactions
– YouTube Data API v3 for subscription checks
– OCR library (e.g., Tesseract.js) for text detection
– JSON files as a lightweight datastore

##### Detail
- Every module under utils/ to show where business logic resides
- Token generation & validation step as a discrete component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    DiscordAPI["Discord API"]:::external
    YouTubeAPI["YouTube Data API v3"]:::external
    OCREngine["OCR Engine"]:::external

    %% Bot Service Layer
    subgraph "Bot Service"
        BSC["Discord Bot Service"]:::service
    end

    %% Web Server Layer
    subgraph "Web Server"
        WS["Express Server"]:::service
    end

    %% Frontend UI Layer
    subgraph "Frontend UI"
        FE_HTML["index.html"]:::frontend
        FE_JS["script.js"]:::frontend
        FE_CSS["style.css"]:::frontend
    end

    %% Modules Layer
    subgraph "Business Logic Modules"
        YT["YouTube Data API Module"]:::module
        OCR["OCR & Watermark Module"]:::module
    end

    %% Watermark Assets
    subgraph "Anti-Fraud Assets"
        WAT["watermarks/"]:::assets
    end

    %% Datastore Layer
    subgraph "JSON Datastore"
        CONF["config.json"]:::datastore
        BANNED["banned-users.json"]:::datastore
        TRANS["translations.json"]:::datastore
    end

    %% Flows
    DiscordAPI -->|"/verify command"| BSC
    BSC -->|"generate token & link"| WS
    FE_HTML -->|load UI| FE_JS
    FE_CSS -->|styles UI| FE_HTML
    FE_JS -->|"POST screenshot+token"| WS
    WS -->|"validate token"| CONF
    WS -->|"invoke OCR"| OCR
    OCR -->|"scan image"| OCREngine
    OCR -->|"check watermark"| WAT
    WS -->|"check subscription"| YT
    YT -->|"query subscription"| YouTubeAPI
    WS -->|"update ban list"| BANNED
    WS -->|"load translations"| TRANS
    WS -->|"assign role"| BSC
    BSC -->|"assign role"| DiscordAPI

    %% Click Events
    click BSC "https://github.com/krex381/youtube-sub-checker/blob/main/discord-bot.js"
    click WS "https://github.com/krex381/youtube-sub-checker/blob/main/server.js"
    click FE_HTML "https://github.com/krex381/youtube-sub-checker/blob/main/frontend/index.html"
    click FE_JS "https://github.com/krex381/youtube-sub-checker/blob/main/frontend/script.js"
    click FE_CSS "https://github.com/krex381/youtube-sub-checker/blob/main/frontend/style.css"
    click YT "https://github.com/krex381/youtube-sub-checker/blob/main/utils/youtube.js"
    click WAT "https://github.com/krex381/youtube-sub-checker/tree/main/watermarks/"
    click CONF "https://github.com/krex381/youtube-sub-checker/blob/main/config.json"
    click BANNED "https://github.com/krex381/youtube-sub-checker/blob/main/banned-users.json"
    click TRANS "https://github.com/krex381/youtube-sub-checker/blob/main/translations.json"

    %% Styles
    classDef service fill:#D6EAF8,stroke:#3498DB,color:#1B4F72,stroke-width:1px
    classDef frontend fill:#E8DAEF,stroke:#8E44AD,color:#512E5F,stroke-width:1px
    classDef module fill:#D5F5E3,stroke:#27AE60,color:#1E8449,stroke-width:1px
    classDef assets fill:#FCF3CF,stroke:#F1C40F,color:#7D6608,stroke-width:1px
    classDef datastore fill:#FADBD8,stroke:#E74C3C,color:#641E16,stroke-width:1px
    classDef external fill:#E5E7E9,stroke:#566573,color:#17202A,stroke-width:1px
```
