# badlee/scriptbox architecture

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

- Interactive diagram: https://gitdiagram.com/badlee/scriptbox
- Repository: https://github.com/badlee/scriptbox

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    AdminBrowser["Admin Browser"]:::ext
    ExternalSMS["External SMS Providers\n(Kannel HTTP, SMPP)"]:::ext

    %% CLI & Config Subsystem
    subgraph "CLI & Config Subsystem"
        CLI["CLI & Config"]:::server
        click CLI "https://github.com/badlee/scriptbox/blob/master/bin/cli.js"
        click CLI "https://github.com/badlee/scriptbox/blob/master/bin/config.js"
        click CLI "https://github.com/badlee/scriptbox/blob/master/bin/server.js"
    end

    %% Settings
    Settings["Application Settings\nsettings.js\nsettings.json\nsettings.json.dist"]:::server
    click Settings "https://github.com/badlee/scriptbox/blob/master/settings.js"
    click Settings "https://github.com/badlee/scriptbox/blob/master/settings.json"
    click Settings "https://github.com/badlee/scriptbox/blob/master/settings.json.dist"

    CLI --> Settings
    CLI --> HTTPServer

    %% HTTP Server
    HTTPServer["HTTP Server\nindex.js"]:::server
    click HTTPServer "https://github.com/badlee/scriptbox/blob/master/index.js"
    Settings --> HTTPServer
    AdminBrowser -->|HTTP/REST| HTTPServer

    %% Router/Controller Layer
    subgraph "Router/Controller Layer"
        R1["Login Route\nroutes/0_login.js"]:::server
        click R1 "https://github.com/badlee/scriptbox/blob/master/routes/0_login.js"
        R2["Static Route\nroutes/1_static.js"]:::server
        click R2 "https://github.com/badlee/scriptbox/blob/master/routes/1_static.js"
        R3["Connectors API\nroutes/2_connectors.js"]:::server
        click R3 "https://github.com/badlee/scriptbox/blob/master/routes/2_connectors.js"
        R4["Admin Routes\nroutes/admin/"]:::server
        click R4 "https://github.com/badlee/scriptbox/tree/master/routes/admin/"
        R5["Health Check\nroutes/healthz.js"]:::server
        click R5 "https://github.com/badlee/scriptbox/blob/master/routes/healthz.js"
    end

    HTTPServer --> R1
    HTTPServer --> R2
    HTTPServer --> R3
    HTTPServer --> R4
    HTTPServer --> R5

    %% View & Static Layer
    subgraph "View & Static Layer"
        Templates["Server-side Templates\nviews/"]:::ui
        click Templates "https://github.com/badlee/scriptbox/tree/master/views/"
        PublicUI["Public UI Assets\npublic/"]:::ui
        click PublicUI "https://github.com/badlee/scriptbox/tree/master/public/"
        AdminUI["Admin UI Assets\npublic/admin/"]:::ui
        click AdminUI "https://github.com/badlee/scriptbox/tree/master/public/admin/"
    end

    R1 --> Templates
    R2 --> PublicUI
    R4 --> AdminUI

    %% Data Storage
    subgraph "Data Storage"
        DBFile["File-based DB\ndb/, dbProd/"]:::db
        click DBFile "https://github.com/badlee/scriptbox/tree/master/db/"
        DBMem["In-Memory Store\nmemory.js"]:::db
        click DBMem "https://github.com/badlee/scriptbox/blob/master/memory.js"
        Models["Model Schemas\nmodels/"]:::db
        click Models "https://github.com/badlee/scriptbox/blob/master/models/00_user.js"
        click Models "https://github.com/badlee/scriptbox/blob/master/models/1_sms.js"
    end

    R1 --> Models
    R3 --> Models
    R5 --> Models

    Models --> DBFile
    Models --> DBMem

    %% Script Engine
    ScriptEngine["VM Script Sandbox\nvm.js"]:::script
    click ScriptEngine "https://github.com/badlee/scriptbox/blob/master/vm.js"
    R3 --> ScriptEngine
    ExternalSMS --> ConnectorMgr

    %% Connector Manager
    ConnectorMgr["Connector Manager\nconnector.js"]:::server
    click ConnectorMgr "https://github.com/badlee/scriptbox/blob/master/connector.js"
    Settings --> ConnectorMgr
    ConnectorMgr --> ConnectorPlugins
    ConnectorMgr --> ScriptEngine

    %% Connector Plugins
    subgraph "Connector Plugins"
        Kannel["Kannel Connector\nscripts/connectors/kannel.js"]:::script
        click Kannel "https://github.com/badlee/scriptbox/blob/master/scripts/connectors/kannel.js"
        SMPP["SMPP Connector\nscripts/connectors/smpp.js"]:::script
        click SMPP "https://github.com/badlee/scriptbox/blob/master/scripts/connectors/smpp.js"
        Modem["Modem Connector\nscripts/connectors/modem.js"]:::script
        click Modem "https://github.com/badlee/scriptbox/blob/master/scripts/connectors/modem.js"
        Shorty["Shorty Connector\nscripts/connectors/shorty.js"]:::script
        click Shorty "https://github.com/badlee/scriptbox/blob/master/scripts/connectors/shorty.js"
    end

    ConnectorPlugins --> ExternalSMS
    ExternalSMS --> ConnectorMgr

    %% User Scripts
    subgraph "User Scripts"
        Keywords["Keyword Scripts\nscripts/keywords/"]:::script
        click Keywords "https://github.com/badlee/scriptbox/tree/master/scripts/keywords/"
        Modules["Custom Modules\nscripts/modules/"]:::script
        click Modules "https://github.com/badlee/scriptbox/tree/master/scripts/modules/"
        Services["Background Services\nscripts/services/"]:::script
        click Services "https://github.com/badlee/scriptbox/tree/master/scripts/services/"
    end

    ScriptEngine --> Keywords
    ScriptEngine --> Modules
    ScriptEngine --> Services
    ScriptEngine --> DBFile

    %% Data Flow for SMS
    ExternalSMS --> ConnectorMgr --> ScriptEngine --> DBFile
    DBFile --> ConnectorMgr --> ExternalSMS

    %% Class Definitions
    classDef server fill:#f0f8ff,stroke:#000;
    classDef ui fill:#ffe4e1,stroke:#000;
    classDef db fill:#e0ffe0,stroke:#000;
    classDef script fill:#fffacd,stroke:#000;
    classDef ext fill:#f5f5f5,stroke:#000;
```
