# eriappvrc/translatebot architecture

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

- Interactive diagram: https://gitdiagram.com/eriappvrc/translatebot
- Repository: https://github.com/eriappvrc/translatebot

## Overview

##### Project Type & Purpose
- This is a backend service (Node.js micro-service) that connects to Discord as a bot, listens for events and slash commands, uses the DeepL API for translation, and persists data in SQLite.
- Key use-cases: real-time auto-translation, slash-command configuration, statistics, and administrative maintenance.

##### Main Components
- Discord Gateway/API
- DeepL Translation API
b. Bot Service (group in a large rectangle labeled “TranslationBot”)
1. Entry Point
- index.js (Event dispatcher & bot initialization)
2. Command Registration
- deploy-commands.js (Registers slash commands with Discord)
3. Command Handlers
- commands/*.js (translate, translate-setup, translate-channel, translate-role, translate-stats, translate-admin, translate-help, translate-quickstart, translate-rules)
4. Utilities
- translation.js (DeepL API wrapper & caching logic)
- database.js (SQLite open, read/write config & stats)
- database-fixed.js (DB repair utility)
c. Data Store
- translate_bot.sqlite (SQLite file on disk)
d. Configuration
- .env (Discord token, DeepL key, DB path, etc.)
- package.json / package-lock.json (Node dependencies)

##### Relationships & Data Flows
1. Bot reads .env → initialize clients (Discord.js, DB, DeepL).
2. deploy-commands.js registers slash commands via Discord REST.
3. index.js logs in and opens Gateway WebSocket.
- Runtime Flow:
- Slash Command Handling:
a. Discord → (slash command event) → index.js
b. index.js routes to the corresponding commands/*.js handler
c. Handler calls database.js for config or stats
d. For translation: handler calls translation.js → DeepL API → returns text
e. Handler writes logs/stats to SQLite → replies to Discord
- Message Create Auto-Translate:
a. Discord → (messageCreate event) → index.js
b. index.js checks channel/user config via database.js
c. If eligible, calls translation.js → DeepL → caches results
d. Saves translation history in SQLite → posts translated message
- Error & Maintenance:
- database-fixed.js invoked manually for DB repair
- translate-admin commands trigger database.js cleanup/backup

##### Architectural Patterns & Principles
- Modular Command Pattern: each slash command lives in its own module under src/commands.
- Single Responsibility: index.js only dispatches events, deploy-commands.js only registers commands, translation.js only handles API integration.
- Layered: Presentation (Discord events) → Application (command handlers) → Infrastructure (utils & DB) → External (DeepL).

##### Final Checklist
[ ] All major components (Discord Gateway, Bot Core, Commands, Utils, SQLite, DeepL) are present
[ ] Groupings reflect the file-system structure (src/commands, src/utils)
[ ] Labels include key technologies (Discord.js v14, Node.js v18+, SQLite, DeepL API)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External APIs
    subgraph "External Services"
        direction TB
        Discord[("Discord Gateway/API")]:::external
        DeepL[("DeepL Translation API")]:::external
    end

    %% Bot Core
    subgraph "TranslationBot Service"
        direction TB
        Entry["index.js\n(Event Dispatcher & Bot Initialization)"]:::internal
        Deploy["deploy-commands.js\n(Command Registration)"]:::internal

        subgraph "Command Handlers"
            direction TB
            C1["translate.js"]:::internal
            C2["translate-setup.js"]:::internal
            C3["translate-channel.js"]:::internal
            C4["translate-role.js"]:::internal
            C5["translate-stats.js"]:::internal
            C6["translate-admin.js"]:::internal
            C7["translate-help.js"]:::internal
            C8["translate-quickstart.js"]:::internal
            C9["translate-rules.js"]:::internal
        end

        subgraph "Utilities"
            direction TB
            U1["translation.js\n(DeepL API wrapper & caching)"]:::internal
            U2["database.js\n(SQLite operations)"]:::internal
            U3["database-fixed.js\n(DB repair utility)"]:::internal
        end
    end

    %% Configuration & Data Store
    subgraph "Configuration"
        direction TB
        Env[(".env\n(Environment variables)")]:::internal
        PKG["package.json/\npackage-lock.json"]:::internal
    end

    translate_db[(translate_bot.sqlite)]:::storage

    %% Startup Flow
    Env -->|1. load configs| Entry
    Entry -->|2. register commands| Deploy
    Deploy -->|REST API calls| Discord
    Entry -->|3. login & open WS| Discord

    %% Runtime Slash Commands
    Discord -->|slashCommandEvent| Entry
    Entry -->|route to handler| C1
    Entry -->|route to handler| C2
    Entry -->|route to handler| C3
    Entry -->|route to handler| C4
    Entry -->|route to handler| C5
    Entry -->|route to handler| C6
    Entry -->|route to handler| C7
    Entry -->|route to handler| C8
    Entry -->|route to handler| C9

    C1 -->|read/write config| U2
    C1 -->|translate text| U1
    C1 -->|log stats| U2
    U1 -->|API request| DeepL
    U1 -->|cache stored| U2

    %% Runtime Auto-Translate
    Discord -->|messageCreateEvent| Entry
    Entry -->|check eligibility| U2
    Entry -->|call translate| U1
    U1 -->|API request| DeepL
    U1 -->|cache| U2
    U2 -->|history write| translate_db
    Entry -->|post translation| Discord

    %% Maintenance & Repair
    U3 -->|DB repair| translate_db
    C6 -->|cleanup/backup| U2

    %% Click Events
    click Entry "https://github.com/eriappvrc/translatebot/blob/main/src/index.js"
    click Deploy "https://github.com/eriappvrc/translatebot/blob/main/src/deploy-commands.js"
    click C1 "https://github.com/eriappvrc/translatebot/blob/main/src/commands/translate.js"
    click C2 "https://github.com/eriappvrc/translatebot/blob/main/src/commands/translate-setup.js"
    click C3 "https://github.com/eriappvrc/translatebot/blob/main/src/commands/translate-channel.js"
    click C4 "https://github.com/eriappvrc/translatebot/blob/main/src/commands/translate-role.js"
    click C5 "https://github.com/eriappvrc/translatebot/blob/main/src/commands/translate-stats.js"
    click C6 "https://github.com/eriappvrc/translatebot/blob/main/src/commands/translate-admin.js"
    click C7 "https://github.com/eriappvrc/translatebot/blob/main/src/commands/translate-help.js"
    click C8 "https://github.com/eriappvrc/translatebot/blob/main/src/commands/translate-quickstart.js"
    click C9 "https://github.com/eriappvrc/translatebot/blob/main/src/commands/translate-rules.js"
    click U1 "https://github.com/eriappvrc/translatebot/blob/main/src/utils/translation.js"
    click U2 "https://github.com/eriappvrc/translatebot/blob/main/src/utils/database.js"
    click U3 "https://github.com/eriappvrc/translatebot/blob/main/src/utils/database-fixed.js"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef external fill:#f8cbad,stroke:#333,stroke-width:1px
    classDef storage fill:#d9ead3,stroke:#333,stroke-width:1px
```
