How clevertechnexus2/black-hat-md works
1. What this repo is
- black-hat-md is a long-running Node.js WhatsApp multi-device bot. Its core job is to keep a WhatsApp session alive, receive messages/events, route them to command modules, and persist bot state across restarts.
2. Top-level boot path
- The entrypoint is split between the root index.js and black_hat/index.js, with config.js and settings.js providing runtime configuration from environment variables.
- The runtime is designed for multiple deployment targets: Heroku, Render, Railway, Koyeb, and VPS/Docker. Dockerfile, Procfile, app.json, render.yaml, railway.toml, koyeb.yaml, and heroku.yml are deployment boundaries, not business logic.
3. WhatsApp connectivity layer
- black_hat/connection/ is the transport boundary to WhatsApp. It includes socket setup (socketConfig.js), connection lifecycle handling (connectionHandler.js), command dispatch (commandHandler.js), serialization/normalization of incoming messages (serializer.js), and group-related event wiring (groupEvents.js).
- This layer is the primary ingress/egress path: all user interactions enter here and all replies are emitted here.
4. Message routing and command execution
- The commands/ directory contains the user-facing feature modules. Incoming WhatsApp messages are parsed by the connection layer and routed into these handlers based on command category.
- The modules are organized by domain: general, group/admin, owner, settings, tools, search, downloader, play/media, games, AI, notes, tempmail, shortener, converter, sports, religion, and WhatsApp-specific utilities.
5. Core feature subsystems
- The bot is not a single monolith; it is a set of loosely grouped capability modules:
- commands/group.js, settings*.js, owner*.js for moderation and control.
- commands/downloader*.js, play.js, search*.js, tourl.js for media and link workflows.
- commands/ai.js, commands/tools*.js, commands/converter.js, commands/logo.js for utility/content generation.
- commands/notes.js, commands/tempmail.js, commands/shortener.js, commands/sports.js, commands/religion.js for specialized services.
6. Game engine boundary
- Game logic is split out of generic commands into dedicated core files under black_hat/: gameHandler.js, gameAI.js, tictactoe.js, wcg.js, and supporting files like diceGame.js and games.js in the database layer.
- This suggests a separate stateful subsystem for interactive games, with the bot acting as the transport and UI while these modules manage game rules and turn state.
7. Persistence layer
- black_hat/database/ is the storage boundary. database.js appears to abstract the backend, while domain-specific files such as settings.js, groupSettings.js, messageStore.js, notes.js, sudo.js, tempmail.js, lidMapping.js, games.js, and diceGame.js isolate different kinds of persisted state.
- The README and file layout indicate a hybrid persistence model: local SQLite for fallback/stateful runtime data and PostgreSQL when DATABASE_URL is provided.
8. Session/auth storage
- black_hat/session/ contains SQLite databases for WhatsApp authentication/session state (session.db, store.db and their WAL/SHM files).
- This is a separate persistence concern from bot data: it holds the login/session material needed to reconnect to WhatsApp, so the bot can restart without re-pairing when the session is preserved.
9. Group and context utilities
- black_hat/connection/groupCache.js, contextInfo.js, and dictionary.js are support utilities that improve message formatting, group metadata lookup, and reusable content/phrases.
- black_hat/gmdCmds.js, gmdFunctions*.js, and gmdHelpers.js look like a grouped helper layer for moderation/group-management flows, likely shared across multiple command modules.
10. Runtime dependencies and external services
- The bot depends on WhatsApp connectivity as its primary external service.
- Some commands likely call external content sources or APIs (for downloads, search, AI, shortening, temp mail, etc.), but those integrations are encapsulated behind the command modules rather than exposed as separate services.
- FFmpeg is an important system dependency for media-heavy commands, and the README explicitly calls it out for VPS/self-hosted deployments.
11. Operational model
- The process is meant to run continuously under a process manager or platform supervisor. Persistent state lives either in local SQLite files or in PostgreSQL, while the WhatsApp session and command routing stay in-memory during runtime.
- The architecture is therefore event-driven: WhatsApp events in, command handling and DB/API calls in the middle, WhatsApp replies and state updates out.
Main entry points: commandHandler.js Command router · index.js Bot start · socketConfig.js Socket config · connectionHandler.js Connection
Components 21
Boot & config
Process entrypoints and runtime configuration
- Root entry · Top-level process entrypoint
index.js - Bot start · Main runtime bootstrap for the bot
black_hat/index.js - Config · Environment-driven runtime settings
config.js - Settings · Default bot settings and toggles
settings.js
WhatsApp transport
Connection, parsing, and event dispatch to/from WhatsApp
- Socket config · Creates and configures the WhatsApp socket
black_hat/connection/socketConfig.js - Connection · Handles connect, reconnect, and session lifecycle
black_hat/connection/connectionHandler.js - Serializer · Normalizes incoming WhatsApp messages and context
black_hat/connection/serializer.js - Command router · Routes parsed messages to command modules
black_hat/connection/commandHandler.js - Group events · Hooks group-related updates and reactions
black_hat/connection/groupEvents.js
Commands
User-facing feature modules routed from incoming messages
- Group admin · Group moderation and admin workflows
commands/group.js - Owner control · Owner-only control and privileged actions
commands/owner.js - Media tools · Downloader, play, and URL conversion flows
commands/downloader.js - Search tools · Search and lookup commands
commands/search.js - Utilities · General tools, converter, logo, and helper features
commands/tools.js - AI features · AI/chat generation commands
commands/ai.js - Special services · Notes, temp mail, shortener, sports, religion, WhatsApp utilities
commands/notes.js
Persistence
Database-backed bot state and session storage
- Database core · Backend abstraction over bot persistence
black_hat/database/database.js - State tables · Domain-specific persistence for settings, groups, messages, notes, and identities
black_hat/database/settings.js - Session store · WhatsApp session and authentication persistence
black_hat/session/session.db
Game engine
Interactive game rules and state flow
- Game handler · Coordinates interactive game sessions
black_hat/gameHandler.js - Game rules · Game-specific rule engines and state transitions
black_hat/tictactoe.js
Connections 22
- Root entry → Bot start: starts · Root entry launches the bot runtime
- Bot start → Config: loads · Reads environment configuration
- Bot start → Settings: applies · Initializes runtime defaults and feature flags
- Bot start → Socket config: creates socket · Builds the WhatsApp client connection
- Socket config → Connection: binds lifecycle · Connection events are handled centrally
- Socket config → Serializer: normalizes · Incoming messages are parsed into internal form
- Serializer → Command router: dispatches · Normalized messages move into command routing
- Connection → Group events: wires events · Group updates are attached to the connection lifecycle
- Command router → Group admin: routes · Group/admin commands are executed here
- Command router → Owner control: routes · Privileged owner commands are executed here
- Command router → Media tools: routes · Downloader and play workflows are executed here
- Command router → Search tools: routes · Search-related commands are executed here
- Command router → Utilities: routes · General utilities and converters are executed here
- Command router → AI features: routes · AI-oriented commands are executed here
- Command router → Special services: routes · Special-purpose service commands are executed here
- Command router → Game handler: routes · Game commands are forwarded to the game subsystem
- Game handler → Game rules: applies rules · Game sessions use dedicated rule/state modules
- Command router → Database core: reads/writes · Commands persist and fetch bot state through the storage abstraction
- Database core → State tables: maps domains · Storage is split across domain-specific state files
- Connection → Session store: authenticates · Connection lifecycle depends on WhatsApp session persistence
- Group events → State tables: updates · Group metadata and settings are persisted
- Game handler → State tables: persists · Game state can be saved across restarts