# seedevr/quantum-bot architecture

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

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

## Overview

1. **Project type and runtime**
   - This is a **Node.js WhatsApp multi-device bot** built around the Baileys ecosystem and meant to run on Termux, Debian/Ubuntu, or any Node.js host.
   - The repository is organized as a command-driven bot, not a traditional server app.

2. **Startup and configuration boundary**
   - The main runtime is likely launched from top-level entry files such as `nk.js`, `quantum.js`, and `meta.js`, with `package.json` defining the run scripts.
   - Runtime behavior is controlled by `config.json` and secrets/environment values in `.env`.
   - Key configuration inputs include prefix, owner accounts, bot mode, language mode, anti-spam settings, blacklist, and connection mode.

3. **Core bot engine**
   - The central orchestration layer lives under `lib/`, especially `waWorker.js`, `_header.js`, `funciones.js`, and related utility modules.
   - This layer is responsible for:
     - connecting to WhatsApp,
     - receiving messages/events,
     - parsing commands,
     - dispatching handlers,
     - and formatting responses.

4. **Command dispatch architecture**
   - The main application logic is split into a large **plugin-style command tree** under `lib/waCmd/`.
   - Each file appears to implement one command or a small feature group, making the command layer the main functional boundary of the bot.
   - The structure is capability-based rather than transport-based, which makes the architecture easy to diagram as “event in → command router → feature module → reply out.”

5. **Feature domains inside `waCmd`**
   - `ADMINS`: group-management and moderation controls such as welcome messages, tagging, warnings, and toggles.
   - `PROPIETARIO`: owner-only controls such as eval/exec, bot activation, language changes, chat banning, environment edits, and user management.
   - `JUEGOS`, `ALEATORIO`, `HERRAMIENTAS`: entertainment, random content, and utility commands.
   - `BUSCADOR`: search features like Wikipedia, Pinterest, image lookup, and YouTube search.
   - `DESCARGADOR`: media download features for YouTube, Facebook, Instagram, TikTok, MediaFire, and other source-specific wrappers.
   - `CONVERSOR`: media/text conversion features such as stickers, text-to-image/effects, audio conversion, and webp/mp4-style transformations.
   - `NSFW`, `AI`, `OT-ANIME`: specialized content services, AI chat, and anime-related outputs.

6. **Cross-platform and sub-bot support**
   - There are adapter-style directories for other transports or integration modes: `lib/teleCmd/`, `lib/discCmd/`, and `lib/waCmd/SUB-BOT/`.
   - These suggest the bot can expose similar functionality through Telegram/Discord-style command surfaces or manage linked “sub-bots” / assistant bots.
   - `serBotWa.js` appears in multiple adapter areas, implying shared service logic for connecting bot sessions.

7. **Persistence and state**
   - Persistent data is stored in a lightweight file-based database rather than an external database server.
   - `basededatos/comunidad.json` is the visible data file, with `lib/database.js` and `lib/escribirDB.js` handling reads/writes.
   - This means bot state, community settings, and likely user/group metadata are managed locally in JSON.

8. **Localization and message content**
   - Multi-language support is built in under `lib/idiomas/` with Spanish, English, Indonesian, Portuguese, and German text bundles.
   - This is a clear separation between logic and presentation text, so the diagram should show a language/content layer feeding command responses.
   - Text/media assets are also separated into `multimedia/`, keeping command code independent from static assets.

9. **Media processing pipeline**
   - Several commands rely on local media tooling and conversion helpers such as `lib/webp2mp4.js`, `lib/sticker.js`, `lib/converter.js`, and related helpers.
   - The README installation steps confirm external binaries are required: `ffmpeg`, `imagemagick`, `libwebp`, `mpv`, and `jq`.
   - This implies a pipeline where incoming media is transformed locally before being sent back to WhatsApp.

10. **External API dependence**
   - Many command families are thin wrappers over external services: search APIs, download APIs, sticker/text-effect generators, and content fetchers.
   - Files like `some_*_api.js`, `yt*`, `igdl.js`, `fbdl.js`, `pinterest.js`, `wikipedia.js`, and `rule34.js` indicate the bot aggregates multiple third-party or public endpoints.
   - For architecture purposes, these should be shown as outbound integrations from command modules to remote APIs.

11. **Moderation and safety controls**
   - The README highlights anti-link, anti-spam, anti-foreigners, anti-calls, anti-private, and anti-weird protections.
   - These controls are likely enforced in the event-processing layer before command execution, especially for group chats.
   - Owner/admin modules also support group governance features like welcome handling and chat/user restrictions.

12. **Operational modes**
   - The bot supports public/private-style behavior and a configurable “mode” in `config.json`.
   - There are also settings for minimum group size, per-command limits, blacklist, and recursion/fake-server toggles.
   - These operate as policy gates around the main command router, affecting whether a message is handled at all.

13. **Repository shape for an architecture diagram**
   - A good diagram would show:
     - WhatsApp connection at the edge,
     - a central message/event worker,
     - a command router,
     - category-based command modules,
     - local JSON state,
     - external API calls,
     - and media-processing tools.
   - The main boundary is between **event ingestion / dispatch** and **feature plugins**, with config, language packs, and multimedia as supporting layers.

Main entry points: [`lib/waWorker.js`](https://github.com/seedevr/quantum-bot/blob/main/lib/waWorker.js) (Worker), [`lib/waCmd/CONVERSOR`](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/CONVERSOR) (Converters), [`lib/waCmd/SUB-BOT`](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/SUB-BOT) (Sub-bots), [`lib/database.js`](https://github.com/seedevr/quantum-bot/blob/main/lib/database.js) (DB IO)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_nk_js["nk.js<br/>entrypoint<br/>[nk.js]"]
  node_quantum_js["quantum.js<br/>entrypoint<br/>[quantum.js]"]
  node_meta_js["meta.js<br/>entrypoint<br/>[meta.js]"]
  node_wa_worker["Worker<br/>[waWorker.js]"]
end

subgraph group_support["Support"]
  node_helpers["Core helpers<br/>runtime utils<br/>[funciones.js]"]
  node_header["Header<br/>boot config<br/>[_header.js]"]
  node_config["Config<br/>settings<br/>[config.json]"]
  node_db[("Community DB<br/>json store<br/>[comunidad.json]")]
  node_db_io["DB IO<br/>storage layer<br/>[database.js]"]
  node_db_write["DB write<br/>persistence<br/>[escribirDB.js]"]
  node_langs["Languages<br/>i18n packs"]
  node_media_assets["Media assets<br/>static assets"]
end

subgraph group_commands["Commands"]
  node_moderation["Moderation<br/>command domain"]
  node_owner["Owner<br/>command domain"]
  node_entertainment["Fun<br/>command domain"]
  node_search["Search<br/>command domain"]
  node_downloads["Downloads<br/>command domain"]
  node_conversion["Converters<br/>command domain"]
  node_ai["AI"]
  node_nsfw["NSFW<br/>command domain"]
  node_anime["Anime<br/>command domain"]
  node_subbots["Sub-bots<br/>command domain"]
end

subgraph group_integrations["Integrations"]
  node_tele_adapter["Telegram adapter<br/>cross-runtime adapter"]
  node_disc_adapter["Discord adapter<br/>cross-runtime adapter"]
  node_media_tools["Media tools<br/>local pipeline<br/>[converter.js]"]
  node_webp_mp4["WebP/MP4<br/>local pipeline<br/>[webp2mp4.js]"]
  node_external_apis[("External APIs<br/>remote services")]
end

node_nk_js -->|"launches"| node_wa_worker
node_quantum_js -->|"launches"| node_wa_worker
node_meta_js -->|"launches"| node_wa_worker
node_config -->|"policy"| node_wa_worker
node_header -->|"bootstrap"| node_wa_worker
node_wa_worker -->|"uses"| node_helpers
node_wa_worker -->|"persists"| node_db_io
node_db_io -->|"stores"| node_db
node_db_write -->|"writes"| node_db
node_wa_worker -->|"localizes"| node_langs
node_wa_worker -->|"routes"| node_moderation
node_wa_worker -->|"routes"| node_owner
node_wa_worker -->|"routes"| node_entertainment
node_wa_worker -->|"routes"| node_search
node_wa_worker -->|"routes"| node_downloads
node_wa_worker -->|"routes"| node_conversion
node_wa_worker -->|"routes"| node_ai
node_wa_worker -->|"routes"| node_nsfw
node_wa_worker -->|"routes"| node_anime
node_wa_worker -->|"routes"| node_subbots
node_moderation -.->|"calls"| node_external_apis
node_owner -.->|"calls"| node_external_apis
node_entertainment -.->|"calls"| node_external_apis
node_search -.->|"calls"| node_external_apis
node_downloads -.->|"calls"| node_external_apis
node_conversion -->|"uses"| node_media_tools
node_conversion -->|"uses"| node_webp_mp4
node_conversion -.->|"calls"| node_external_apis
node_nsfw -.->|"calls"| node_external_apis
node_anime -.->|"calls"| node_external_apis
node_subbots -->|"bridges"| node_tele_adapter
node_subbots -->|"bridges"| node_disc_adapter
node_wa_worker -->|"loads"| node_media_assets
node_wa_worker -.->|"shares logic"| node_tele_adapter
node_wa_worker -.->|"shares logic"| node_disc_adapter

click node_nk_js "https://github.com/seedevr/quantum-bot/blob/main/nk.js"
click node_quantum_js "https://github.com/seedevr/quantum-bot/blob/main/quantum.js"
click node_meta_js "https://github.com/seedevr/quantum-bot/blob/main/meta.js"
click node_wa_worker "https://github.com/seedevr/quantum-bot/blob/main/lib/waWorker.js"
click node_helpers "https://github.com/seedevr/quantum-bot/blob/main/lib/funciones.js"
click node_header "https://github.com/seedevr/quantum-bot/blob/main/lib/_header.js"
click node_config "https://github.com/seedevr/quantum-bot/blob/main/config.json"
click node_db "https://github.com/seedevr/quantum-bot/blob/main/basededatos/comunidad.json"
click node_db_io "https://github.com/seedevr/quantum-bot/blob/main/lib/database.js"
click node_db_write "https://github.com/seedevr/quantum-bot/blob/main/lib/escribirDB.js"
click node_langs "https://github.com/seedevr/quantum-bot/tree/main/lib/idiomas"
click node_media_assets "https://github.com/seedevr/quantum-bot/tree/main/multimedia"
click node_moderation "https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/ADMINS"
click node_owner "https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/PROPIETARIO"
click node_entertainment "https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/ALEATORIO"
click node_search "https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/BUSCADOR"
click node_downloads "https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/DESCARGADOR"
click node_conversion "https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/CONVERSOR"
click node_ai "https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/AI"
click node_nsfw "https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/NSFW"
click node_anime "https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/OT-ANIME"
click node_subbots "https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/SUB-BOT"
click node_tele_adapter "https://github.com/seedevr/quantum-bot/tree/main/lib/teleCmd"
click node_disc_adapter "https://github.com/seedevr/quantum-bot/tree/main/lib/discCmd"
click node_media_tools "https://github.com/seedevr/quantum-bot/blob/main/lib/converter.js"
click node_webp_mp4 "https://github.com/seedevr/quantum-bot/blob/main/lib/webp2mp4.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_nk_js,node_quantum_js,node_meta_js,node_wa_worker toneBlue
class node_helpers,node_header,node_config,node_db,node_db_io,node_db_write,node_langs,node_media_assets toneAmber
class node_moderation,node_owner,node_entertainment,node_search,node_downloads,node_conversion,node_ai,node_nsfw,node_anime,node_subbots toneMint
class node_tele_adapter,node_disc_adapter,node_media_tools,node_webp_mp4,node_external_apis toneRose
```

## Components

### Runtime

Startup entrypoints and the WhatsApp event worker.

- [nk.js](https://github.com/seedevr/quantum-bot/blob/main/nk.js): entrypoint · Primary bot launcher. · `nk.js`
- [quantum.js](https://github.com/seedevr/quantum-bot/blob/main/quantum.js): entrypoint · Alternate launcher. · `quantum.js`
- [meta.js](https://github.com/seedevr/quantum-bot/blob/main/meta.js): entrypoint · Additional runtime entry. · `meta.js`
- [Worker](https://github.com/seedevr/quantum-bot/blob/main/lib/waWorker.js): event worker · Connects to WhatsApp, ingests messages, and dispatches commands. · `lib/waWorker.js`

### Support

Configuration, persistence, language bundles, and media assets.

- [Core helpers](https://github.com/seedevr/quantum-bot/blob/main/lib/funciones.js): runtime utils · Shared formatting, parsing, and bot utility functions. · `lib/funciones.js`
- [Header](https://github.com/seedevr/quantum-bot/blob/main/lib/_header.js): boot config · Bootstrap and shared runtime header state. · `lib/_header.js`
- [Config](https://github.com/seedevr/quantum-bot/blob/main/config.json): settings · Bot mode, prefix, owner, limits, and policy settings. · `config.json`
- [Community DB](https://github.com/seedevr/quantum-bot/blob/main/basededatos/comunidad.json): json store · Local persistent state and community metadata. · `basededatos/comunidad.json`
- [DB IO](https://github.com/seedevr/quantum-bot/blob/main/lib/database.js): storage layer · Reads and writes bot state to the local JSON database. · `lib/database.js`
- [DB write](https://github.com/seedevr/quantum-bot/blob/main/lib/escribirDB.js): persistence · Database write helper. · `lib/escribirDB.js`
- [Languages](https://github.com/seedevr/quantum-bot/tree/main/lib/idiomas): i18n packs · Localized response text bundles for multiple languages. · `lib/idiomas`
- [Media assets](https://github.com/seedevr/quantum-bot/tree/main/multimedia): static assets · Bundled audio and image files used in replies. · `multimedia`

### Commands

Plugin-style command domains routed from incoming events.

- [Moderation](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/ADMINS): command domain · Group controls, warnings, welcome toggles, and admin tools. · `lib/waCmd/ADMINS`
- [Owner](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/PROPIETARIO): command domain · Owner-only control plane for eval, exec, bans, and bot ops. · `lib/waCmd/PROPIETARIO`
- [Fun](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/ALEATORIO): command domain · Games, random prompts, profile flows, and lightweight interactions. · `lib/waCmd/ALEATORIO`
- [Search](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/BUSCADOR): command domain · Lookup commands for Wikipedia, images, Pinterest, and YouTube search. · `lib/waCmd/BUSCADOR`
- [Downloads](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/DESCARGADOR): command domain · Wrappers for media download services and video/audio extraction. · `lib/waCmd/DESCARGADOR`
- [Converters](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/CONVERSOR): command domain · Sticker, text-effect, audio, and media conversion commands. · `lib/waCmd/CONVERSOR`
- [AI](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/AI): command domain · Chat-oriented AI features. · `lib/waCmd/AI`
- [NSFW](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/NSFW): command domain · Adult-content fetchers and aggregators. · `lib/waCmd/NSFW`
- [Anime](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/OT-ANIME): command domain · Anime-related content commands. · `lib/waCmd/OT-ANIME`
- [Sub-bots](https://github.com/seedevr/quantum-bot/tree/main/lib/waCmd/SUB-BOT): command domain · Linked bot/session management and sub-bot control. · `lib/waCmd/SUB-BOT`

### Integrations

External services and local processing tools used by commands.

- [Telegram adapter](https://github.com/seedevr/quantum-bot/tree/main/lib/teleCmd): cross-runtime adapter · Telegram-side session and subscription support. · `lib/teleCmd`
- [Discord adapter](https://github.com/seedevr/quantum-bot/tree/main/lib/discCmd): cross-runtime adapter · Discord-side session and bot support. · `lib/discCmd`
- [Media tools](https://github.com/seedevr/quantum-bot/blob/main/lib/converter.js): local pipeline · Local conversion and sticker processing helpers. · `lib/converter.js`
- [WebP/MP4](https://github.com/seedevr/quantum-bot/blob/main/lib/webp2mp4.js): local pipeline · Sticker and media format conversion helper. · `lib/webp2mp4.js`
- **External APIs**: remote services · Third-party search, download, generator, and content endpoints used by commands.

## Connections

- nk.js → Worker: launches · Starts the main WhatsApp worker.
- quantum.js → Worker: launches · Alternate entrypoint into the worker.
- meta.js → Worker: launches · Additional runtime entry into the worker.
- Config → Worker: policy · Provides runtime mode, limits, prefix, and owner settings.
- Header → Worker: bootstrap · Shares startup state and bootstrap values.
- Worker → Core helpers: uses · Message parsing and formatting helpers.
- Worker → DB IO: persists · Reads and updates local state.
- DB IO → Community DB: stores · Backs state with the JSON community database.
- DB write → Community DB: writes · Updates persistent JSON state.
- Worker → Languages: localizes · Selects language strings for responses.
- Worker → Moderation: routes · Dispatches moderation and group-management commands.
- Worker → Owner: routes · Dispatches owner-only control commands.
- Worker → Fun: routes · Dispatches fun and random commands.
- Worker → Search: routes · Dispatches search and lookup commands.
- Worker → Downloads: routes · Dispatches download and media-fetch commands.
- Worker → Converters: routes · Dispatches media/text conversion commands.
- Worker → AI: routes · Dispatches AI chat commands.
- Worker → NSFW: routes · Dispatches adult-content commands.
- Worker → Anime: routes · Dispatches anime-related commands.
- Worker → Sub-bots: routes · Dispatches sub-bot management commands.
- Moderation → External APIs: calls · May fetch group-related or helper data from external endpoints.
- Owner → External APIs: calls · Owner tools can fetch or control remote services.
- Fun → External APIs: calls · Uses random-content and helper APIs.
- Search → External APIs: calls · Queries lookup and search endpoints.
- Downloads → External APIs: calls · Wraps third-party download services.
- Converters → Media tools: uses · Invokes local transformation pipeline.
- Converters → WebP/MP4: uses · Handles sticker/video conversion.
- Converters → External APIs: calls · Uses remote text-effect and media generation services.
- NSFW → External APIs: calls · Fetches content from public endpoints.
- Anime → External APIs: calls · Uses anime content services.
- Sub-bots → Telegram adapter: bridges · Supports Telegram-linked sessions.
- Sub-bots → Discord adapter: bridges · Supports Discord-linked sessions.
- Worker → Media assets: loads · Reads bundled media for replies and responses.
- Worker → Telegram adapter: shares logic · Shares session logic with cross-runtime adapters.
- Worker → Discord adapter: shares logic · Shares session logic with cross-runtime adapters.
