# haraka/haraka-plugin-bounce architecture

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

- Interactive diagram: https://gitdiagram.com/haraka/haraka-plugin-bounce
- Repository: https://github.com/haraka/haraka-plugin-bounce

## Overview

##### Project type and purpose
- This is a Node.js plugin (“haraka-plugin-bounce”) for the Haraka SMTP server.
- Its purpose is to hook into Haraka’s SMTP request pipeline and apply multiple configurable strategies to detect, validate, and process bounce messages.

##### File structure
- Top level:
- index.js – the plugin entry point
- config/ – contains bounce.ini and auxiliary JSON files (whitelist, bad_rcpt)
- test/ – unit and integration tests
- .github/workflows – CI, linting (Prettier), security (CodeQL), publish automation
- package.json – dependencies and plugin metadata
- No frontend; it lives entirely in the Haraka backend plugin architecture.
- Configuration and test artifacts are file-based; no external database.

##### README insights
- Describes features: hash-based validation, SPF checks, return-path rules, whitelist/bad-recipient lists.
- Specifies config parameters in config/bounce.ini and JSON whitelist.
- Integration point: append `"bounce"` to Haraka’s config/plugins file.

##### Main components
a. Haraka SMTP Server (core)
b. Plugin Engine (Haraka’s hook dispatcher)
c. bounce plugin module (index.js + sub-modules)
d. Configuration store (config/bounce.ini, bounce_whitelist.json, bounce_bad_rcpt)
e. Node.js crypto module (HMAC generation/validation)
f. DNS resolver (for SPF checks)
g. Downstream plugins or delivery subsystem
h. Client endpoints (SMTP clients sending mail; recipients)

##### Relationships and data flows
1. SMTP Client → Haraka SMTP listener
2. Haraka → sequential plugin hooks (e.g. `hook_data`, `hook_queue`)
3. bounce plugin loads config and JSON lists at startup
4. On bounce detection hook:
- Extract headers
- Call crypto to validate hash (if enabled)
- Query DNS for SPF validation (if enabled)
- Check return-path, recipient count, bad_rcpt list, whitelist
- Decide: accept & forward to downstream plugins/delivery or reject with SMTP error
5. Haraka → downstream plugins → final delivery or bounce back to sender
6. Plugin logs events, errors, metrics

##### Architectural patterns and principles
- Plugin architecture (inversion of control): Haraka calls plugin hooks
- Single responsibility: each check (hash, SPF, return-path) is a separate function
- Configuration-driven behavior: all rules toggled via INI/JSON
- No global state; config loaded once, then immutable during runtime
- Extensibility: adding new checks is adding new hook handlers or config sections

##### Relevant technologies
- Node.js runtime (v14+)
- Haraka SMTP server
- Node.js crypto (HMAC, hashing algorithms)
- DNS resolver library (for SPF record lookups)
- INI parser (for bounce.ini)
- JSON parser (for whitelists)
- Mocha or similar for test/index.js
- GitHub Actions for CI, Prettier for formatting, CodeQL for security scanning

##### Detailed capture of essential elements
- Config loading on plugin init.
- Decision diamond: “Bounce checks pass?” → Yes forwards, No rejects.
- File watchers or reloads if config changes at runtime (if applicable).
- Example config toggles beside each subcomponent.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Components (Blue)
    subgraph "Runtime Flow"
        direction TB
        SMTPClient["SMTP Client"]:::runtime
        HarakaCore["Haraka SMTP Server"]:::runtime
        subgraph "Bounce Plugin" 
            direction TB
            PluginInit["index.js\n(plugin entry)"]:::runtime
            subgraph "Submodules"
                direction TB
                HashMod["Hash Validation Module"]:::runtime
                SPFMod["SPF Validation Module"]:::runtime
                RuleEngine["Rule Engine\n(return-path, recipient count)"]:::runtime
                Loader["Whitelist/Bad-recipient Loader"]:::runtime
            end
            ConfigLoad["Load Config"]:::runtime
            Decision{"Bounce checks pass?"}:::runtime
        end
        Crypto["Node.js Crypto Module"]:::runtime
        DNS["DNS Resolver (SPF)"]:::runtime
        Downstream["Downstream Plugins/Delivery"]:::runtime
        SMTPClient -->|"SMTP DATA"| HarakaCore
        HarakaCore -->|"hook_data / hook_queue"| PluginInit
        PluginInit --> ConfigLoad
        ConfigLoad --> HashMod
        ConfigLoad --> SPFMod
        ConfigLoad --> RuleEngine
        ConfigLoad --> Loader
        HashMod --> Crypto
        SPFMod --> DNS
        HashMod --> Decision
        SPFMod --> Decision
        RuleEngine --> Decision
        Loader --> Decision
        Decision -->|Yes: accept & forward| Downstream
        Decision -->|No: reject SMTP error| HarakaCore
    end

    %% Configuration Store (Green)
    subgraph "Configuration Store"
        direction TB
        INI["bounce.ini"]:::config
        JSONWL["bounce_whitelist.json"]:::config
        JSONBR["bounce_bad_rcpt.json"]:::config
    end
    INI --> ConfigLoad
    JSONWL --> Loader
    JSONBR --> Loader

    %% CI/DevOps (Gray)
    subgraph "CI / DevOps Pipelines"
        direction TB
        CI[".github/workflows/ci.yml"]:::ci
        CodeQL[".github/workflows/codeql.yml"]:::ci
        Prettier[".github/workflows/prettier.yml"]:::ci
        Publish[".github/workflows/publish.yml"]:::ci
        TestSuite["test/index.js"]:::ci
    end

    %% Metadata & Docs
    subgraph "Project Metadata & Docs"
        direction TB
        PKG["package.json"]:::config
        ESLint["eslint.config.mjs"]:::config
        README["README.md"]:::config
        Changelog["CHANGELOG.md"]:::config
        Contributors["CONTRIBUTORS.md"]:::config
        License["LICENSE"]:::config
        ReleaseDir[".release"]:::config
    end

    %% Click Events
    click PluginInit "https://github.com/haraka/haraka-plugin-bounce/blob/master/index.js"
    click INI "https://github.com/haraka/haraka-plugin-bounce/blob/master/config/bounce.ini"
    click JSONWL "https://github.com/haraka/haraka-plugin-bounce/blob/master/config/bounce_whitelist.json"
    click JSONBR "https://github.com/haraka/haraka-plugin-bounce/blob/master/config/bounce_bad_rcpt.json"
    click TestSuite "https://github.com/haraka/haraka-plugin-bounce/blob/master/test/index.js"
    click CI "https://github.com/haraka/haraka-plugin-bounce/blob/master/.github/workflows/ci.yml"
    click CodeQL "https://github.com/haraka/haraka-plugin-bounce/blob/master/.github/workflows/codeql.yml"
    click Prettier "https://github.com/haraka/haraka-plugin-bounce/blob/master/.github/workflows/prettier.yml"
    click Publish "https://github.com/haraka/haraka-plugin-bounce/blob/master/.github/workflows/publish.yml"
    click PKG "https://github.com/haraka/haraka-plugin-bounce/blob/master/package.json"
    click ESLint "https://github.com/haraka/haraka-plugin-bounce/blob/master/eslint.config.mjs"
    click README "https://github.com/haraka/haraka-plugin-bounce/blob/master/README.md"
    click Changelog "https://github.com/haraka/haraka-plugin-bounce/blob/master/CHANGELOG.md"
    click Contributors "https://github.com/haraka/haraka-plugin-bounce/blob/master/CONTRIBUTORS.md"
    click License "https://github.com/haraka/haraka-plugin-bounce/tree/master/LICENSE"
    click ReleaseDir "https://github.com/haraka/haraka-plugin-bounce/blob/master/.release"

    %% Styles
    classDef runtime fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef config fill:#90EE90,stroke:#000,stroke-width:1px
    classDef ci fill:#D3D3D3,stroke:#000,stroke-width:1px
```
