# mindbaz/zonemta-block-zone architecture

> Architecture diagram of the GitHub repository mindbaz/zonemta-block-zone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mindbaz/zonemta-block-zone
- Repository: https://github.com/mindbaz/zonemta-block-zone

## Overview

##### Project type and purpose
- This is a Node.js plugin module for ZoneMTA (an SMTP server framework) that blocks mail delivery to specific “zones” or domains.
- It is not a standalone full-stack app but an extension module that ZoneMTA loads at runtime.

##### File structure
- Root files:
- package.json / index.js — the entry point and module metadata
- config.example.toml / config.toml — plugin-specific configuration
- Makefile / LICENSE / README.md — build, license, and documentation
- tests/ directory: unit tests for each core function (get_receiver_domain, is_receiver_domain_blocked, raise_error, init)

##### README for insights
- Usage: installed as a dependency, enabled in ZoneMTA’s “plugins” section with type “receiver”
- Configuration: array of zone names to block
- Workflow: ZoneMTA calls the plugin’s hook on each incoming recipient, the plugin inspects the domain, and throws an error if it’s in the blocked list.

##### Components
a. Main components
- ZoneMTA Core (SMTP engine, plugin loader)
- zonemta-block-msp Plugin
– init() hook registration
– get_receiver_domain()
– is_receiver_domain_blocked()
– raise_error()
- Plugin Configuration (TOML file)
- Tests harness (Mocha/Jest or similar test runner) – optional, for completeness
b. Relationships & interactions
- SMTP flow → ZoneMTA Core
- Core invokes Plugin.init() at startup
- For each recipient:
– Core → Plugin.get_receiver_domain(input envelope)
– Domain returned → Plugin.is_receiver_domain_blocked(config.zone_block)
– If blocked → Plugin.raise_error() → ZoneMTA rejects delivery
- Config.toml is read by the plugin at init time
c. Architectural patterns / design principles
- Hook-based plugin architecture (observer pattern)
- Single-responsibility functions (each exported function does one thing)
- Configuration-driven behavior
d. Key technologies & libraries
- Node.js module system (CommonJS exports in index.js)
- zone-mta plugin API (receiver hook)
- toml parser (reads config.toml)
- test framework (e.g., Mocha) for unit tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    Envelope["Incoming SMTP Envelope"]:::external
    Core["ZoneMTA Core"]:::core
    ConfigActive["config.toml"]:::config
    ConfigExample["config.example.toml"]:::config
    PackageMetadata["package.json"]:::doc
    Documentation["README.md"]:::doc
    BuildTasks["Makefile"]:::doc
    LicenseFile["LICENSE"]:::doc

    %% Plugin subgraph
    subgraph "Plugin: zonemta-block-msp"
        direction TB
        PluginInit["init()"]:::plugin
        ExtractDomain["get_receiver_domain()"]:::plugin
        BlockCheck["is_receiver_domain_blocked()"]:::plugin
        RaiseError["raise_error()"]:::plugin
    end

    %% Tests subgraph
    subgraph "Tests"    
        direction TB
        TestsHarness["tests/"]:::tests
        TestInit["init-test.js"]:::tests
        TestGetDomain["get_receiver_domain-test.js"]:::tests
        TestBlockCheck["is_receiver_domain_blocked-test.js"]:::tests
        TestRaiseError["raise_error-test.js"]:::tests
    end

    %% Startup flow
    ConfigActive -->|reads at init| PluginInit
    Envelope --> Core
    Core -->|on startup| PluginInit

    %% Runtime flow
    Envelope -->|per recipient| Core
    Core -->|calls hook| ExtractDomain
    ExtractDomain -->|domain| BlockCheck
    BlockCheck -->|blocked?| RaiseError
    RaiseError -->|throws error| Core

    %% Tests relationships
    TestsHarness --> TestInit
    TestsHarness --> TestGetDomain
    TestsHarness --> TestBlockCheck
    TestsHarness --> TestRaiseError

    %% Documentation & metadata connections
    PackageMetadata --- Documentation
    PackageMetadata --- BuildTasks
    PackageMetadata --- LicenseFile

    %% Click Events
    click PluginInit "https://github.com/mindbaz/zonemta-block-zone/blob/main/index.js"
    click ExtractDomain "https://github.com/mindbaz/zonemta-block-zone/blob/main/index.js"
    click BlockCheck "https://github.com/mindbaz/zonemta-block-zone/blob/main/index.js"
    click RaiseError "https://github.com/mindbaz/zonemta-block-zone/blob/main/index.js"
    click PackageMetadata "https://github.com/mindbaz/zonemta-block-zone/blob/main/package.json"
    click Documentation "https://github.com/mindbaz/zonemta-block-zone/blob/main/README.md"
    click BuildTasks "https://github.com/mindbaz/zonemta-block-zone/tree/main/Makefile"
    click LicenseFile "https://github.com/mindbaz/zonemta-block-zone/tree/main/LICENSE"
    click ConfigActive "https://github.com/mindbaz/zonemta-block-zone/blob/main/config.toml"
    click ConfigExample "https://github.com/mindbaz/zonemta-block-zone/blob/main/config.example.toml"
    click TestsHarness "https://github.com/mindbaz/zonemta-block-zone/tree/main/tests/"
    click TestInit "https://github.com/mindbaz/zonemta-block-zone/blob/main/tests/init-test.js"
    click TestGetDomain "https://github.com/mindbaz/zonemta-block-zone/blob/main/tests/get_receiver_domain-test.js"
    click TestBlockCheck "https://github.com/mindbaz/zonemta-block-zone/blob/main/tests/is_receiver_domain_blocked-test.js"
    click TestRaiseError "https://github.com/mindbaz/zonemta-block-zone/blob/main/tests/raise_error-test.js"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef plugin fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef config fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef doc fill:#f8d7da,stroke:#333,stroke-width:1px;
    classDef tests fill:#e2e3e5,stroke:#333,stroke-width:1px;
    classDef external fill:#ffffff,stroke:#333,stroke-width:1px;
```
