# sallaapp/webhook-actions-js architecture

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

- Interactive diagram: https://gitdiagram.com/sallaapp/webhook-actions-js
- Repository: https://github.com/sallaapp/webhook-actions-js

## Overview

##### Project type and purpose
- This is an open-source Node.js library/module (“@salla.sa/webhooks-actions”) designed to simplify receiving and handling webhooks from the Salla e-commerce platform.
- It provides a dispatcher (SallaWebhook) that validates incoming HTTP POSTs, matches events against user-defined listeners or action files, and invokes the correct handler.

##### File structure
- Top-level:
– .github/, dependabot.yml → CI/CD and security scanning configs
– package.json, package-lock.json → module metadata and dependencies
– README.md → high-level overview and usage patterns
- src/Actions.js → core dispatcher implementation
- example/… → a sample Express.js app showing two integration patterns:
– “using listeners” (programmatic registration)
– “using folder structure” (auto-load JS files under example/Actions)
- test/ → unit tests for Actions.js
- dynamic/github-code-scanning → security code-scanning config (CodeQL)

##### Key insights from the README
- Two integration modes: listeners vs. folder-based loading of action files
- Environment variables (SALLA_WEBHOOK_SECRET, OAuth credentials) drive authorization and mode
- Central workflow: Salla invokes your HTTP endpoint → SallaWebhook.checkActions() → validate secret/auth header → dispatch to handler
- Predefined action names mapped to files under an Actions directory (e.g., order.created, customer.login)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External System"
        Salla["Salla e-commerce Platform"]:::external
    end

    subgraph "Consumer Application (Express.js)"
        App["Express.js HTTP Server"]:::consumer
        env["Environment Config (.env.example)"]:::config
        listeners["Listener Registration (programmatic)"]:::user
        actions["Folder-based Action Handlers"]:::user
    end

    subgraph "Core Library (@salla.sa/webhooks-actions)"
        webhook["SallaWebhook Module\n(src/Actions.js)"]:::core
    end

    subgraph "Project Metadata"
        pkg["package.json & package-lock.json"]:::metadata
        readme["README.md"]:::metadata
    end

    subgraph "CI/CD & Security Scanning"
        github["GitHub Actions & CODEOWNERS\n(.github/)"]:::ci
        dependabot["Dependabot\n(.github/dependabot.yml)"]:::ci
        codeql["CodeQL Scanning\n(dynamic/github-code-scanning/)"]:::ci
    end

    subgraph "Testing"
        tests["Unit Test Suite\n(test/SallaWebhooksHelper.test.js)"]:::test
    end

    Salla -->|"HTTP POST /webhook\n+ Authorization Header"| App
    env --> App
    App -->|"bodyParser + Authorization Check\n→ checkActions()"| webhook
    listeners -->|"on(event, handler)"| webhook
    actions -->|"auto-load based on event name"| webhook
    webhook -->|"invokes handler\nwith payload"| listeners
    webhook -->|"invokes action file\nwith payload"| actions
    pkg --> webhook
    readme --> App
    tests --> webhook
    github --> pkg
    dependabot --> pkg
    codeql --> pkg

    click webhook "https://github.com/sallaapp/webhook-actions-js/blob/master/src/Actions.js"
    click App "https://github.com/sallaapp/webhook-actions-js/blob/master/example/app.js"
    click actions "https://github.com/sallaapp/webhook-actions-js/tree/master/example/Actions/"
    click listeners "https://github.com/sallaapp/webhook-actions-js/blob/master/example/app.js"
    click env "https://github.com/sallaapp/webhook-actions-js/blob/master/example/.env.example"
    click github "https://github.com/sallaapp/webhook-actions-js/tree/master/.github/"
    click dependabot "https://github.com/sallaapp/webhook-actions-js/blob/master/.github/dependabot.yml"
    click codeql "https://github.com/sallaapp/webhook-actions-js/tree/master/dynamic/github-code-scanning/"
    click tests "https://github.com/sallaapp/webhook-actions-js/blob/master/test/SallaWebhooksHelper.test.js"
    click pkg "https://github.com/sallaapp/webhook-actions-js/blob/master/package.json"
    click readme "https://github.com/sallaapp/webhook-actions-js/blob/master/README.md"

    classDef external fill:#1f78b4,stroke:#0d3d66,color:#ffffff;
    classDef consumer fill:#a6cee3,stroke:#1f78b4,color:#000000;
    classDef core fill:#33a02c,stroke:#006400,color:#ffffff;
    classDef user fill:#ff7f00,stroke:#cc5500,color:#000000;
    classDef config fill:#b2df8a,stroke:#558b2f,color:#000000;
    classDef metadata fill:#6a3d9a,stroke:#3d0050,color:#ffffff;
    classDef ci fill:#bdbdbd,stroke:#595959,color:#000000;
    classDef test fill:#fb9a99,stroke:#a50f15,color:#000000;
```
