# clevertechnexus2/black-hat-md architecture

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

- Interactive diagram: https://gitdiagram.com/clevertechnexus2/black-hat-md
- Repository: https://github.com/clevertechnexus2/black-hat-md

## Overview

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: [`black_hat/connection/commandHandler.js`](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/commandHandler.js) (Command router), [`black_hat/index.js`](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/index.js) (Bot start), [`black_hat/connection/socketConfig.js`](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/socketConfig.js) (Socket config), [`black_hat/connection/connectionHandler.js`](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/connectionHandler.js) (Connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot & config"]
  node_root_index["Root entry<br/>bootstrap<br/>[index.js]"]
  node_bot_index["Bot start<br/>bootstrap<br/>[index.js]"]
  node_config["Config<br/>[config.js]"]
  node_settings["Settings<br/>[settings.js]"]
end

subgraph group_transport["WhatsApp transport"]
  node_socket_config["Socket config<br/>whatsapp socket<br/>[socketConfig.js]"]
  node_conn_handler["Connection<br/>lifecycle"]
  node_serializer["Serializer<br/>message normalize<br/>[serializer.js]"]
  node_cmd_handler["Command router<br/>dispatch<br/>[commandHandler.js]"]
  node_group_events["Group events<br/>event wiring<br/>[groupEvents.js]"]
end

subgraph group_commands["Commands"]
  node_group_cmd["Group admin<br/>command module<br/>[group.js]"]
  node_owner_cmd["Owner control<br/>command module<br/>[owner.js]"]
  node_media_cmd["Media tools<br/>command module<br/>[downloader.js]"]
  node_search_cmd["Search tools<br/>command module<br/>[search.js]"]
  node_utility_cmd["Utilities<br/>command module<br/>[tools.js]"]
  node_ai_cmd["AI features<br/>command module<br/>[ai.js]"]
  node_service_cmd["Special services<br/>command module<br/>[notes.js]"]
end

subgraph group_state["Persistence"]
  node_db_core[("Database core<br/>storage abstraction<br/>[database.js]")]
  node_db_domain[("State tables<br/>domain storage<br/>[settings.js]")]
  node_session_store[("Session store<br/>auth/session db<br/>[session.db]")]
end

subgraph group_games["Game engine"]
  node_game_handler["Game handler<br/>game orchestration<br/>[gameHandler.js]"]
  node_game_rules["Game rules<br/>game logic<br/>[tictactoe.js]"]
end

node_root_index -->|"starts"| node_bot_index
node_bot_index -->|"loads"| node_config
node_bot_index -->|"applies"| node_settings
node_bot_index -->|"creates socket"| node_socket_config
node_socket_config -->|"binds lifecycle"| node_conn_handler
node_socket_config -->|"normalizes"| node_serializer
node_serializer -->|"dispatches"| node_cmd_handler
node_conn_handler -->|"wires events"| node_group_events
node_cmd_handler -->|"routes"| node_group_cmd
node_cmd_handler -->|"routes"| node_owner_cmd
node_cmd_handler -->|"routes"| node_media_cmd
node_cmd_handler -->|"routes"| node_search_cmd
node_cmd_handler -->|"routes"| node_utility_cmd
node_cmd_handler -->|"routes"| node_ai_cmd
node_cmd_handler -->|"routes"| node_service_cmd
node_cmd_handler -->|"routes"| node_game_handler
node_game_handler -->|"applies rules"| node_game_rules
node_cmd_handler -->|"reads/writes"| node_db_core
node_db_core -->|"maps domains"| node_db_domain
node_conn_handler -->|"authenticates"| node_session_store
node_group_events -->|"updates"| node_db_domain
node_game_handler -->|"persists"| node_db_domain

click node_root_index "https://github.com/clevertechnexus2/black-hat-md/blob/main/index.js"
click node_bot_index "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/index.js"
click node_config "https://github.com/clevertechnexus2/black-hat-md/blob/main/config.js"
click node_settings "https://github.com/clevertechnexus2/black-hat-md/blob/main/settings.js"
click node_socket_config "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/socketConfig.js"
click node_conn_handler "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/connectionHandler.js"
click node_serializer "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/serializer.js"
click node_cmd_handler "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/commandHandler.js"
click node_group_events "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/groupEvents.js"
click node_group_cmd "https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/group.js"
click node_owner_cmd "https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/owner.js"
click node_media_cmd "https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/downloader.js"
click node_search_cmd "https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/search.js"
click node_utility_cmd "https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/tools.js"
click node_ai_cmd "https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/ai.js"
click node_service_cmd "https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/notes.js"
click node_db_core "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/database/database.js"
click node_db_domain "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/database/settings.js"
click node_session_store "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/session/session.db"
click node_game_handler "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/gameHandler.js"
click node_game_rules "https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/tictactoe.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_root_index,node_bot_index,node_config,node_settings toneBlue
class node_socket_config,node_conn_handler,node_serializer,node_cmd_handler,node_group_events toneAmber
class node_group_cmd,node_owner_cmd,node_media_cmd,node_search_cmd,node_utility_cmd,node_ai_cmd,node_service_cmd toneMint
class node_db_core,node_db_domain,node_session_store toneRose
class node_game_handler,node_game_rules toneIndigo
```

## Components

### Boot & config

Process entrypoints and runtime configuration

- [Root entry](https://github.com/clevertechnexus2/black-hat-md/blob/main/index.js): bootstrap · Top-level process entrypoint · `index.js`
- [Bot start](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/index.js): bootstrap · Main runtime bootstrap for the bot · `black_hat/index.js`
- [Config](https://github.com/clevertechnexus2/black-hat-md/blob/main/config.js): env config · Environment-driven runtime settings · `config.js`
- [Settings](https://github.com/clevertechnexus2/black-hat-md/blob/main/settings.js): runtime settings · Default bot settings and toggles · `settings.js`

### WhatsApp transport

Connection, parsing, and event dispatch to/from WhatsApp

- [Socket config](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/socketConfig.js): whatsapp socket · Creates and configures the WhatsApp socket · `black_hat/connection/socketConfig.js`
- [Connection](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/connectionHandler.js): lifecycle · Handles connect, reconnect, and session lifecycle · `black_hat/connection/connectionHandler.js`
- [Serializer](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/serializer.js): message normalize · Normalizes incoming WhatsApp messages and context · `black_hat/connection/serializer.js`
- [Command router](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/commandHandler.js): dispatch · Routes parsed messages to command modules · `black_hat/connection/commandHandler.js`
- [Group events](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/connection/groupEvents.js): event wiring · Hooks group-related updates and reactions · `black_hat/connection/groupEvents.js`

### Commands

User-facing feature modules routed from incoming messages

- [Group admin](https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/group.js): command module · Group moderation and admin workflows · `commands/group.js`
- [Owner control](https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/owner.js): command module · Owner-only control and privileged actions · `commands/owner.js`
- [Media tools](https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/downloader.js): command module · Downloader, play, and URL conversion flows · `commands/downloader.js`
- [Search tools](https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/search.js): command module · Search and lookup commands · `commands/search.js`
- [Utilities](https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/tools.js): command module · General tools, converter, logo, and helper features · `commands/tools.js`
- [AI features](https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/ai.js): command module · AI/chat generation commands · `commands/ai.js`
- [Special services](https://github.com/clevertechnexus2/black-hat-md/blob/main/commands/notes.js): command module · Notes, temp mail, shortener, sports, religion, WhatsApp utilities · `commands/notes.js`

### Persistence

Database-backed bot state and session storage

- [Database core](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/database/database.js): storage abstraction · Backend abstraction over bot persistence · `black_hat/database/database.js`
- [State tables](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/database/settings.js): domain storage · Domain-specific persistence for settings, groups, messages, notes, and identities · `black_hat/database/settings.js`
- [Session store](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/session/session.db): auth/session db · WhatsApp session and authentication persistence · `black_hat/session/session.db`

### Game engine

Interactive game rules and state flow

- [Game handler](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/gameHandler.js): game orchestration · Coordinates interactive game sessions · `black_hat/gameHandler.js`
- [Game rules](https://github.com/clevertechnexus2/black-hat-md/blob/main/black_hat/tictactoe.js): game logic · Game-specific rule engines and state transitions · `black_hat/tictactoe.js`

## Connections

- 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