# guru322/guru-ai architecture

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

- Interactive diagram: https://gitdiagram.com/guru322/guru-ai
- Repository: https://github.com/guru322/guru-ai

## Overview

##### Project Type and Purpose
- This is a monolithic Node.js WhatsApp bot (“GURU Ai”) with a plugin-based command system plus a small frontend pairing interface.
- It connects to WhatsApp Web via a library (e.g. Baileys), provides an HTTP UI for scanning/linking, and processes incoming messages through dozens of plugin scripts.
- Persisted state (sessions, user data, logs, queues) is stored in MongoDB.

##### High-Level Components
A. Frontend Pairing Interface
- Files: index.html, index.js, Assets/…
- Served by an Express HTTP server (server.js or via index.js).
- Displays pairing QR code, connection status, and basic controls.

B. HTTP Server Layer
- server.js (or index.js) sets up the Express app, static asset routes, and WebSocket/SSE for live updates.
- handler.js orchestrates incoming HTTP requests and forwards events to the bot engine.

C. Bot Engine Core
- index.js initializes the WhatsApp Web connection, loads config.js, and starts the event loop.
- Uses lib/ modules (database.js, mongo-auth.js, queue.js, converter.js, logs.js, etc.) to handle low-level services.
- Central event dispatcher routes incoming WhatsApp messages to handler.js → Plugin Manager.

D. Plugin Manager
- Directory: plugins/
- Each file exports a command or group of commands (e.g. .ping, .alive, dl-tiktok, gp-kick).
- On message events, the manager selects the matching plugin, invokes its handler, and returns a response.

E. Persistence Layer
- MongoDB (lib/mongo-connection.js, mongo-store.js, auth modules).
- Stores user sessions, chat metadata, queues, command logs, rate-limits, etc.

F. Utility Services
- Conversion (lib/converter.js, webp.js, gifbuffer.js)
- File upload/download (lib/uploadFile.js, lib/import.js)
- Sticker, image upscaling (lib/sticker.js, lib/upscale.js)
- Temporary file cleanup (lib/tempclear.js)
- Logging (lib/logs.js)

G. External Services
- WhatsApp Web API (over websockets/HTTP)
- Optional third-party APIs invoked by plugins (e.g. TikTok, YouTube download endpoints).

##### Inter-Component Relationships & Data Flow
1. User opens browser → HTTP Server → retrieves index.html & assets → shows QR pairing.
2. HTTP Server pushes QR code events (via SSE/WebSocket) generated by Bot Engine core.
3. index.js (Bot Engine) connects to WhatsApp Web, emits events (QR code, connection, messages).
4. handler.js receives WhatsApp events, invokes Plugin Manager.
5. Plugin Manager loads appropriate plugin, may:
a. Query/modify MongoDB via lib/database.js
b. Call utility services (converter, sticker, upload)
c. Call external APIs (dl-tiktok, ai-chat, etc.)
6. Plugin returns a payload (text, media buffer) to Bot Engine → sends back to WhatsApp Web.
7. All significant actions logged (lib/logs.js) and queued (lib/queue.js) if needed.

##### Architectural Patterns & Principles
- Event-driven, plugin-based modularity: easy to add/remove commands.
- Single process, layered services: HTTP layer, core engine, plugin layer, persistence, utilities.
- Clear separation of concerns:
- server.js & handler.js for transport
- lib/ for low-level services
- plugins/ for business logic

##### Final Checklist
- Components: Browser UI, HTTP Server, Bot Engine, Plugin Manager, Utility Services, MongoDB, External APIs & WhatsApp Web
- Container boundaries for “lib/” vs. “plugins/”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser UI
    BrowserUI["📱 Browser UI"]:::external
    subgraph "Frontend Pairing Interface"
        direction TB
        IndexHTML["index.html"]:::frontend
        Assets["Assets/"]:::frontend
    end
    BrowserUI -->|"HTTP GET (HTML, JS, Assets)"| IndexHTML
    BrowserUI --> Assets

    %% HTTP Server Layer
    subgraph "HTTP Server Layer"
        direction TB
        ServerJS["server.js"]:::backend
        HandlerJS["handler.js"]:::backend
    end
    IndexHTML --> ServerJS
    Assets --> ServerJS
    ServerJS --> HandlerJS
    BrowserUI <-->|"WebSocket/SSE"| ServerJS

    %% Bot Engine Core
    subgraph "Bot Engine Core"
        direction TB
        CoreIndex["index.js"]:::backend
        ConfigJS["config.js"]:::backend
        GuruJS["Guru.js"]:::backend
    end
    HandlerJS -->|"invoke handlers"| CoreIndex
    CoreIndex --> ConfigJS
    CoreIndex --> GuruJS

    %% Plugin Manager
    subgraph "Plugin Manager"
        direction TB
        PluginsJS["lib/plugins.js"]:::plugin
        PluginsDir["plugins/"]:::plugin
    end
    CoreIndex -->|"dispatch events"| PluginsJS
    PluginsJS --> PluginsDir

    %% Utility Services
    subgraph "Utility Services"
        direction TB
        Converter["lib/converter.js"]:::utility
        Gifbuffer["lib/Gifbuffer.js"]:::utility
        Webp["lib/webp.js"]:::utility
        UploadFile["lib/uploadFile.js"]:::utility
        ImportJS["lib/import.js"]:::utility
        Sticker["lib/sticker.js"]:::utility
        Upscale["lib/upscale.js"]:::utility
        Tempclear["lib/tempclear.js"]:::utility
        LogsUtil["lib/logs.js"]:::utility
        Helper["lib/helper.js"]:::utility
        QueueUtil["lib/queque.js"]:::utility
        Loading["lib/loading.js"]:::utility
        Print["lib/print.js"]:::utility
        Simple["lib/simple.js"]:::utility
    end
    PluginsDir -->|"calls"| Converter
    PluginsDir --> Webp
    PluginsDir --> Gifbuffer
    PluginsDir --> UploadFile
    PluginsDir --> ImportJS
    PluginsDir --> Sticker
    PluginsDir --> Upscale
    PluginsDir --> Tempclear
    PluginsDir --> LogsUtil
    PluginsDir --> Helper
    PluginsDir --> QueueUtil
    PluginsDir --> Loading
    PluginsDir --> Print
    PluginsDir --> Simple

    %% Persistence Layer
    subgraph "Persistence Layer (MongoDB)"
        direction TB
        MongoConnection["lib/auth/mongo-connection.js"]:::storage
        MongoAuth["lib/auth/mongo-auth.js"]:::storage
        MongoStore["lib/auth/mongo-store.js"]:::storage
        MongoDBJS["lib/mongoDB.js"]:::storage
        DatabaseJS["lib/database.js"]:::storage
        StoreJS["lib/store.js"]:::storage
        MongoDB["MongoDB"]:::storageDB
    end
    CoreIndex -->|"driver"| MongoDBJS
    DatabaseJS --> MongoDB
    MongoConnection --> MongoDB
    MongoAuth --> MongoDB
    MongoStore --> MongoDB
    StoreJS --> MongoDB

    %% External Services
    WhatsAppWeb["☁️ WhatsApp Web API"]:::external
    ThirdParty["☁️ 3rd-Party APIs"]:::external
    CoreIndex -->|"WebSocket"| WhatsAppWeb
    PluginsDir -->|"HTTP/HTTPS"| ThirdParty

    %% Data flows
    CoreIndex -->|"logs"| LogsUtil
    CoreIndex -->|"queue ops"| QueueUtil

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        direction TB
        Dockerfile["Dockerfile"]:::config
        Workflow[".github/workflows/docker-image.yml"]:::config
        Vercel["vercel.json"]:::config
    end

    %% Legend
    subgraph Legend
        direction TB
        A["Compute Modules"]:::backend
        B["Storage Modules"]:::storage
        C["Databases"]:::storageDB
        D["External Services"]:::external
        E["Utility Services"]:::utility
        F["Plugins"]:::plugin
        G["Frontend"]:::frontend
    end

    classDef frontend fill:#B3E5FC,stroke:#0288D1,color:#000
    classDef backend fill:#BBDEFB,stroke:#1976D2,color:#000
    classDef plugin fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef utility fill:#FFF9C4,stroke:#FDD835,color:#000
    classDef storage fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef storageDB fill:#A5D6A7,stroke:#2E7D32,color:#000
    classDef external fill:#E0E0E0,stroke:#9E9E9E,color:#000
    classDef config fill:#E1BEE7,stroke:#8E24AA,color:#000

    %% Click events
    click IndexHTML "https://github.com/guru322/guru-ai/blob/main/index.html"
    click Assets "https://github.com/guru322/guru-ai/tree/main/Assets/"
    click ServerJS "https://github.com/guru322/guru-ai/blob/main/server.js"
    click HandlerJS "https://github.com/guru322/guru-ai/blob/main/handler.js"
    click CoreIndex "https://github.com/guru322/guru-ai/blob/main/index.js"
    click ConfigJS "https://github.com/guru322/guru-ai/blob/main/config.js"
    click GuruJS "https://github.com/guru322/guru-ai/blob/main/Guru.js"
    click PluginsJS "https://github.com/guru322/guru-ai/blob/main/lib/plugins.js"
    click PluginsDir "https://github.com/guru322/guru-ai/tree/main/plugins/"
    click MongoConnection "https://github.com/guru322/guru-ai/blob/main/lib/auth/mongo-connection.js"
    click MongoAuth "https://github.com/guru322/guru-ai/blob/main/lib/auth/mongo-auth.js"
    click MongoStore "https://github.com/guru322/guru-ai/blob/main/lib/auth/mongo-store.js"
    click MongoDBJS "https://github.com/guru322/guru-ai/blob/main/lib/mongoDB.js"
    click DatabaseJS "https://github.com/guru322/guru-ai/blob/main/lib/database.js"
    click StoreJS "https://github.com/guru322/guru-ai/blob/main/lib/store.js"
    click Converter "https://github.com/guru322/guru-ai/blob/main/lib/converter.js"
    click Gifbuffer "https://github.com/guru322/guru-ai/blob/main/lib/Gifbuffer.js"
    click Webp "https://github.com/guru322/guru-ai/blob/main/lib/webp.js"
    click UploadFile "https://github.com/guru322/guru-ai/blob/main/lib/uploadFile.js"
    click ImportJS "https://github.com/guru322/guru-ai/blob/main/lib/import.js"
    click Sticker "https://github.com/guru322/guru-ai/blob/main/lib/sticker.js"
    click Upscale "https://github.com/guru322/guru-ai/blob/main/lib/upscale.js"
    click Tempclear "https://github.com/guru322/guru-ai/blob/main/lib/tempclear.js"
    click LogsUtil "https://github.com/guru322/guru-ai/blob/main/lib/logs.js"
    click Helper "https://github.com/guru322/guru-ai/blob/main/lib/helper.js"
    click QueueUtil "https://github.com/guru322/guru-ai/blob/main/lib/queque.js"
    click Loading "https://github.com/guru322/guru-ai/blob/main/lib/loading.js"
    click Print "https://github.com/guru322/guru-ai/blob/main/lib/print.js"
    click Simple "https://github.com/guru322/guru-ai/blob/main/lib/simple.js"
    click Dockerfile "https://github.com/guru322/guru-ai/tree/main/Dockerfile"
    click Workflow "https://github.com/guru322/guru-ai/blob/main/.github/workflows/docker-image.yml"
    click Vercel "https://github.com/guru322/guru-ai/blob/main/vercel.json"
```
