# tassiocarvalho/bot_marc architecture

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

- Interactive diagram: https://gitdiagram.com/tassiocarvalho/bot_marc
- Repository: https://github.com/tassiocarvalho/bot_marc

## Overview

bot_marc is a multifunction WhatsApp bot built on Baileys. WhatsApp events enter through the connection and event loader; incoming messages are filtered, enriched with common command functions, and dispatched to commands or group-moderation handlers, which reply or act through the WhatsApp socket. The product also includes administration, media/download and AI commands, games, and group-status features. The graph emphasizes this runtime path and the central internal services. Several command families and integrations are documented by the tree or README but were not sampled, so their internal call paths are not inferred.

Main entry points: [`src/commands/member`](https://github.com/tassiocarvalho/bot_marc/tree/main/src/commands/member) (Member Commands), [`src/middlewares/onMesssagesUpsert.js`](https://github.com/tassiocarvalho/bot_marc/blob/main/src/middlewares/onMesssagesUpsert.js) (Message Events), [`src/connection.js`](https://github.com/tassiocarvalho/bot_marc/blob/main/src/connection.js) (Connection), [`src/loader.js`](https://github.com/tassiocarvalho/bot_marc/blob/main/src/loader.js) (Event Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and Events"]
  node_entry["Bot Entry<br/>[index.js]"]
  node_connection["Connection<br/>[connection.js]"]
  node_event_loader["Event Loader<br/>[loader.js]"]
  node_message_events["Message Events"]
  node_participant_events["Participant Events"]
  node_command_dispatch["Command Dispatch<br/>[dynamicCommand.js]"]
end

subgraph group_commands["Bot Commands"]
  node_commands["Command Families"]
  node_admin_commands["Admin Commands"]
  node_member_commands["Member Commands"]
  node_owner_commands["Owner Commands"]
end

subgraph group_moderation["Group Moderation"]
  node_message_moderation["Message Moderation<br/>[messageHandler.js]"]
  node_middleware_policy["Middleware Policy<br/>[index.js]"]
end

subgraph group_services["Domain Services"]
  node_download_queue["Download Queue<br/>[download-queue.js]"]
  node_spider_api["Spider X API<br/>[spider-x-api.js]"]
  node_sticker_service["Sticker Processing<br/>[sticker.js]"]
  node_pet_game["Pet Game<br/>[pet.js]"]
  node_pet_art["Pet Artwork<br/>[pet-art.js]"]
  node_group_status["Group Status<br/>[groupStatus.js]"]
  node_status_video["Status Video<br/>[statusVideo.js]"]
  node_rps["Rock Paper Scissors"]
  node_hangman["Hangman<br/>[hangman.js]"]
  node_tic_tac_toe["Tic Tac Toe<br/>[tic-tac-toe.js]"]
end

subgraph group_foundation["Shared Foundation"]
  node_common_functions["Command Context"]
  node_database[("Local State<br/>[database.js]")]
  node_config["Bot Configuration<br/>[config.js]"]
  node_common_utils["Shared Utilities<br/>[index.js]"]
  node_envelope_registry["Message Envelope"]
  node_payment_detection["Payment Detection<br/>[paymentMessage.js]"]
  node_bad_mac["Session Error Handling<br/>[badMacHandler.js]"]
end

node_whatsapp(("WhatsApp"))
node_external_apis{{"External APIs"}}

node_entry -->|"starts"| node_connection
node_connection -->|"connects"| node_whatsapp
node_connection -->|"loads events"| node_event_loader
node_event_loader -->|"registers"| node_message_events
node_message_events -->|"checks messages"| node_message_moderation
node_message_events -->|"dispatches updates"| node_participant_events
node_message_events -->|"builds context"| node_common_functions
node_message_events -->|"dispatches commands"| node_command_dispatch
node_command_dispatch -.->|"loads command"| node_commands
node_message_moderation -->|"reads restrictions"| node_database
node_message_moderation -->|"checks admin"| node_middleware_policy
node_middleware_policy -->|"reads prefix"| node_database
node_message_moderation -->|"detects payments"| node_payment_detection
node_message_events -->|"records envelope"| node_envelope_registry
node_event_loader -->|"connects queue"| node_download_queue
node_event_loader -->|"loads queue state"| node_database
node_event_loader -->|"handles errors"| node_bad_mac
node_connection -->|"handles session errors"| node_bad_mac
node_connection -->|"prepares group folders"| node_pet_game
node_pet_game -->|"uses artwork"| node_pet_art
node_participant_events -->|"reads state"| node_database
node_commands -.->|"contains"| node_admin_commands
node_commands -.->|"contains"| node_member_commands
node_commands -.->|"contains"| node_owner_commands
node_admin_commands -.->|"uses group state"| node_database
node_member_commands -.->|"uses API"| node_spider_api
node_member_commands -.->|"uses stickers"| node_sticker_service
node_member_commands -.->|"supports games"| node_rps
node_member_commands -.->|"supports games"| node_hangman
node_member_commands -.->|"supports games"| node_tic_tac_toe
node_member_commands -.->|"uses status"| node_group_status
node_member_commands -.->|"uses status video"| node_status_video
node_command_dispatch -.->|"uses utilities"| node_common_utils
node_common_functions -.->|"uses settings"| node_config
node_spider_api -.->|"calls API"| node_external_apis

click node_entry "https://github.com/tassiocarvalho/bot_marc/blob/main/src/index.js"
click node_connection "https://github.com/tassiocarvalho/bot_marc/blob/main/src/connection.js"
click node_event_loader "https://github.com/tassiocarvalho/bot_marc/blob/main/src/loader.js"
click node_message_events "https://github.com/tassiocarvalho/bot_marc/blob/main/src/middlewares/onMesssagesUpsert.js"
click node_participant_events "https://github.com/tassiocarvalho/bot_marc/blob/main/src/middlewares/onGroupParticipantsUpdate.js"
click node_command_dispatch "https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/dynamicCommand.js"
click node_common_functions "https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/loadCommonFunctions.js"
click node_commands "https://github.com/tassiocarvalho/bot_marc/tree/main/src/commands"
click node_admin_commands "https://github.com/tassiocarvalho/bot_marc/tree/main/src/commands/admin"
click node_member_commands "https://github.com/tassiocarvalho/bot_marc/tree/main/src/commands/member"
click node_owner_commands "https://github.com/tassiocarvalho/bot_marc/tree/main/src/commands/owner"
click node_message_moderation "https://github.com/tassiocarvalho/bot_marc/blob/main/src/middlewares/messageHandler.js"
click node_middleware_policy "https://github.com/tassiocarvalho/bot_marc/blob/main/src/middlewares/index.js"
click node_database "https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/database.js"
click node_config "https://github.com/tassiocarvalho/bot_marc/blob/main/src/config.js"
click node_common_utils "https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/index.js"
click node_envelope_registry "https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/messageEnvelopeRegistry.js"
click node_payment_detection "https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/paymentMessage.js"
click node_bad_mac "https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/badMacHandler.js"
click node_download_queue "https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/download-queue.js"
click node_spider_api "https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/spider-x-api.js"
click node_sticker_service "https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/sticker.js"
click node_pet_game "https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/pet.js"
click node_pet_art "https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/pet-art.js"
click node_group_status "https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/groupStatus.js"
click node_status_video "https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/statusVideo.js"
click node_rps "https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/rock-paper-scissors.js"
click node_hangman "https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/hangman.js"
click node_tic_tac_toe "https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/tic-tac-toe.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_connection,node_event_loader,node_message_events,node_participant_events,node_command_dispatch toneBlue
class node_commands,node_admin_commands,node_member_commands,node_owner_commands toneAmber
class node_message_moderation,node_middleware_policy,node_external_apis toneMint
class node_download_queue,node_spider_api,node_sticker_service,node_pet_game,node_pet_art,node_group_status,node_status_video,node_rps,node_hangman,node_tic_tac_toe toneRose
class node_common_functions,node_database,node_config,node_common_utils,node_envelope_registry,node_payment_detection,node_bad_mac,node_whatsapp toneIndigo
```

## Components

### Runtime and Events

- [Bot Entry](https://github.com/tassiocarvalho/bot_marc/blob/main/src/index.js): `src/index.js`
- [Connection](https://github.com/tassiocarvalho/bot_marc/blob/main/src/connection.js): `src/connection.js`
- [Event Loader](https://github.com/tassiocarvalho/bot_marc/blob/main/src/loader.js): `src/loader.js`
- [Message Events](https://github.com/tassiocarvalho/bot_marc/blob/main/src/middlewares/onMesssagesUpsert.js): `src/middlewares/onMesssagesUpsert.js`
- [Participant Events](https://github.com/tassiocarvalho/bot_marc/blob/main/src/middlewares/onGroupParticipantsUpdate.js): `src/middlewares/onGroupParticipantsUpdate.js`
- [Command Dispatch](https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/dynamicCommand.js): `src/utils/dynamicCommand.js`

### Bot Commands

- [Command Families](https://github.com/tassiocarvalho/bot_marc/tree/main/src/commands): `src/commands`
- [Admin Commands](https://github.com/tassiocarvalho/bot_marc/tree/main/src/commands/admin): `src/commands/admin`
- [Member Commands](https://github.com/tassiocarvalho/bot_marc/tree/main/src/commands/member): `src/commands/member`
- [Owner Commands](https://github.com/tassiocarvalho/bot_marc/tree/main/src/commands/owner): `src/commands/owner`

### Group Moderation

- [Message Moderation](https://github.com/tassiocarvalho/bot_marc/blob/main/src/middlewares/messageHandler.js): `src/middlewares/messageHandler.js`
- [Middleware Policy](https://github.com/tassiocarvalho/bot_marc/blob/main/src/middlewares/index.js): `src/middlewares/index.js`

### Domain Services

- [Download Queue](https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/download-queue.js): `src/services/download-queue.js`
- [Spider X API](https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/spider-x-api.js): `src/services/spider-x-api.js`
- [Sticker Processing](https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/sticker.js): `src/services/sticker.js`
- [Pet Game](https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/pet.js): `src/services/pet.js`
- [Pet Artwork](https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/pet-art.js): `src/services/pet-art.js`
- [Group Status](https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/groupStatus.js): `src/services/groupStatus.js`
- [Status Video](https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/statusVideo.js): `src/services/statusVideo.js`
- [Rock Paper Scissors](https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/rock-paper-scissors.js): `src/services/rock-paper-scissors.js`
- [Hangman](https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/hangman.js): `src/services/hangman.js`
- [Tic Tac Toe](https://github.com/tassiocarvalho/bot_marc/blob/main/src/services/tic-tac-toe.js): `src/services/tic-tac-toe.js`

### Shared Foundation

- [Command Context](https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/loadCommonFunctions.js): `src/utils/loadCommonFunctions.js`
- [Local State](https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/database.js): `src/utils/database.js`
- [Bot Configuration](https://github.com/tassiocarvalho/bot_marc/blob/main/src/config.js): `src/config.js`
- [Shared Utilities](https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/index.js): `src/utils/index.js`
- [Message Envelope](https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/messageEnvelopeRegistry.js): `src/utils/messageEnvelopeRegistry.js`
- [Payment Detection](https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/paymentMessage.js): `src/utils/paymentMessage.js`
- [Session Error Handling](https://github.com/tassiocarvalho/bot_marc/blob/main/src/utils/badMacHandler.js): `src/utils/badMacHandler.js`

### Other components

- **WhatsApp**
- **External APIs**

## Connections

- Bot Entry → Connection: starts (evidence: `src/index.js`)
- Connection → WhatsApp: connects (evidence: `src/connection.js`)
- Connection → Event Loader: loads events (evidence: `src/connection.js`)
- Event Loader → Message Events: registers (evidence: `src/loader.js`)
- Message Events → Message Moderation: checks messages (evidence: `src/middlewares/onMesssagesUpsert.js`)
- Message Events → Participant Events: dispatches updates (evidence: `src/middlewares/onMesssagesUpsert.js`)
- Message Events → Command Context: builds context (evidence: `src/middlewares/onMesssagesUpsert.js`)
- Message Events → Command Dispatch: dispatches commands (evidence: `src/middlewares/onMesssagesUpsert.js`)
- Command Dispatch → Command Families: loads command
- Message Moderation → Local State: reads restrictions (evidence: `src/middlewares/messageHandler.js`)
- Message Moderation → Middleware Policy: checks admin (evidence: `src/middlewares/messageHandler.js`)
- Middleware Policy → Local State: reads prefix (evidence: `src/middlewares/index.js`)
- Message Moderation → Payment Detection: detects payments (evidence: `src/middlewares/messageHandler.js`)
- Message Events → Message Envelope: records envelope (evidence: `src/middlewares/onMesssagesUpsert.js`)
- Event Loader → Download Queue: connects queue (evidence: `src/loader.js`)
- Event Loader → Local State: loads queue state (evidence: `src/loader.js`)
- Event Loader → Session Error Handling: handles errors (evidence: `src/loader.js`)
- Connection → Session Error Handling: handles session errors (evidence: `src/connection.js`)
- Connection → Pet Game: prepares group folders (evidence: `src/connection.js`)
- Pet Game → Pet Artwork: uses artwork (evidence: `src/services/pet.js`)
- Participant Events → Local State: reads state (evidence: `src/middlewares/onGroupParticipantsUpdate.js`)
- Command Families → Admin Commands: contains
- Command Families → Member Commands: contains
- Command Families → Owner Commands: contains
- Admin Commands → Local State: uses group state
- Member Commands → Spider X API: uses API (evidence: `src/commands/member/search/yt-search.js`)
- Member Commands → Sticker Processing: uses stickers (evidence: `src/commands/member/funny/pet.js`)
- Member Commands → Rock Paper Scissors: supports games
- Member Commands → Hangman: supports games
- Member Commands → Tic Tac Toe: supports games
- Member Commands → Group Status: uses status
- Member Commands → Status Video: uses status video
- Command Dispatch → Shared Utilities: uses utilities
- Command Context → Bot Configuration: uses settings (evidence: `src/utils/loadCommonFunctions.js`)
- Spider X API → External APIs: calls API
