# neoxr/neoxr-bot architecture

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

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

## Overview

NEOXR-BOT is a WhatsApp bot whose base capabilities include social-media downloads, group management, and utilities. Its main workflow receives WhatsApp events, adapts messages, applies schema and command/event handling, and responds through plugins. The map includes the documented feature families and the core connection, configuration, and persistence layers. Some plugin implementations are unsampled, so those branches are grouped by their existing directories; edges are limited to relationships shown in excerpts or documented in the README.

Main entry points: [`handler.js`](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/handler.js) (Message Handler), [`client.js`](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/client.js) (Client Setup), [`lib/listeners-extra.js`](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/listeners-extra.js) (Event Listeners), [`lib/schema.js`](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/schema.js) (Message Schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["WhatsApp Runtime"]
  node_client["Client Setup<br/>[client.js]"]
  node_engine["Baileys Engine<br/>[engine.js]"]
  node_protocol["Message Helpers<br/>[baileys.js]"]
  node_listeners["Event Listeners<br/>[listeners-extra.js]"]
end

subgraph group_handling["Message Handling"]
  node_handler["Message Handler<br/>[handler.js]"]
  node_schema["Message Schema<br/>[schema.js]"]
end

subgraph group_features["Bot Features"]
  node_download["Download Features"]
  node_auto_download["Automatic Downloads"]
  node_group_features["Group Management"]
  node_group_events["Group Protections"]
  node_convert["Media Conversion"]
  node_utilities["Utilities"]
  node_ai["AI Commands"]
  node_admin["Admin Commands"]
  node_owner["Owner Commands"]
  node_userinfo["User Information"]
end

subgraph group_state["State and Persistence"]
  node_models["Data Models<br/>[models.js]"]
  node_adapter["Storage Adapter<br/>[adapter.js]"]
  node_database[("Configured Database")]
end

subgraph group_operations["Operations"]
  node_notifier["Expiry Notifier<br/>[notifier.js]"]
  node_config["Bot Configuration<br/>[config.js]"]
end

node_user(("WhatsApp User"))
node_whatsapp(("WhatsApp Service"))
node_external_api(("Neoxr API"))

node_user -->|"sends messages"| node_whatsapp
node_whatsapp -.->|"delivers events"| node_listeners
node_client -->|"configures engine"| node_engine
node_client -->|"initializes storage"| node_adapter
node_client -->|"loads models"| node_models
node_client -->|"registers listeners"| node_listeners
node_listeners -->|"adapts messages"| node_protocol
node_listeners -->|"dispatches messages"| node_handler
node_handler -->|"initializes records"| node_schema
node_handler -.->|"dispatches commands"| node_download
node_handler -.->|"dispatches events"| node_auto_download
node_handler -.->|"dispatches commands"| node_group_features
node_handler -.->|"dispatches events"| node_group_events
node_handler -.->|"dispatches commands"| node_convert
node_handler -.->|"dispatches commands"| node_utilities
node_handler -.->|"dispatches commands"| node_ai
node_handler -.->|"dispatches commands"| node_admin
node_handler -.->|"dispatches commands"| node_owner
node_handler -.->|"dispatches commands"| node_userinfo
node_schema -->|"uses defaults"| node_models
node_adapter -->|"selects backend"| node_database
node_client -->|"starts via listeners"| node_notifier
node_notifier -.->|"checks expiry state"| node_database
node_config -->|"configures API"| node_external_api

click node_client "https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/client.js"
click node_engine "https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/engine.js"
click node_protocol "https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/baileys.js"
click node_listeners "https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/listeners-extra.js"
click node_handler "https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/handler.js"
click node_schema "https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/schema.js"
click node_download "https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/download"
click node_auto_download "https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/_events/downloader"
click node_group_features "https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/group"
click node_group_events "https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/_events"
click node_convert "https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/convert"
click node_utilities "https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/utilities"
click node_ai "https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/ai"
click node_admin "https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/admin"
click node_owner "https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/owner"
click node_userinfo "https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/userinfo"
click node_models "https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/models.js"
click node_adapter "https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/adapter.js"
click node_notifier "https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/notifier.js"
click node_config "https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/config.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_client,node_engine,node_protocol,node_listeners,node_user toneBlue
class node_handler,node_schema toneAmber
class node_download,node_auto_download,node_group_features,node_group_events,node_convert,node_utilities,node_ai,node_admin,node_owner,node_userinfo,node_external_api toneMint
class node_models,node_adapter,node_database toneRose
class node_notifier,node_config,node_whatsapp toneIndigo
```

## Components

### WhatsApp Runtime

- [Client Setup](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/client.js): `client.js`
- [Baileys Engine](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/engine.js): `lib/engine.js`
- [Message Helpers](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/baileys.js): `lib/baileys.js`
- [Event Listeners](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/listeners-extra.js): `lib/listeners-extra.js`

### Message Handling

- [Message Handler](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/handler.js): `handler.js`
- [Message Schema](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/schema.js): `lib/schema.js`

### Bot Features

- [Download Features](https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/download): `plugins/download`
- [Automatic Downloads](https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/_events/downloader): `plugins/_events/downloader`
- [Group Management](https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/group): `plugins/group`
- [Group Protections](https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/_events): `plugins/_events`
- [Media Conversion](https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/convert): `plugins/convert`
- [Utilities](https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/utilities): `plugins/utilities`
- [AI Commands](https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/ai): `plugins/ai`
- [Admin Commands](https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/admin): `plugins/admin`
- [Owner Commands](https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/owner): `plugins/owner`
- [User Information](https://github.com/neoxr/neoxr-bot/tree/5.0-ESM/plugins/userinfo): `plugins/userinfo`

### State and Persistence

- [Data Models](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/models.js): `lib/models.js`
- [Storage Adapter](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/adapter.js): `lib/adapter.js`
- **Configured Database**

### Operations

- [Expiry Notifier](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/notifier.js): `lib/notifier.js`
- [Bot Configuration](https://github.com/neoxr/neoxr-bot/blob/5.0-ESM/lib/config.js): `lib/config.js`

### Other components

- **WhatsApp User**
- **WhatsApp Service**
- **Neoxr API**

## Connections

- WhatsApp User → WhatsApp Service: sends messages
- WhatsApp Service → Event Listeners: delivers events
- Client Setup → Baileys Engine: configures engine (evidence: `client.js`)
- Client Setup → Storage Adapter: initializes storage (evidence: `client.js`)
- Client Setup → Data Models: loads models (evidence: `client.js`)
- Client Setup → Event Listeners: registers listeners (evidence: `client.js`)
- Event Listeners → Message Helpers: adapts messages (evidence: `lib/listeners-extra.js`)
- Event Listeners → Message Handler: dispatches messages (evidence: `lib/listeners-extra.js`)
- Message Handler → Message Schema: initializes records (evidence: `handler.js`)
- Message Handler → Download Features: dispatches commands
- Message Handler → Automatic Downloads: dispatches events
- Message Handler → Group Management: dispatches commands
- Message Handler → Group Protections: dispatches events
- Message Handler → Media Conversion: dispatches commands
- Message Handler → Utilities: dispatches commands
- Message Handler → AI Commands: dispatches commands
- Message Handler → Admin Commands: dispatches commands
- Message Handler → Owner Commands: dispatches commands
- Message Handler → User Information: dispatches commands
- Message Schema → Data Models: uses defaults (evidence: `lib/schema.js`)
- Storage Adapter → Configured Database: selects backend (evidence: `lib/adapter.js`)
- Client Setup → Expiry Notifier: starts via listeners
- Expiry Notifier → Configured Database: checks expiry state
- Bot Configuration → Neoxr API: configures API (evidence: `lib/config.js`)