# tungaqhd/simple-zalo-bot architecture

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

- Interactive diagram: https://gitdiagram.com/tungaqhd/simple-zalo-bot
- Repository: https://github.com/tungaqhd/simple-zalo-bot

## Overview

##### Project Type & Purpose
- This is a Node.js web application that acts as a Zalo bot. Its primary functionalities include responding according to a preset script and sending bulk messages.
- The project also features an admin panel (accessible at http://localhost:3000/admin) for managing settings or messages.

##### File Structure
- The main entry point is app.js, which likely initializes the Express server and ties together various components.
- The “config” folder includes configuration files (config.js, database.js) to set up environment parameters and database connections.
- The “helpers” folder holds bot helper logic (bot.js) that manages how the bot interacts with Zalo.
- The “middlewares” folder contains middleware functions such as adminMiddleware.js and zaloMiddleware.js, implying that some requests are filtered or processed (perhaps authentication or validation on incoming webhook requests).
- The “models” directory features a model (Robot.js), which likely encapsulates the bot’s data or state.
- The “routes” folder organizes endpoint definitions (admin.js, index.js, webhook.js) to separate concerns across admin, general routes, and the bot’s webhook handling.
- The “views” folder contains EJS templates for rendering the admin panel (admin.ejs), bot interface (robot.ejs), sending messages (send.ejs), and common header/footer components.

##### Main Components & Their Interactions
- Application Server (app.js): Acts as the orchestrator. It loads configurations, registers middleware, and binds the routes.
- Configuration Layer (config/): Supplies app settings and database connection details and influences the runtime behavior of other modules.
- Routing Layer (routes/):
- The “index.js” handles base or public routes.
- “admin.js” manages admin-specific requests and renders the admin panel which interacts with admin-specific middleware.
- “webhook.js” is designed to receive callbacks or events (likely for the Zalo bot) and hands these off to the proper middleware and helper functions.
- Bot Logic (helpers/bot.js): Contains the core logic for how the bot behaves, interprets scripts, and sends messages.
- Middleware (middlewares/): Provides additional processing (such as authentication or logging) for incoming requests, with special middleware for admin routes and Zalo interactions.
- Data Model (models/Robot.js): Represents the bot’s state or data that might be stored and manipulated.
- Presentation Layer (views/): Uses EJS templates to generate HTML for the admin panel and other user-facing pages.

##### Architectural Patterns & Design Principles
- MVC-like Separation: Although not strictly following complete MVC, the project clearly decouples configuration, routing, business logic (helpers), and presentation (views).
- Middleware Pattern: Express middlewares are used to preprocess and control request handling.
- Modular Design: Each function (bot logic, admin panel, webhook handling) is isolated into separate files/folders, promoting separation of concerns.

a. Main Components:
- Application Entry Point (app.js)
- Configuration Module (config/)
- Routing Modules (routes/ with admin, webhook, and index endpoints)
- Middleware (middlewares/)
- Bot Logic/Helper (helpers/bot.js)
- Data Model (models/Robot.js)
- Presentation Layer (views/)

b. Their Relationships/Interactions:
- The Server (app.js) loads configurations and middleware then routes incoming requests.
- Requests (from browsers or the Zalo service) hit corresponding routes (admin panel, webhook, or general endpoints) which trigger specific middleware.
- The webhook routes use the “zaloMiddleware.js” for Zalo-specific validations before passing control to the bot helper in “helpers/bot.js”.
- The admin panel routes use “adminMiddleware.js” and eventually render views from the “views/” folder.
- The bot helper may use the “models/Robot.js” to persist or retrieve bot-related data.

c. Important Patterns & Technologies:
- Use of Express.js for request handling.
- Middleware usage for request pre-processing.
- Template rendering using EJS in the views layer.
- A modular structure that separates configuration, routes, business logic, and view layers.

- Node.js runtime as the core environment.
- Separate the layers: Presentation (views), Business Logic (helpers, models), and Routes (controllers).
- Data flow:
- Interactions between routes and middleware.
- Connection from webhook endpoints to the bot helper and then to the model layer.
- Use labels for each component (e.g., “Admin Middleware”, “Zalo Middleware”, “Robot Model”).

## Diagram (Mermaid)

```mermaid
graph TD
    Client("Client"):::client
    appjs("Application Server (app.js)"):::server
    Client -->|"HTTPRequest"| appjs

    subgraph "Configuration Module"
        configConfig("config/config.js"):::config
        configDB("config/database.js"):::config
    end

    appjs -->|"loadsConfig"| configConfig
    appjs -->|"loadsConfig"| configDB

    subgraph "Routing Modules"
        adminRoute("routes/admin.js"):::routes
        indexRoute("routes/index.js"):::routes
        webhookRoute("routes/webhook.js"):::routes
    end

    appjs -->|"routesRequests"| adminRoute
    appjs -->|"routesRequests"| indexRoute
    appjs -->|"routesRequests"| webhookRoute

    subgraph "Middleware Components"
        adminMW("middlewares/adminMiddleware.js"):::middleware
        zaloMW("middlewares/zaloMiddleware.js"):::middleware
    end

    adminRoute -->|"useAdminMW"| adminMW
    webhookRoute -->|"useZaloMW"| zaloMW

    adminMW -->|"rendersAdminPanel"| adminView

    botHelper("helpers/bot.js"):::helper
    robotModel("models/Robot.js"):::model

    zaloMW -->|"triggersBotLogic"| botHelper
    botHelper -->|"managesData"| robotModel

    subgraph "Presentation Layer (Views)"
        adminView("views/admin.ejs"):::views
        robotView("views/robot.ejs"):::views
        sendView("views/send.ejs"):::views
        headerView("views/header.ejs"):::views
        footerView("views/footer.ejs"):::views
    end

    indexRoute -->|"rendersView"| robotView

    %% Click Events
    click appjs "https://github.com/tungaqhd/simple-zalo-bot/blob/master/app.js"
    click configConfig "https://github.com/tungaqhd/simple-zalo-bot/blob/master/config/config.js"
    click configDB "https://github.com/tungaqhd/simple-zalo-bot/blob/master/config/database.js"
    click adminRoute "https://github.com/tungaqhd/simple-zalo-bot/blob/master/routes/admin.js"
    click indexRoute "https://github.com/tungaqhd/simple-zalo-bot/blob/master/routes/index.js"
    click webhookRoute "https://github.com/tungaqhd/simple-zalo-bot/blob/master/routes/webhook.js"
    click adminMW "https://github.com/tungaqhd/simple-zalo-bot/blob/master/middlewares/adminMiddleware.js"
    click zaloMW "https://github.com/tungaqhd/simple-zalo-bot/blob/master/middlewares/zaloMiddleware.js"
    click botHelper "https://github.com/tungaqhd/simple-zalo-bot/blob/master/helpers/bot.js"
    click robotModel "https://github.com/tungaqhd/simple-zalo-bot/blob/master/models/Robot.js"
    click adminView "https://github.com/tungaqhd/simple-zalo-bot/blob/master/views/admin.ejs"
    click robotView "https://github.com/tungaqhd/simple-zalo-bot/blob/master/views/robot.ejs"
    click sendView "https://github.com/tungaqhd/simple-zalo-bot/blob/master/views/send.ejs"
    click headerView "https://github.com/tungaqhd/simple-zalo-bot/blob/master/views/header.ejs"
    click footerView "https://github.com/tungaqhd/simple-zalo-bot/blob/master/views/footer.ejs"

    %% Styles
    classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef server fill:#ff6666,stroke:#333,stroke-width:2px;
    classDef config fill:#66ff66,stroke:#333,stroke-width:2px;
    classDef routes fill:#66ccff,stroke:#333,stroke-width:2px;
    classDef middleware fill:#ff99cc,stroke:#333,stroke-width:2px;
    classDef helper fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef model fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef views fill:#ccffcc,stroke:#333,stroke-width:2px;
```
