# znanx/moon-bot architecture

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

- Interactive diagram: https://gitdiagram.com/znanx/moon-bot
- Repository: https://github.com/znanx/moon-bot

## Overview

MOON BOT is a WhatsApp automation bot built on Baileys and @znan/wabot. Its main workflow is: WhatsApp messages reach the connection initialized in main.js, listeners route them through handler.js, and command or event plugins perform the requested action and reply through the connection. Plugin capabilities span moderation, downloads, AI, media conversion, games, utilities, and group administration. main.js also initializes and periodically saves database state. The README documents optional scheduled owner backups and an HTTP health endpoint; detailed wiring for unsampled plugin families is not shown here.

Main entry points: [`plugins`](https://github.com/znanx/moon-bot/tree/master/plugins) (Command plugins), [`handler.js`](https://github.com/znanx/moon-bot/blob/master/handler.js) (Command and event router), [`main.js`](https://github.com/znanx/moon-bot/blob/master/main.js) (Connection and jobs), [`plugins/_events`](https://github.com/znanx/moon-bot/tree/master/plugins/_events) (Event plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_main["Connection and jobs<br/>[main.js]"]
  node_listeners["Message listeners<br/>[listeners.js]"]
  node_handler["Command and event router<br/>[handler.js]"]
end

subgraph group_plugins["Plugin features"]
  node_command_plugins["Command plugins"]
  node_event_plugins["Event plugins"]
  node_moderation["Moderation"]
  node_downloads["Download features"]
  node_media["Media and conversion"]
  node_ai["AI features"]
  node_games["Games"]
  node_group_admin["Group and admin"]
  node_utilities["Search and tools"]
  node_user_features["User features"]
  node_store["Group product store<br/>[product.js]"]
end

subgraph group_state["State and helpers"]
  node_database[("Bot database<br/>[localdb.js]")]
  node_schema["Data schema<br/>[schema.js]"]
  node_antispam["Spam checks<br/>[antispam.js]"]
  node_functions["Shared functions<br/>[function.js]"]
end

subgraph group_operations["Operations"]
  node_health["HTTP health endpoint<br/>[server.js]"]
end

node_user(("WhatsApp user"))
node_whatsapp(("WhatsApp service"))

node_user -->|"sends message"| node_whatsapp
node_whatsapp -->|"delivers events"| node_listeners
node_listeners -->|"dispatches messages"| node_handler
node_handler -->|"runs commands"| node_command_plugins
node_handler -->|"runs events"| node_event_plugins
node_handler -->|"checks spam"| node_antispam
node_command_plugins -->|"sends replies"| node_whatsapp
node_event_plugins -->|"sends replies"| node_whatsapp
node_main -->|"sets up listeners"| node_listeners
node_main -->|"loads and saves"| node_database
node_main -->|"initializes data"| node_schema
node_handler -->|"uses global state"| node_database
node_command_plugins -->|"uses helpers"| node_functions
node_event_plugins -->|"uses helpers"| node_functions
node_command_plugins -->|"includes moderation"| node_moderation
node_command_plugins -->|"includes downloads"| node_downloads
node_command_plugins -->|"includes conversion"| node_media
node_command_plugins -->|"includes AI"| node_ai
node_command_plugins -->|"includes games"| node_games
node_command_plugins -->|"includes controls"| node_group_admin
node_command_plugins -->|"includes tools"| node_utilities
node_command_plugins -->|"includes accounts"| node_user_features
node_command_plugins -->|"includes products"| node_store
node_main -.->|"optional status mode"| node_health

click node_main "https://github.com/znanx/moon-bot/blob/master/main.js"
click node_listeners "https://github.com/znanx/moon-bot/blob/master/lib/system/listeners.js"
click node_handler "https://github.com/znanx/moon-bot/blob/master/handler.js"
click node_command_plugins "https://github.com/znanx/moon-bot/tree/master/plugins"
click node_event_plugins "https://github.com/znanx/moon-bot/tree/master/plugins/_events"
click node_moderation "https://github.com/znanx/moon-bot/tree/master/plugins/_events/protector"
click node_downloads "https://github.com/znanx/moon-bot/tree/master/plugins/downloader"
click node_media "https://github.com/znanx/moon-bot/tree/master/plugins/converter"
click node_ai "https://github.com/znanx/moon-bot/tree/master/plugins/ai"
click node_games "https://github.com/znanx/moon-bot/tree/master/plugins/game"
click node_group_admin "https://github.com/znanx/moon-bot/tree/master/plugins/admin"
click node_utilities "https://github.com/znanx/moon-bot/tree/master/plugins/tools"
click node_user_features "https://github.com/znanx/moon-bot/tree/master/plugins/users"
click node_store "https://github.com/znanx/moon-bot/blob/master/plugins/store/product.js"
click node_database "https://github.com/znanx/moon-bot/blob/master/lib/system/localdb.js"
click node_schema "https://github.com/znanx/moon-bot/blob/master/lib/system/schema.js"
click node_antispam "https://github.com/znanx/moon-bot/blob/master/lib/system/antispam.js"
click node_functions "https://github.com/znanx/moon-bot/blob/master/lib/system/function.js"
click node_health "https://github.com/znanx/moon-bot/blob/master/server.js"

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_main,node_listeners,node_handler,node_user toneBlue
class node_command_plugins,node_event_plugins,node_moderation,node_downloads,node_media,node_ai,node_games,node_group_admin,node_utilities,node_user_features,node_store toneAmber
class node_database,node_schema,node_antispam,node_functions toneMint
class node_health toneRose
class node_whatsapp toneIndigo
```

## Components

### Bot runtime

- [Connection and jobs](https://github.com/znanx/moon-bot/blob/master/main.js): `main.js`
- [Message listeners](https://github.com/znanx/moon-bot/blob/master/lib/system/listeners.js): `lib/system/listeners.js`
- [Command and event router](https://github.com/znanx/moon-bot/blob/master/handler.js): `handler.js`

### Plugin features

- [Command plugins](https://github.com/znanx/moon-bot/tree/master/plugins): `plugins`
- [Event plugins](https://github.com/znanx/moon-bot/tree/master/plugins/_events): `plugins/_events`
- [Moderation](https://github.com/znanx/moon-bot/tree/master/plugins/_events/protector): `plugins/_events/protector`
- [Download features](https://github.com/znanx/moon-bot/tree/master/plugins/downloader): `plugins/downloader`
- [Media and conversion](https://github.com/znanx/moon-bot/tree/master/plugins/converter): `plugins/converter`
- [AI features](https://github.com/znanx/moon-bot/tree/master/plugins/ai): `plugins/ai`
- [Games](https://github.com/znanx/moon-bot/tree/master/plugins/game): `plugins/game`
- [Group and admin](https://github.com/znanx/moon-bot/tree/master/plugins/admin): `plugins/admin`
- [Search and tools](https://github.com/znanx/moon-bot/tree/master/plugins/tools): `plugins/tools`
- [User features](https://github.com/znanx/moon-bot/tree/master/plugins/users): `plugins/users`
- [Group product store](https://github.com/znanx/moon-bot/blob/master/plugins/store/product.js): `plugins/store/product.js`

### State and helpers

- [Bot database](https://github.com/znanx/moon-bot/blob/master/lib/system/localdb.js): `lib/system/localdb.js`
- [Data schema](https://github.com/znanx/moon-bot/blob/master/lib/system/schema.js): `lib/system/schema.js`
- [Spam checks](https://github.com/znanx/moon-bot/blob/master/lib/system/antispam.js): `lib/system/antispam.js`
- [Shared functions](https://github.com/znanx/moon-bot/blob/master/lib/system/function.js): `lib/system/function.js`

### Operations

- [HTTP health endpoint](https://github.com/znanx/moon-bot/blob/master/server.js): `server.js`

### Other components

- **WhatsApp user**
- **WhatsApp service**

## Connections

- WhatsApp user → WhatsApp service: sends message
- WhatsApp service → Message listeners: delivers events
- Message listeners → Command and event router: dispatches messages
- Command and event router → Command plugins: runs commands
- Command and event router → Event plugins: runs events
- Command and event router → Spam checks: checks spam
- Command plugins → WhatsApp service: sends replies
- Event plugins → WhatsApp service: sends replies
- Connection and jobs → Message listeners: sets up listeners
- Connection and jobs → Bot database: loads and saves
- Connection and jobs → Data schema: initializes data
- Command and event router → Bot database: uses global state
- Command plugins → Shared functions: uses helpers
- Event plugins → Shared functions: uses helpers
- Command plugins → Moderation: includes moderation
- Command plugins → Download features: includes downloads
- Command plugins → Media and conversion: includes conversion
- Command plugins → AI features: includes AI
- Command plugins → Games: includes games
- Command plugins → Group and admin: includes controls
- Command plugins → Search and tools: includes tools
- Command plugins → User features: includes accounts
- Command plugins → Group product store: includes products
- Connection and jobs → HTTP health endpoint: optional status mode