# zelvarys/whatsapp-bot architecture

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

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

## Overview

Zelvarys is a Baileys-based WhatsApp bot. Incoming messages pass through the socket event handler and message router, which directs them to command, active-game, lobby, or chatbot handling; commands and game engines produce replies through the WhatsApp socket. The graph preserves the README’s AI, utility, media, user, owner, and game capabilities. Several command and service implementations are unsampled, so their links are shown only where the README or SOURCE INDEX supports them; optional external integrations are dashed where invocation is unverified.

Main entry points: [`src/routing/commandRouter.js`](https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/commandRouter.js) (Command Router), [`src/core/whatsappBot.js`](https://github.com/zelvarys/whatsapp-bot/blob/main/src/core/whatsappBot.js) (Bot Lifecycle), [`src/routing/messageRouter.js`](https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/messageRouter.js) (Message Router), [`src/models/userModel.js`](https://github.com/zelvarys/whatsapp-bot/blob/main/src/models/userModel.js) (User Profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_entry["Application Entry<br/>[index.js]"]
  node_bot["Bot Lifecycle<br/>[whatsappBot.js]"]
  node_socket["Socket Connection"]
  node_events["Socket Events<br/>[socketEvents.js]"]
end

subgraph group_routing["Message Routing"]
  node_message["Message Router<br/>[messageRouter.js]"]
  node_commands["Command Router<br/>[commandRouter.js]"]
  node_chatbot["Chatbot Router<br/>[chatbotRouter.js]"]
  node_game_router["Game Router<br/>[gameRouter.js]"]
  node_lobby_router["Lobby Router<br/>[lobbyRouter.js]"]
end

subgraph group_features["Commands &amp; Features"]
  node_ai_commands["AI Commands<br/>[aiCommands.js]"]
  node_utility["Utility Commands"]
  node_media_commands["Media Commands<br/>[mediaCommands.js]"]
  node_user_commands["User Commands<br/>[userCommands.js]"]
  node_owner_commands["Owner Commands<br/>[ownerCommands.js]"]
  node_other_commands["Other Commands<br/>[otherCommands.js]"]
  node_ai_services["AI Services"]
  node_media_services["Media Services"]
  node_external_services["External API Clients"]
end

subgraph group_games["Game Systems"]
  node_game_commands["Game Commands"]
  node_game_registry["Game Registry<br/>[registry.js]"]
  node_game_rules["Game Rules<br/>[gameRules.js]"]
  node_hangman["Hangman Engine<br/>[hangmanEngine.js]"]
  node_tictactoe["Tic-Tac-Toe Engine<br/>[tictactoeEngine.js]"]
  node_lobby_games["Lobby Game Engines"]
  node_lobby_state["Lobby State<br/>[lobbyState.js]"]
end

subgraph group_state["State &amp; Persistence"]
  node_user_model[("User Profiles<br/>[userModel.js]")]
  node_game_stats[("Game Statistics<br/>[gameStatsModel.js]")]
  node_bot_state[("Bot Settings<br/>[botStateModel.js]")]
  node_json_repo["JSON Repository<br/>[jsonRepository.js]"]
  node_global_state["In-Memory State<br/>[globalState.js]"]
  node_state_helpers["Command &amp; Download State<br/>[stateHelpers.js]"]
end

node_user(("WhatsApp User"))
node_whatsapp{{"WhatsApp / Baileys"}}
node_gemini{{"Gemini API"}}

node_user -->|"sends messages"| node_whatsapp
node_whatsapp -->|"delivers events"| node_events
node_entry -->|"starts"| node_bot
node_entry -->|"initializes"| node_global_state
node_entry -->|"schedules cleanup"| node_whatsapp
node_bot -->|"creates"| node_socket
node_bot -->|"registers"| node_events
node_events -->|"routes messages"| node_message
node_message -->|"routes prefixed text"| node_commands
node_message -->|"routes game replies"| node_game_router
node_message -->|"routes lobby messages"| node_lobby_router
node_message -->|"routes other text"| node_chatbot
node_commands -->|"dispatches AI"| node_ai_commands
node_commands -->|"dispatches games"| node_game_registry
node_commands -->|"dispatches utilities"| node_utility
node_commands -->|"dispatches media"| node_media_commands
node_commands -->|"dispatches user actions"| node_user_commands
node_commands -->|"dispatches owner actions"| node_owner_commands
node_commands -->|"dispatches other actions"| node_other_commands
node_ai_commands -->|"uses AI features"| node_ai_services
node_ai_commands -->|"uses speech synthesis"| node_media_services
node_ai_services -.->|"calls model API"| node_gemini
node_utility -->|"uses media processing"| node_media_services
node_media_commands -.->|"handles downloads"| node_media_services
node_user_commands -->|"reads profiles"| node_user_model
node_user_commands -->|"requests crypto data"| node_external_services
node_game_registry -->|"dispatches game types"| node_game_commands
node_game_router -->|"checks game rules"| node_game_rules
node_game_router -->|"handles moves"| node_tictactoe
node_game_router -->|"handles guesses"| node_hangman
node_game_commands -->|"starts matches"| node_tictactoe
node_game_commands -.->|"starts lobby games"| node_lobby_games
node_lobby_router -->|"manages lobbies"| node_lobby_state
node_hangman -->|"checks and updates"| node_game_rules
node_hangman -->|"awards points"| node_user_model
node_hangman -->|"records results"| node_game_stats
node_tictactoe -->|"awards points"| node_user_model
node_tictactoe -->|"records results"| node_game_stats
node_user_model -->|"persists profiles"| node_json_repo
node_game_stats -->|"persists statistics"| node_json_repo
node_bot_state -->|"persists settings"| node_json_repo
node_commands -->|"tracks cooldowns"| node_state_helpers
node_chatbot -->|"checks chatbot mode"| node_bot_state
node_chatbot -->|"generates replies"| node_ai_services
node_bot -->|"loads user data"| node_user_model
node_bot -->|"loads game stats"| node_game_stats
node_bot -->|"loads settings"| node_bot_state

click node_entry "https://github.com/zelvarys/whatsapp-bot/blob/main/index.js"
click node_bot "https://github.com/zelvarys/whatsapp-bot/blob/main/src/core/whatsappBot.js"
click node_socket "https://github.com/zelvarys/whatsapp-bot/blob/main/src/core/socketConnection.js"
click node_events "https://github.com/zelvarys/whatsapp-bot/blob/main/src/core/socketEvents.js"
click node_message "https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/messageRouter.js"
click node_commands "https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/commandRouter.js"
click node_chatbot "https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/chatbotRouter.js"
click node_game_router "https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/gameRouter.js"
click node_lobby_router "https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/lobbyRouter.js"
click node_ai_commands "https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/aiCommands.js"
click node_utility "https://github.com/zelvarys/whatsapp-bot/tree/main/src/commands/utilityCommands"
click node_media_commands "https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/mediaCommands.js"
click node_user_commands "https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/userCommands.js"
click node_owner_commands "https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/ownerCommands.js"
click node_other_commands "https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/otherCommands.js"
click node_ai_services "https://github.com/zelvarys/whatsapp-bot/tree/main/src/services/ai"
click node_media_services "https://github.com/zelvarys/whatsapp-bot/tree/main/src/services/media"
click node_external_services "https://github.com/zelvarys/whatsapp-bot/tree/main/src/services/external"
click node_game_commands "https://github.com/zelvarys/whatsapp-bot/tree/main/src/commands/gameCommands"
click node_game_registry "https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/gameCommands/registry.js"
click node_game_rules "https://github.com/zelvarys/whatsapp-bot/blob/main/src/utils/gameRules.js"
click node_hangman "https://github.com/zelvarys/whatsapp-bot/blob/main/src/services/games/hangmanEngine.js"
click node_tictactoe "https://github.com/zelvarys/whatsapp-bot/blob/main/src/services/games/tictactoeEngine.js"
click node_lobby_games "https://github.com/zelvarys/whatsapp-bot/tree/main/src/services/games"
click node_lobby_state "https://github.com/zelvarys/whatsapp-bot/blob/main/src/utils/lobbyState.js"
click node_user_model "https://github.com/zelvarys/whatsapp-bot/blob/main/src/models/userModel.js"
click node_game_stats "https://github.com/zelvarys/whatsapp-bot/blob/main/src/models/gameStatsModel.js"
click node_bot_state "https://github.com/zelvarys/whatsapp-bot/blob/main/src/models/botStateModel.js"
click node_json_repo "https://github.com/zelvarys/whatsapp-bot/blob/main/src/models/jsonRepository.js"
click node_global_state "https://github.com/zelvarys/whatsapp-bot/blob/main/src/core/globalState.js"
click node_state_helpers "https://github.com/zelvarys/whatsapp-bot/blob/main/src/utils/stateHelpers.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_entry,node_bot,node_socket,node_events,node_user toneBlue
class node_message,node_commands,node_chatbot,node_game_router,node_lobby_router toneAmber
class node_ai_commands,node_utility,node_media_commands,node_user_commands,node_owner_commands,node_other_commands,node_ai_services,node_media_services,node_external_services,node_gemini toneMint
class node_game_commands,node_game_registry,node_game_rules,node_hangman,node_tictactoe,node_lobby_games,node_lobby_state toneRose
class node_user_model,node_game_stats,node_bot_state,node_json_repo,node_global_state,node_state_helpers,node_whatsapp toneIndigo
```

## Components

### Bot Runtime

- [Application Entry](https://github.com/zelvarys/whatsapp-bot/blob/main/index.js): `index.js`
- [Bot Lifecycle](https://github.com/zelvarys/whatsapp-bot/blob/main/src/core/whatsappBot.js): `src/core/whatsappBot.js`
- [Socket Connection](https://github.com/zelvarys/whatsapp-bot/blob/main/src/core/socketConnection.js): `src/core/socketConnection.js`
- [Socket Events](https://github.com/zelvarys/whatsapp-bot/blob/main/src/core/socketEvents.js): `src/core/socketEvents.js`

### Message Routing

- [Message Router](https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/messageRouter.js): `src/routing/messageRouter.js`
- [Command Router](https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/commandRouter.js): `src/routing/commandRouter.js`
- [Chatbot Router](https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/chatbotRouter.js): `src/routing/chatbotRouter.js`
- [Game Router](https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/gameRouter.js): `src/routing/gameRouter.js`
- [Lobby Router](https://github.com/zelvarys/whatsapp-bot/blob/main/src/routing/lobbyRouter.js): `src/routing/lobbyRouter.js`

### Commands & Features

- [AI Commands](https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/aiCommands.js): `src/commands/aiCommands.js`
- [Utility Commands](https://github.com/zelvarys/whatsapp-bot/tree/main/src/commands/utilityCommands): `src/commands/utilityCommands`
- [Media Commands](https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/mediaCommands.js): `src/commands/mediaCommands.js`
- [User Commands](https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/userCommands.js): `src/commands/userCommands.js`
- [Owner Commands](https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/ownerCommands.js): `src/commands/ownerCommands.js`
- [Other Commands](https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/otherCommands.js): `src/commands/otherCommands.js`
- [AI Services](https://github.com/zelvarys/whatsapp-bot/tree/main/src/services/ai): `src/services/ai`
- [Media Services](https://github.com/zelvarys/whatsapp-bot/tree/main/src/services/media): `src/services/media`
- [External API Clients](https://github.com/zelvarys/whatsapp-bot/tree/main/src/services/external): `src/services/external`

### Game Systems

- [Game Commands](https://github.com/zelvarys/whatsapp-bot/tree/main/src/commands/gameCommands): `src/commands/gameCommands`
- [Game Registry](https://github.com/zelvarys/whatsapp-bot/blob/main/src/commands/gameCommands/registry.js): `src/commands/gameCommands/registry.js`
- [Game Rules](https://github.com/zelvarys/whatsapp-bot/blob/main/src/utils/gameRules.js): `src/utils/gameRules.js`
- [Hangman Engine](https://github.com/zelvarys/whatsapp-bot/blob/main/src/services/games/hangmanEngine.js): `src/services/games/hangmanEngine.js`
- [Tic-Tac-Toe Engine](https://github.com/zelvarys/whatsapp-bot/blob/main/src/services/games/tictactoeEngine.js): `src/services/games/tictactoeEngine.js`
- [Lobby Game Engines](https://github.com/zelvarys/whatsapp-bot/tree/main/src/services/games): `src/services/games`
- [Lobby State](https://github.com/zelvarys/whatsapp-bot/blob/main/src/utils/lobbyState.js): `src/utils/lobbyState.js`

### State & Persistence

- [User Profiles](https://github.com/zelvarys/whatsapp-bot/blob/main/src/models/userModel.js): `src/models/userModel.js`
- [Game Statistics](https://github.com/zelvarys/whatsapp-bot/blob/main/src/models/gameStatsModel.js): `src/models/gameStatsModel.js`
- [Bot Settings](https://github.com/zelvarys/whatsapp-bot/blob/main/src/models/botStateModel.js): `src/models/botStateModel.js`
- [JSON Repository](https://github.com/zelvarys/whatsapp-bot/blob/main/src/models/jsonRepository.js): `src/models/jsonRepository.js`
- [In-Memory State](https://github.com/zelvarys/whatsapp-bot/blob/main/src/core/globalState.js): `src/core/globalState.js`
- [Command & Download State](https://github.com/zelvarys/whatsapp-bot/blob/main/src/utils/stateHelpers.js): `src/utils/stateHelpers.js`

### Other components

- **WhatsApp User**
- **WhatsApp / Baileys**
- **Gemini API**

## Connections

- WhatsApp User → WhatsApp / Baileys: sends messages
- WhatsApp / Baileys → Socket Events: delivers events (evidence: `src/core/socketEvents.js`)
- Application Entry → Bot Lifecycle: starts (evidence: `index.js`)
- Application Entry → In-Memory State: initializes (evidence: `index.js`)
- Application Entry → WhatsApp / Baileys: schedules cleanup (evidence: `index.js`)
- Bot Lifecycle → Socket Connection: creates (evidence: `src/core/whatsappBot.js`)
- Bot Lifecycle → Socket Events: registers (evidence: `src/core/whatsappBot.js`)
- Socket Events → Message Router: routes messages (evidence: `src/core/socketEvents.js`)
- Message Router → Command Router: routes prefixed text (evidence: `src/routing/messageRouter.js`)
- Message Router → Game Router: routes game replies (evidence: `src/routing/messageRouter.js`)
- Message Router → Lobby Router: routes lobby messages (evidence: `src/routing/messageRouter.js`)
- Message Router → Chatbot Router: routes other text (evidence: `src/routing/messageRouter.js`)
- Command Router → AI Commands: dispatches AI (evidence: `src/routing/commandRouter.js`)
- Command Router → Game Registry: dispatches games (evidence: `src/routing/commandRouter.js`)
- Command Router → Utility Commands: dispatches utilities (evidence: `src/routing/commandRouter.js`)
- Command Router → Media Commands: dispatches media (evidence: `src/routing/commandRouter.js`)
- Command Router → User Commands: dispatches user actions (evidence: `src/routing/commandRouter.js`)
- Command Router → Owner Commands: dispatches owner actions (evidence: `src/routing/commandRouter.js`)
- Command Router → Other Commands: dispatches other actions (evidence: `src/routing/commandRouter.js`)
- AI Commands → AI Services: uses AI features (evidence: `src/commands/aiCommands.js`)
- AI Commands → Media Services: uses speech synthesis (evidence: `src/commands/aiCommands.js`)
- AI Services → Gemini API: calls model API
- Utility Commands → Media Services: uses media processing (evidence: `src/commands/utilityCommands/compress.js`)
- Media Commands → Media Services: handles downloads
- User Commands → User Profiles: reads profiles (evidence: `src/commands/userCommands.js`)
- User Commands → External API Clients: requests crypto data (evidence: `src/commands/userCommands.js`)
- Game Registry → Game Commands: dispatches game types (evidence: `src/commands/gameCommands/registry.js`)
- Game Router → Game Rules: checks game rules (evidence: `src/routing/gameRouter.js`)
- Game Router → Tic-Tac-Toe Engine: handles moves (evidence: `src/routing/gameRouter.js`)
- Game Router → Hangman Engine: handles guesses (evidence: `src/routing/gameRouter.js`)
- Game Commands → Tic-Tac-Toe Engine: starts matches (evidence: `src/commands/gameCommands/duoGames.js`)
- Game Commands → Lobby Game Engines: starts lobby games (evidence: `src/commands/gameCommands/duoGames.js`)
- Lobby Router → Lobby State: manages lobbies (evidence: `src/routing/lobbyRouter.js`)
- Hangman Engine → Game Rules: checks and updates (evidence: `src/services/games/hangmanEngine.js`)
- Hangman Engine → User Profiles: awards points (evidence: `src/services/games/hangmanEngine.js`)
- Hangman Engine → Game Statistics: records results (evidence: `src/services/games/hangmanEngine.js`)
- Tic-Tac-Toe Engine → User Profiles: awards points (evidence: `src/services/games/tictactoeEngine.js`)
- Tic-Tac-Toe Engine → Game Statistics: records results (evidence: `src/services/games/tictactoeEngine.js`)
- User Profiles → JSON Repository: persists profiles (evidence: `src/models/userModel.js`)
- Game Statistics → JSON Repository: persists statistics (evidence: `src/models/gameStatsModel.js`)
- Bot Settings → JSON Repository: persists settings (evidence: `src/models/botStateModel.js`)
- Command Router → Command & Download State: tracks cooldowns (evidence: `src/routing/commandRouter.js`)
- Chatbot Router → Bot Settings: checks chatbot mode (evidence: `src/routing/chatbotRouter.js`)
- Chatbot Router → AI Services: generates replies (evidence: `src/routing/chatbotRouter.js`)
- Bot Lifecycle → User Profiles: loads user data (evidence: `src/core/whatsappBot.js`)
- Bot Lifecycle → Game Statistics: loads game stats (evidence: `src/core/whatsappBot.js`)
- Bot Lifecycle → Bot Settings: loads settings (evidence: `src/core/whatsappBot.js`)