How zoh-98/shelly works
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.