# zoh-98/shelly architecture

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

- Interactive diagram: https://gitdiagram.com/zoh-98/shelly
- Repository: https://github.com/zoh-98/shelly

## Overview

##### Project type and purpose
- This is a Node.js–based Facebook Messenger chat-bot (“Shelly”) offering a plugin-style command/event framework.
- It uses an fbca submodule for Facebook Chat API integration, a modular commands/events layer under `modules/`, a lightweight data layer under `includes/database/`, plus utility and logging subpackages under `tad/` and `utils/`.

##### File structure
- Top-level entrypoints:
- `index.js` – bot bootstrapper
- `Shelly.js` – possible alias or alternate launcher
- `Procfile`, `Dockerfile` – deployment descriptors
- `config.json`, `appstate.json`, `FastConfigFca.json` – runtime & API credentials
- Subsystems:
- fbca/ – encapsulates all low-level Facebook Chat API calls
- includes/ – core services:
– controllers/ for CRUD around “users”, “threads”, “currencies”
– database/ for SQLite models + ORM
– handle/ for parsing commands, reactions, replies, events
– listen.js – bridges fbca events into handlers
- modules/ – plugin layer: commands/ (120+ JS command modules), events/ (handlers for join/leave/anti-ban, etc.)
- tad/utils/logger & utils – cross-cutting helpers for logging, coloring, general utilities
- languages/ – localization files
- Data stores:
- `includes/data.sqlite` – default SQLite DB
- Some modules reference a `mongoDB/` folder for optional Mongo integration
- Config & deployment: Procfile for Heroku; Dockerfile for containerization.

##### Key insights from README
- Minimal project description (“Shelly Bot – exceptional copy”)

##### Main components and interactions
a. Components
1. Bot Core (index.js / Shelly.js)
2. Facebook Chat API Adapter (fbca)
3. Event Dispatcher (includes/listen.js → includes/handle/)
4. Command Plugins (modules/commands)
5. Event Plugins (modules/events)
6. Data Layer (includes/database + controllers + data.sqlite)
7. Utility Services (tad/utils, utils/)
8. External Services:
- Facebook Messenger Real-time API (MQTT socket)
- Optional MongoDB instance
b. Relationships & Data Flows
- Bot Core initializes config, connects to fbca → opens WebSocket/MQTT →
- Incoming messages/events flow into Event Dispatcher →
- Dispatcher routes to:
- Command Handler → matching module in modules/commands
- Event Handler → matching module in modules/events
- Command/Event modules may:
- Invoke fbca HTTP methods (sendMessage, markAsRead, etc.)
- Read/write via controllers → SQLite (or Mongo)
- Log via tad/utils/logger
- Outgoing responses go back through fbca to Facebook.
c. Architectural patterns & principles
- Plugin pattern for commands/events → add/remove features without touching core.
- Layered architecture: Adapter (fbca) → Dispatcher → Plugins → Persistence → Utilities.
- Separation of concerns: fbca handles the protocol; modules focus on business logic; database code centralized in includes/database.
d. Key technologies & libraries
- Node.js & npm (package.json)
- fbca (Facebook Chat API client)
- SQLite (node-sqlite3) via includes/database
- Optional MongoDB
- MQTT for real-time events (listenMqtt)
- Docker, Heroku (Procfile), dotenv-style config.

##### Detailed capture of essential elements
- Role of `includes/controllers` vs `includes/database` vs `modules/commands`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Deployment
    subgraph "Configuration & Deployment" 
        CFG["config.json, appstate.json, FastConfigFca.json"]:::config
        DEP["Procfile, Dockerfile"]:::config
    end

    %% Core Layer
    subgraph "Bot Core" 
        BC1["index.js"]:::core
        BC2["Shelly.js"]:::core
    end

    %% Adapter Layer
    subgraph "Facebook API Adapter (fbca)" 
        FBCA["fbca/"]:::core
    end

    %% Dispatcher Layer
    subgraph "Event Dispatcher" 
        LISTEN["includes/listen.js"]:::core
        HANDLE["includes/handle/"]:::core
    end

    %% Plugin Layer
    subgraph "Command Plugins" 
        CMDS["modules/commands/"]:::plugin
    end

    subgraph "Event Plugins" 
        EVTS["modules/events/"]:::plugin
    end

    %% Data Layer
    subgraph "Data Layer"
        ORMMOD["includes/database/"]:::db
        CTRL["includes/controllers/"]:::db
        SQLITE["includes/data.sqlite"]:::db
    end

    %% Utility Layer
    subgraph "Utility Services"
        TAD["tad/utils/"]:::util
        UTILS["utils/"]:::util
    end

    %% External Services
    FB["Facebook Messenger API"]:::external
    Mongo["Optional MongoDB"]:::external

    %% Relationships
    CFG -->|loads config| BC1
    DEP -->|deployment| BC1

    BC1 -->|"initializes"| FBCA
    BC1 -->|"starts event bridge"| LISTEN

    FBCA -->|"websocket/MQTT"| FB
    FBCA -->|"HTTP sendMessage/sendRead"| FB

    LISTEN -->|"incoming events"| HANDLE
    HANDLE -->|"routes to commands"| CMDS
    HANDLE -->|"routes to events"| EVTS

    CMDS -->|"invoke adapter"| FBCA
    CMDS -->|"use controllers"| CTRL
    CMDS -->|"log via util"| TAD

    EVTS -->|"invoke adapter"| FBCA
    EVTS -->|"use controllers"| CTRL
    EVTS -->|"log via util"| TAD

    CTRL -->|"reads/writes"| ORMMOD
    ORMMOD -->|"persists"| SQLITE
    CMDS -.->|"optional ops"| Mongo
    EVTS -.->|"optional ops"| Mongo

    BC1 -->|"uses utils"| UTILS
    TAD -->|"helper functions"| UTILS

    %% Click Events
    click BC1 "https://github.com/zoh-98/shelly/blob/main/index.js"
    click BC2 "https://github.com/zoh-98/shelly/blob/main/Shelly.js"
    click FBCA "https://github.com/zoh-98/shelly/tree/main/fbca/"
    click LISTEN "https://github.com/zoh-98/shelly/blob/main/includes/listen.js"
    click HANDLE "https://github.com/zoh-98/shelly/tree/main/includes/handle/"
    click CMDS "https://github.com/zoh-98/shelly/tree/main/modules/commands/"
    click EVTS "https://github.com/zoh-98/shelly/tree/main/modules/events/"
    click ORMMOD "https://github.com/zoh-98/shelly/tree/main/includes/database/"
    click CTRL "https://github.com/zoh-98/shelly/tree/main/includes/controllers/"
    click SQLITE "https://github.com/zoh-98/shelly/blob/main/includes/data.sqlite"
    click TAD "https://github.com/zoh-98/shelly/tree/main/tad/utils/"
    click UTILS "https://github.com/zoh-98/shelly/tree/main/utils/"
    click CFG "https://github.com/zoh-98/shelly/blob/main/config.json"
    click DEP "https://github.com/zoh-98/shelly/tree/main/Procfile"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef plugin fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef db fill:#ffe0b2,stroke:#333,stroke-width:1px;
    classDef util fill:#e1bee7,stroke:#333,stroke-width:1px;
    classDef external fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef config fill:#f0f0f0,stroke:#333,stroke-width:1px;
```
