How badlee/scriptbox works
Project type and purpose
• This is a full-stack Node.js SMS gateway application (“ScriptBox SMS gateway”).
• It provides an HTTP dashboard and admin UI, processes SMS messages via connectors (Kannel, SMPP, modem), runs user-defined validation/rewriter scripts, and stores data (users, SMS logs) in a file-based or in-memory DB.
File structure
• Top-level:
• bin/cli.js, bin/server.js, bin/config.js – command-line interface for config and start
• index.js – main Express app entry point
• connector.js, memory.js, vm.js – core runtime: connector manager, in-memory storage, VM sandbox
• db/ and dbProd/ – data storage folders
• models/ – schema definitions (00_user.js, 1_sms.js)
• routes/ – Express route modules (login, static, connectors, admin subroutes, healthz)
• public/ & public/admin/ – static assets for UI, CSS/JS/vendors
• scripts/ – dynamic plugins: connectors (kannel.js, smpp.js, etc.), modules, services
• views/ – server-side templates (Twig/HTML)
• Patterns:
• MVC: models ↔ routes/controllers ↔ views
• Plugin architecture: scripts/modules loaded at runtime via vm.js sandbox
• Connector abstraction: connector.js orchestrates scripts/connectors
README insights
• SMS service = “Mot Cle” (keyword) linked to a script, with validator and reject regex.
• Scripts run in isolated JavaScript context limited to 25 ms.
• Admin UI served on port 13014 (dashboard, /admin).
• Connectors configurable (Kannel, SMPP, custom modem) via CLI.
a. Main components:
1. CLI & Config subsystem (bin/)
2. HTTP Server (index.js/Express)
3. Router/Controller layer (routes/)
4. View & Static Asset layer (views/, public/, public/admin/)
5. Data Storage (db/, memory.js, models/)
6. Script Engine (vm.js + scripts/)
7. Connector Manager (connector.js)
8. Connectors (scripts/connectors/*.js)
9. External SMS Providers (Kannel HTTP/SMPP endpoint, SMPP server)
b. Relationships & interactions:
• Admin Browser ↔ HTTP Server via REST/HTML endpoints
• HTTP Server → Router/Controllers → Data Storage (CRUD on users, SMS, keywords)
• HTTP Server → Script Engine → Scripts & Modules → Data Storage (logs)
• Connector Manager → Scripts (validators, rewriters) → External Providers
• Connector listens on SMPP/Kannel port, hands SMS to Script Engine, then sends out processed SMS
c. Architectural patterns:
• MVC for web UI
• Plugin architecture: dynamic script loading isolated via VM
• Adapter pattern for connectors abstracting SMPP/Kannel/modem
• Single-process Node.js monolith with modular separation
d. Key technologies:
• Node.js and Express
• VM module for sandboxed script execution
• File-based or in-memory DB (custom, via memory.js and db folder)
• Twig or plain HTML templates
• Frontend stack: Bootstrap, jQuery, various plugins (charts, datatables, datepickers)