# nivagameco/chatbot architecture

> Architecture diagram of the GitHub repository nivagameco/chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nivagameco/chatbot
- Repository: https://github.com/nivagameco/chatbot

## Overview

##### Project Type and Purpose
- This project is a Facebook bot built with Node.js that interacts with users on Facebook Messenger. It integrates with the OpenAI API to enable chat functionality (via the /ask command) and also supports utility commands like /roll, /ping, and /uptime.
- The README highlights that users must supply Facebook cookies (fbstate.json) and an OpenAI API key, which indicates both account interaction and external API communication.

##### Analyzing the File Structure
- Top-Level Files:
- index.js: The entry point of the bot.
- package.json: Defines the Node.js dependencies and scripts.
- README.md, LICENSE, .gitignore: Standard project documentation and version control configurations.
- Directories:
- commands: Contains separate subdirectories (fun and information) for command modules. For instance, fun has /ask and /roll, while information has /ping and /uptime.
- config: Contains configuration files (config.js for bot settings, fbstate.json for Facebook cookies).
- events: Contains event handlers, such as messageCreate.js – the entry point for processing Facebook messages.
- handlers: Contains modular components for dispatching commands (command.js) and events (event.js).

##### Key Components
a. Main Application (index.js):
- Acts as the bootstrapping element.
- Loads configuration and initializes event handlers.
b. Configuration Module:
- Configuration settings are managed in the config folder (config.js and fbstate.json).
- This module holds API keys, command prefix, caching, ratelimits, and cookie data for Facebook.
c. Event Handling:
- The events directory (e.g., messageCreate.js) listens to incoming messages.
d. Command Handling:
- The handlers folder (command.js and event.js) dispatches appropriate commands based on detected messages.
- The commands directory is structured into categories (fun and information). Each command (ask, roll, ping, uptime) is modularized into its own file.
e. External Interactions:
- Facebook Platform: The bot uses data from fbstate.json to communicate with Facebook.
- OpenAI API: Invoked during the /ask command to obtain responses from ChatGPT.

##### Interactions and Data Flow
- Start at the Main Application (index.js) which loads the configuration.
- The bot listens for events using modules in the events directory (e.g., messageCreate.js). These events are triggered by Facebook messages.
- On receiving a message, the event handler forwards the data to the command handler (located in handlers/command.js).
- The command handler checks the command folder structure and executes the appropriate module (either in commands/fun or commands/information).
- For example, when a user types /ask, the corresponding command (commands/fun/ask.js) sends a request to the OpenAI API.
- The response (or result) is then sent back as a message through the Facebook API using the bot’s state (fbstate.json).

##### Architectural Patterns and Principles
- Modularity: The project is divided into distinct modules (commands, events, handlers) which makes it easy to maintain and extend.
- Separation of Concerns: Different files and directories handle configuration, event processing, and command processing separately.
- Plug-in Approach: The command structure is designed to allow additional commands to be added without affecting other parts of the system.
- External API Integration: Clear boundaries for integrating with the OpenAI API for chat functions and using Facebook authentication/cookies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Initialization
    subgraph "Initialization"
        MainApp("Main Application (index.js)"):::internal
        ConfigFile("Config File (config/config.js)"):::internal
        FbCookie("Facebook Cookie (config/fbstate.json)"):::internal
    end

    %% Event Processing
    subgraph "Event Processing"
        FB("Facebook Platform"):::external
        EventListener("Event Listener (events/messageCreate.js)"):::internal
    end

    %% Command Handling
    subgraph "Command Handling"
        CmdDispatcher("Command Dispatcher (handlers/command.js)"):::internal
        EventHandler("Event Handler (handlers/event.js)"):::internal
    end

    %% Command Modules
    subgraph "Command Modules"
        subgraph "Fun Commands"
            Ask("Ask Command (/ask) (commands/fun/ask.js)"):::internal
            Roll("Roll Command (/roll) (commands/fun/roll.js)"):::internal
        end
        subgraph "Information Commands"
            Ping("Ping Command (/ping) (commands/information/ping.js)"):::internal
            Uptime("Uptime Command (/uptime) (commands/information/uptime.js)"):::internal
        end
    end

    %% External Service
    OpenAI("OpenAI API"):::external

    %% Data Flow / Relationships
    MainApp -->|"loads"| ConfigFile
    MainApp -->|"loads"| FbCookie

    FB -->|"sendsMessage"| EventListener
    EventListener -->|"forwards"| CmdDispatcher

    CmdDispatcher -->|"triggers"| Ask
    CmdDispatcher -->|"triggers"| Roll
    CmdDispatcher -->|"triggers"| Ping
    CmdDispatcher -->|"triggers"| Uptime

    Ask -->|"calls"| OpenAI
    OpenAI -->|"responds"| Ask

    %% Click Events
    click MainApp "https://github.com/nivagameco/chatbot/blob/main/index.js"
    click ConfigFile "https://github.com/nivagameco/chatbot/blob/main/config/config.js"
    click FbCookie "https://github.com/nivagameco/chatbot/blob/main/config/fbstate.json"
    click EventListener "https://github.com/nivagameco/chatbot/blob/main/events/messageCreate.js"
    click CmdDispatcher "https://github.com/nivagameco/chatbot/blob/main/handlers/command.js"
    click EventHandler "https://github.com/nivagameco/chatbot/blob/main/handlers/event.js"
    click Ask "https://github.com/nivagameco/chatbot/blob/main/commands/fun/ask.js"
    click Roll "https://github.com/nivagameco/chatbot/blob/main/commands/fun/roll.js"
    click Ping "https://github.com/nivagameco/chatbot/blob/main/commands/information/ping.js"
    click Uptime "https://github.com/nivagameco/chatbot/blob/main/commands/information/uptime.js"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px;
```
