# guiireal/takeshi-bot architecture

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

- Interactive diagram: https://gitdiagram.com/guiireal/takeshi-bot
- Repository: https://github.com/guiireal/takeshi-bot

## Overview

##### Project Type and Purpose
- This is a Node.js–based, event-driven WhatsApp chatbot (“Takeshi Bot”) that runs as a single process.
- It uses the Baileys library to connect to WhatsApp, loads commands dynamically, applies middleware, calls external services (Spider X API, Catbox, FFMPEG, etc.), and stores simple data in JSON.

##### High-Level File‐Structure Analysis
- Top-level:
- index.js (entry point for hosting), index.js under src (runtime entry)
- assets/ (media files + Baileys auth state)
- database/ (auto-responder JSON)
- src/ (core code):
– config.js, connection.js, loader.js, index.js, test.js
– folders: commands (admin/member/owner), middlewares, services, utils, errors, @types
- Patterns:
- Event‐driven flow (Baileys emits messages → loader & middlewares → command handlers)
- Plugin-style commands folder, each command modularized
- Layered organization: Connection → Loader → Middlewares → Commands → Services/Utils

##### Key Components
A. WhatsApp Connection Layer
- Baileys client (in `src/connection.js`)
- Entry point (`src/index.js`)
B. Loader & Dispatcher
- `loader.js` (scans commands, loads help metadata)
- Dynamic command resolver (`utils/dynamicCommand.js`)
C. Middleware Layer
- `src/middlewares/*.js` (check permissions, onGroupParticipantsUpdate, onMessagesUpsert)
D. Command Handlers
- `src/commands/*` (admin, member, owner)
- Each command: receives context, interacts with services/utils, returns responses
E. Services & External Integrations
- `src/services/baileys.js` (wrapper around Baileys send/receive)
- `src/services/spider-x-api.js`, `src/services/catbox.js`
- Axios HTTP calls
- FFmpeg (spawned via child_process for media)
F. Utilities & Data Stores
- `src/utils/*.js` (logger, database wrapper, message templates, common functions)
- `database/auto-responder.json` (persistent data)
- `assets/auth/baileys/` (session files)
- `assets/temp/` (transient files)
G. External Systems
- WhatsApp servers (via Baileys)
- Spider X API
- Catbox API
- YouTube/TikTok for downloads (through third-party endpoints)

##### Relationships and Data Flow
1. **Start**: Node.js (`index.js`) initializes config → connection → loader
2. **Connection**: Baileys connects to WhatsApp, emits “message upsert” events
3. **Loader**: Receives event, applies global interceptors, loads appropriate command module
4. **Middleware**: Each incoming message passes through `checkPermission`, `onGroupParticipantsUpdate`, etc.
5. **Command Execution**:
- Command handler logic in `src/commands/*`
- May call services (e.g., Spider X for AI generation, Catbox for file hosting)
- May invoke utilities (e.g., `utils/database.js`, `logger.js`)
- For media, spawns FFMPEG or downloads via Axios
6. **Response**: Service writes reply via Baileys wrapper → WhatsApp

##### Architectural Patterns & Principles
- Event‐Driven Architecture (EDA)
- Layered structure (Connection → Loader → Middleware → Commands → Services → Utils)
- Plugin/Modular Commands (dynamic discovery of handlers)
- Single Responsibility (each module has a clear domain)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Process
    Core["Node.js Runtime / Entry Point\n(src/index.js)"]:::infra
    click Core "https://github.com/guiireal/takeshi-bot/blob/main/src/index.js"

    Config["Configuration\n(src/config.js)"]:::app
    click Config "https://github.com/guiireal/takeshi-bot/blob/main/src/config.js"

    Connection["Baileys Client\n(src/connection.js)"]:::infra
    click Connection "https://github.com/guiireal/takeshi-bot/blob/main/src/connection.js"

    Loader["Loader & Dispatcher\n(src/loader.js)"]:::app
    click Loader "https://github.com/guiireal/takeshi-bot/blob/main/src/loader.js"

    DynamicCmd["Dynamic Command Resolver\n(src/utils/dynamicCommand.js)"]:::app
    click DynamicCmd "https://github.com/guiireal/takeshi-bot/blob/main/src/utils/dynamicCommand.js"

    subgraph Middleware Layer
        direction TB
        MIDX["Middlewares Index\n(src/middlewares/index.js)"]:::app
        click MIDX "https://github.com/guiireal/takeshi-bot/blob/main/src/middlewares/index.js"
        CheckPerm["checkPermission.js"]:::app
        click CheckPerm "https://github.com/guiireal/takeshi-bot/blob/main/src/middlewares/checkPermission.js"
        OnPart["onGroupParticipantsUpdate.js"]:::app
        click OnPart "https://github.com/guiireal/takeshi-bot/blob/main/src/middlewares/onGroupParticipantsUpdate.js"
        OnUpsert["onMessagesUpsert.js"]:::app
        click OnUpsert "https://github.com/guiireal/takeshi-bot/blob/main/src/middlewares/onMesssagesUpsert.js"
        MIDX --> CheckPerm --> OnPart --> OnUpsert
    end

    subgraph Command Handlers
        direction TB
        subgraph Admin Tier
            direction TB
            AdminCmd["src/commands/admin/"]:::app
            click AdminCmd "https://github.com/guiireal/takeshi-bot/tree/main/src/commands/admin/"
        end
        subgraph Member Tier
            direction TB
            MemCmd["src/commands/member/"]:::app
            click MemCmd "https://github.com/guiireal/takeshi-bot/tree/main/src/commands/member/"
        end
        subgraph Owner Tier
            direction TB
            OwnerCmd["src/commands/owner/"]:::app
            click OwnerCmd "https://github.com/guiireal/takeshi-bot/tree/main/src/commands/owner/"
        end
    end

    subgraph Services & External Integrations
        direction TB
        BaileysWrap["Baileys Wrapper\n(src/services/baileys.js)"]:::infra
        click BaileysWrap "https://github.com/guiireal/takeshi-bot/blob/main/src/services/baileys.js"
        SpiderX["Spider X API\n(src/services/spider-x-api.js)"]:::ext
        click SpiderX "https://github.com/guiireal/takeshi-bot/blob/main/src/services/spider-x-api.js"
        Catbox["Catbox API\n(src/services/catbox.js)"]:::ext
        click Catbox "https://github.com/guiireal/takeshi-bot/blob/main/src/services/catbox.js"
        FFmpeg["FFmpeg Process\n(child_process)"]:::infra
    end

    subgraph Utilities & Error Types
        direction TB
        Logger["Logger\n(src/utils/logger.js)"]:::app
        click Logger "https://github.com/guiireal/takeshi-bot/blob/main/src/utils/logger.js"
        DBUtil["Database Util\n(src/utils/database.js)"]:::app
        click DBUtil "https://github.com/guiireal/takeshi-bot/blob/main/src/utils/database.js"
        MsgUtil["Messages Templates\n(src/utils/messages.js)"]:::app
        click MsgUtil "https://github.com/guiireal/takeshi-bot/blob/main/src/utils/messages.js"
        UtilsIdx["Utils Index\n(src/utils/index.js)"]:::app
        click UtilsIdx "https://github.com/guiireal/takeshi-bot/blob/main/src/utils/index.js"
        CommonFn["Load Common Functions\n(src/utils/loadCommonFunctions.js)"]:::app
        click CommonFn "https://github.com/guiireal/takeshi-bot/blob/main/src/utils/loadCommonFunctions.js"
        subgraph Error Types
            Danger["DangerError.js"]:::app
            click Danger "https://github.com/guiireal/takeshi-bot/blob/main/src/errors/DangerError.js"
            InvalidParam["InvalidParameterError.js"]:::app
            click InvalidParam "https://github.com/guiireal/takeshi-bot/blob/main/src/errors/InvalidParameterError.js"
            WarningErr["WarningError.js"]:::app
            click WarningErr "https://github.com/guiireal/takeshi-bot/blob/main/src/errors/WarningError.js"
        end
    end

    subgraph Data & Storage
        direction TB
        AutoRes["auto-responder.json"]:::data
        click AutoRes "https://github.com/guiireal/takeshi-bot/blob/main/database/auto-responder.json"
        AuthState["Baileys Auth State"]:::data
        click AuthState "https://github.com/guiireal/takeshi-bot/tree/main/assets/auth/"
        TempFiles["Transient Media Files"]:::data
        click TempFiles "https://github.com/guiireal/takeshi-bot/tree/main/assets/temp/"
        StaticMedia["Static Assets\nassets/images/funny/"]:::data
        click StaticMedia "https://github.com/guiireal/takeshi-bot/tree/main/assets/images/funny/"
    end

    subgraph External Systems
        direction TB
        WhatsApp["WhatsApp Servers"]:::ext
        SPXAPI["Spider X API"]:::ext
        CBXAPI["Catbox API"]:::ext
        YT["YouTube/TikTok APIs"]:::ext
    end

    %% Flow
    Core --> Config
    Core --> Connection
    Core --> Loader
    Connection -.->|message upsert event| Loader
    Loader --> DynamicCmd
    Loader --> MIDX
    MIDX --> AdminCmd
    MIDX --> MemCmd
    MIDX --> OwnerCmd
    AdminCmd --> BaileysWrap
    MemCmd --> BaileysWrap
    OwnerCmd --> BaileysWrap
    AdminCmd --> SpiderX
    AdminCmd --> Catbox
    AdminCmd --> FFmpeg
    MemCmd --> SpiderX
    MemCmd --> Catbox
    MemCmd --> FFmpeg
    OwnerCmd --> SpiderX
    OwnerCmd --> Catbox
    OwnerCmd --> FFmpeg
    AdminCmd --> Logger
    MemCmd --> DBUtil
    OwnerCmd --> MsgUtil
    DBUtil --> AutoRes
    BaileysWrap --> WhatsApp
    SpiderX --> SPXAPI
    Catbox --> CBXAPI
    FFmpeg --> TempFiles
    YT --> MemCmd

    %% Classes
    classDef infra fill:#b2f2bb,stroke:#2f6627,color:#000
    classDef app fill:#cfe2ff,stroke:#084298,color:#000
    classDef data fill:#ffe5b4,stroke:#b36b00,color:#000
    classDef ext fill:#f8d7da,stroke:#842029,color:#000
```
