# hmhung1/zalo-bot architecture

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

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

## Overview

This is a Zalo chat bot: it authenticates, loads command and event plugins, then turns incoming Zalo events into message objects and dispatches them to handlers. Commands can respond through the bot API; the bot also maintains user, group, and currency records, while the checktt command separately records group interaction statistics in JSON files. The excerpts show the main startup and listener wiring, but not every handler or plugin implementation, so those subsystems are represented at directory level where appropriate.

Main entry points: [`core/Client.js`](https://github.com/hmhung1/zalo-bot/blob/master/core/Client.js) (Client setup), [`core/listen.js`](https://github.com/hmhung1/zalo-bot/blob/master/core/listen.js) (Event listener), [`plugins/commands/checktt.js`](https://github.com/hmhung1/zalo-bot/blob/master/plugins/commands/checktt.js) (Group interaction stats), [`plugins/commands`](https://github.com/hmhung1/zalo-bot/tree/master/plugins/commands) (Command plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_entry["Startup entry<br/>[index.js]"]
  node_client["Client setup<br/>[Client.js]"]
  node_config["Bot configuration<br/>[config.js]"]
  node_env["Environment loader<br/>[Env.js]"]
  node_logger["Logging<br/>[log.js]"]
end

subgraph group_dispatch["Message dispatch"]
  node_listener["Event listener<br/>[listen.js]"]
  node_commands["Command handler<br/>[handleCommand.js]"]
  node_replies["Reply handler<br/>[handleReply.js]"]
  node_messages["Message handler<br/>[handleMessage.js]"]
  node_events["Event handler<br/>[handleEvent.js]"]
  node_create_records["Record initialization"]
end

subgraph group_data["Persistence"]
  node_db_config[("Database connection<br/>[index.js]")]
  node_user_model[("User model<br/>[users.js]")]
  node_group_model[("Group model<br/>[groups.js]")]
  node_currency_model[("Currency model<br/>[currencies.js]")]
  node_users["User data access<br/>[users.js]"]
  node_groups["Group data access<br/>[groups.js]"]
  node_currencies["Currency data access<br/>[currencies.js]"]
  node_interaction_files[("Interaction statistics files<br/>data store")]
end

subgraph group_features["Commands and integrations"]
  node_command_plugins["Command plugins"]
  node_checktt["Group interaction stats<br/>[checktt.js]"]
  node_plugin_events["Event plugins"]
  node_media_api["Media API helpers<br/>[api.js]"]
end

node_operator(("Bot operator"))
node_zalo{{"Zalo platform"}}

node_operator -->|"starts bot"| node_entry
node_entry -->|"starts client"| node_client
node_client -->|"reads settings"| node_config
node_client -->|"loads environment"| node_env
node_client -->|"authenticates"| node_db_config
node_client -->|"creates model"| node_user_model
node_client -->|"creates model"| node_group_model
node_client -->|"creates model"| node_currency_model
node_client -->|"starts listener"| node_listener
node_client -->|"loads plugins"| node_command_plugins
node_client -->|"loads plugins"| node_plugin_events
node_client -->|"logs in"| node_zalo
node_listener -->|"registers listener"| node_zalo
node_listener -->|"initializes access"| node_users
node_listener -->|"initializes access"| node_groups
node_listener -->|"initializes access"| node_currencies
node_listener -->|"dispatches messages"| node_commands
node_listener -->|"dispatches messages"| node_replies
node_listener -->|"dispatches messages"| node_messages
node_listener -->|"dispatches messages"| node_create_records
node_listener -->|"dispatches events"| node_events
node_replies -->|"routes reply"| node_command_plugins
node_client -->|"reports status"| node_logger
node_checktt -->|"reads group data"| node_groups
node_checktt -->|"reads user info"| node_users
node_checktt -.->|"sends responses"| node_zalo
node_checktt -->|"reads and writes"| node_interaction_files
node_command_plugins -->|"uses media helpers"| node_media_api

click node_entry "https://github.com/hmhung1/zalo-bot/blob/master/index.js"
click node_client "https://github.com/hmhung1/zalo-bot/blob/master/core/Client.js"
click node_config "https://github.com/hmhung1/zalo-bot/blob/master/config.js"
click node_env "https://github.com/hmhung1/zalo-bot/blob/master/core/util/Env.js"
click node_listener "https://github.com/hmhung1/zalo-bot/blob/master/core/listen.js"
click node_commands "https://github.com/hmhung1/zalo-bot/blob/master/core/handle/handleCommand.js"
click node_replies "https://github.com/hmhung1/zalo-bot/blob/master/core/handle/handleReply.js"
click node_messages "https://github.com/hmhung1/zalo-bot/blob/master/core/handle/handleMessage.js"
click node_events "https://github.com/hmhung1/zalo-bot/blob/master/core/handle/handleEvent.js"
click node_create_records "https://github.com/hmhung1/zalo-bot/blob/master/core/handle/handleCreateDatabase.js"
click node_db_config "https://github.com/hmhung1/zalo-bot/blob/master/core/database/data/index.js"
click node_user_model "https://github.com/hmhung1/zalo-bot/blob/master/core/database/data/models/users.js"
click node_group_model "https://github.com/hmhung1/zalo-bot/blob/master/core/database/data/models/groups.js"
click node_currency_model "https://github.com/hmhung1/zalo-bot/blob/master/core/database/data/models/currencies.js"
click node_users "https://github.com/hmhung1/zalo-bot/blob/master/core/database/users.js"
click node_groups "https://github.com/hmhung1/zalo-bot/blob/master/core/database/groups.js"
click node_currencies "https://github.com/hmhung1/zalo-bot/blob/master/core/database/currencies.js"
click node_command_plugins "https://github.com/hmhung1/zalo-bot/tree/master/plugins/commands"
click node_checktt "https://github.com/hmhung1/zalo-bot/blob/master/plugins/commands/checktt.js"
click node_plugin_events "https://github.com/hmhung1/zalo-bot/tree/master/plugins/events"
click node_media_api "https://github.com/hmhung1/zalo-bot/blob/master/core/util/api.js"
click node_logger "https://github.com/hmhung1/zalo-bot/blob/master/core/util/log.js"
click node_interaction_files "https://github.com/hmhung1/zalo-bot/tree/master/core/data/checktt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_client,node_config,node_env,node_logger toneBlue
class node_listener,node_commands,node_replies,node_messages,node_events,node_create_records toneAmber
class node_db_config,node_user_model,node_group_model,node_currency_model,node_users,node_groups,node_currencies,node_interaction_files toneMint
class node_command_plugins,node_checktt,node_plugin_events,node_media_api toneRose
class node_operator,node_zalo toneIndigo
```

## Components

### Bot runtime

- [Startup entry](https://github.com/hmhung1/zalo-bot/blob/master/index.js): `index.js`
- [Client setup](https://github.com/hmhung1/zalo-bot/blob/master/core/Client.js): `core/Client.js`
- [Bot configuration](https://github.com/hmhung1/zalo-bot/blob/master/config.js): `config.js`
- [Environment loader](https://github.com/hmhung1/zalo-bot/blob/master/core/util/Env.js): `core/util/Env.js`
- [Logging](https://github.com/hmhung1/zalo-bot/blob/master/core/util/log.js): `core/util/log.js`

### Message dispatch

- [Event listener](https://github.com/hmhung1/zalo-bot/blob/master/core/listen.js): `core/listen.js`
- [Command handler](https://github.com/hmhung1/zalo-bot/blob/master/core/handle/handleCommand.js): `core/handle/handleCommand.js`
- [Reply handler](https://github.com/hmhung1/zalo-bot/blob/master/core/handle/handleReply.js): `core/handle/handleReply.js`
- [Message handler](https://github.com/hmhung1/zalo-bot/blob/master/core/handle/handleMessage.js): `core/handle/handleMessage.js`
- [Event handler](https://github.com/hmhung1/zalo-bot/blob/master/core/handle/handleEvent.js): `core/handle/handleEvent.js`
- [Record initialization](https://github.com/hmhung1/zalo-bot/blob/master/core/handle/handleCreateDatabase.js): `core/handle/handleCreateDatabase.js`

### Persistence

- [Database connection](https://github.com/hmhung1/zalo-bot/blob/master/core/database/data/index.js): `core/database/data/index.js`
- [User model](https://github.com/hmhung1/zalo-bot/blob/master/core/database/data/models/users.js): `core/database/data/models/users.js`
- [Group model](https://github.com/hmhung1/zalo-bot/blob/master/core/database/data/models/groups.js): `core/database/data/models/groups.js`
- [Currency model](https://github.com/hmhung1/zalo-bot/blob/master/core/database/data/models/currencies.js): `core/database/data/models/currencies.js`
- [User data access](https://github.com/hmhung1/zalo-bot/blob/master/core/database/users.js): `core/database/users.js`
- [Group data access](https://github.com/hmhung1/zalo-bot/blob/master/core/database/groups.js): `core/database/groups.js`
- [Currency data access](https://github.com/hmhung1/zalo-bot/blob/master/core/database/currencies.js): `core/database/currencies.js`
- [Interaction statistics files](https://github.com/hmhung1/zalo-bot/tree/master/core/data/checktt): data store · `core/data/checktt`

### Commands and integrations

- [Command plugins](https://github.com/hmhung1/zalo-bot/tree/master/plugins/commands): `plugins/commands`
- [Group interaction stats](https://github.com/hmhung1/zalo-bot/blob/master/plugins/commands/checktt.js): `plugins/commands/checktt.js`
- [Event plugins](https://github.com/hmhung1/zalo-bot/tree/master/plugins/events): `plugins/events`
- [Media API helpers](https://github.com/hmhung1/zalo-bot/blob/master/core/util/api.js): `core/util/api.js`

### Other components

- **Bot operator**
- **Zalo platform**

## Connections

- Bot operator → Startup entry: starts bot (evidence: `README.md`)
- Startup entry → Client setup: starts client (evidence: `index.js`)
- Client setup → Bot configuration: reads settings (evidence: `core/Client.js`)
- Client setup → Environment loader: loads environment (evidence: `core/Client.js`)
- Client setup → Database connection: authenticates (evidence: `core/Client.js`)
- Client setup → User model: creates model (evidence: `core/Client.js`)
- Client setup → Group model: creates model (evidence: `core/Client.js`)
- Client setup → Currency model: creates model (evidence: `core/Client.js`)
- Client setup → Event listener: starts listener (evidence: `core/Client.js`)
- Client setup → Command plugins: loads plugins (evidence: `core/Client.js`)
- Client setup → Event plugins: loads plugins (evidence: `core/Client.js`)
- Client setup → Zalo platform: logs in (evidence: `core/Client.js`)
- Event listener → Zalo platform: registers listener (evidence: `core/listen.js`)
- Event listener → User data access: initializes access (evidence: `core/listen.js`)
- Event listener → Group data access: initializes access (evidence: `core/listen.js`)
- Event listener → Currency data access: initializes access (evidence: `core/listen.js`)
- Event listener → Command handler: dispatches messages (evidence: `core/listen.js`)
- Event listener → Reply handler: dispatches messages (evidence: `core/listen.js`)
- Event listener → Message handler: dispatches messages (evidence: `core/listen.js`)
- Event listener → Record initialization: dispatches messages (evidence: `core/listen.js`)
- Event listener → Event handler: dispatches events (evidence: `core/listen.js`)
- Reply handler → Command plugins: routes reply (evidence: `core/handle/handleReply.js`)
- Client setup → Logging: reports status (evidence: `core/Client.js`)
- Group interaction stats → Group data access: reads group data (evidence: `plugins/commands/checktt.js`)
- Group interaction stats → User data access: reads user info (evidence: `plugins/commands/checktt.js`)
- Group interaction stats → Zalo platform: sends responses
- Group interaction stats → Interaction statistics files: reads and writes (evidence: `plugins/commands/checktt.js`)
- Command plugins → Media API helpers: uses media helpers (evidence: `plugins/commands/sing.js`)
