How seedevr/quantum-bot works
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: waWorker.js Worker · CONVERSOR Converters · SUB-BOT Sub-bots · database.js DB IO
Components 27
Runtime
Startup entrypoints and the WhatsApp event worker.
- nk.js · Primary bot launcher.
nk.js - quantum.js · Alternate launcher.
quantum.js - meta.js · Additional runtime entry.
meta.js - Worker · Connects to WhatsApp, ingests messages, and dispatches commands.
lib/waWorker.js
Support
Configuration, persistence, language bundles, and media assets.
- Core helpers · Shared formatting, parsing, and bot utility functions.
lib/funciones.js - Header · Bootstrap and shared runtime header state.
lib/_header.js - Config · Bot mode, prefix, owner, limits, and policy settings.
config.json - Community DB · Local persistent state and community metadata.
basededatos/comunidad.json - DB IO · Reads and writes bot state to the local JSON database.
lib/database.js - DB write · Database write helper.
lib/escribirDB.js - Languages · Localized response text bundles for multiple languages.
lib/idiomas - Media assets · Bundled audio and image files used in replies.
multimedia
Commands
Plugin-style command domains routed from incoming events.
- Moderation · Group controls, warnings, welcome toggles, and admin tools.
lib/waCmd/ADMINS - Owner · Owner-only control plane for eval, exec, bans, and bot ops.
lib/waCmd/PROPIETARIO - Fun · Games, random prompts, profile flows, and lightweight interactions.
lib/waCmd/ALEATORIO - Search · Lookup commands for Wikipedia, images, Pinterest, and YouTube search.
lib/waCmd/BUSCADOR - Downloads · Wrappers for media download services and video/audio extraction.
lib/waCmd/DESCARGADOR - Converters · Sticker, text-effect, audio, and media conversion commands.
lib/waCmd/CONVERSOR - AI · Chat-oriented AI features.
lib/waCmd/AI - NSFW · Adult-content fetchers and aggregators.
lib/waCmd/NSFW - Anime · Anime-related content commands.
lib/waCmd/OT-ANIME - Sub-bots · Linked bot/session management and sub-bot control.
lib/waCmd/SUB-BOT
Integrations
External services and local processing tools used by commands.
- Telegram adapter · Telegram-side session and subscription support.
lib/teleCmd - Discord adapter · Discord-side session and bot support.
lib/discCmd - Media tools · Local conversion and sticker processing helpers.
lib/converter.js - WebP/MP4 · Sticker and media format conversion helper.
lib/webp2mp4.js - External APIs · Third-party search, download, generator, and content endpoints used by commands.
Connections 35
- 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.