# martech-workshop/toolbelt architecture

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

- Interactive diagram: https://gitdiagram.com/martech-workshop/toolbelt
- Repository: https://github.com/martech-workshop/toolbelt

## Overview

##### Project type and purpose
- This is neither a monolithic application nor a running service, but an **open-source helper toolkit** for martech stack deployment.

##### File structure
- Top‐level folders:
- Base
- HAP
- Host
- Mautic
- WP
- archive (examples)
Each component folder contains:
– conf/ (raw config files)
– script/ (administration shortcuts)
– setup scripts (e.g. loadBase, loadHAP)
- There are no application source‐code directories; instead there are “load…” scripts that orchestrate copying files to target paths.
- README clarifies that each component is designed to be a building block in a Dockerfile or on a Debian 12 host.

##### Key insights from README
- **Modular design**: one folder per stack component
- **Separation of concerns**:
– conf = passive data (configs)
– script = active tooling for day-to-day ops
– setup scripts = unopinionated installers that just copy and set permissions
- **Use cases**:
– As library of files to `COPY` in Dockerfiles
– As bootstrap helper on bare or virtual hosts

##### Main components
a. **Source Repository** (GitHub/GitLab)
b. **Components** (modules in the repo):
- Base (Debian-slim base image)
- HAP (HAProxy)
- Host (bare-metal or VM host setup)
- Mautic (marketing automation stack)
- WP (WordPress)
- archive/ examples (Traefik, docker-compose samples)
c. **Developer / CI**
– Clones the repo
– Runs setup scripts or copies individual files via `wget`/`curl`
d. **Build Pipeline**
– Docker build contexts for each component
– `COPY` conf/ and script/ contents into container images
– Setup scripts executed at image‐build time
e. **Runtime Environments**
– Container images (Base → HAP/Mautic/WP layered images)
– Debian 12 host (for Host component or non-containerized setup)
f. **External Dependencies**
– Certificate authority (for certRenew scripts)
– Database server (MariaDB for Mautic)
– Apache/PHP-FPM for Mautic
– Docker or LXD daemons

##### Relationships and interactions
- Developer/CI pulls **Source Repo** → invokes **setup scripts** or selects individual **conf** & **script** files → passes them into **Docker build** or host provisioning process → produces **Container Images** or configures **Debian Host** → deployed into runtime targets (swarm, VMs).
- Container images have a clear **layered dependency**:
Base image  → HAP image → optional Mautic or WP image
- Host provisioning stands somewhat outside the container world but also leverages the same helper scripts.

##### Architectural patterns and design principles
- **Layered architecture**: Docker images built in stages, each stage corresponding to a component folder.
- **Separation of concerns**: installers (setup scripts) don’t embed business logic. Configuration is data-only.
- **Convention over configuration**: strict folder naming (`conf/`, `script/`, top-level setup scripts) makes automated tooling easy.

##### Diagramming recommendations
- Use **rectangles** for each major component (Source Repo, Base, HAP, Host, Mautic, WP, Archive).
- From Developer / CI → Source Repo (clone)
- From Source Repo → Build Pipeline (setup scripts invoked)
- From Build Pipeline → Container Images → Runtime Environment
- From Container Images → External Dependencies
- Blue for repo and build stages
- Green for container images / runtime artifacts
- Orange for external services

##### Essential elements to capture
- Clear **component boundaries**
- **Data flow** (config & scripts → images → runtime)
- **Dependencies** between modules (Base → HAP → Mautic)
- **External service interactions** (e.g., Mautic ↔ MariaDB, HAP ↔ certificates)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer/CI
    Dev["Developer / CI"]:::dev

    %% Source Repository
    subgraph "Source Repository" 
        direction TB
        Base["Base"]:::repo
        HAP["HAP"]:::repo
        Host["Host"]:::repo
        Mautic["Mautic"]:::repo
        WP["WP"]:::repo
        Archive["archive"]:::repo
    end

    %% Build Pipeline
    subgraph "Build Pipeline" 
        direction TB
        Build["Build Pipeline"]:::build
        HostProv["Host Provisioning"]:::build
    end

    %% Container Images
    subgraph "Container Images" 
        direction TB
        BaseImg["Base Image"]:::runtime
        HAPImg["HAP Image"]:::runtime
        MauticImg["Mautic Image"]:::runtime
        WPImg["WP Image"]:::runtime
    end

    %% Runtime Environments
    subgraph "Runtime Environments"
        direction TB
        DockerRuntime["Docker / LXD Daemon"]:::external
        DebHost["Debian 12 Host"]:::runtime
    end

    %% External Dependencies
    subgraph "External Services"
        direction TB
        CA["Certificate Authority"]:::external
        MariaDB["MariaDB"]:::external
        ApachePHP["Apache / PHP-FPM"]:::external
    end

    %% Relationships
    Dev -->|"git clone"| Base
    Dev -->|"git clone"| HAP
    Dev -->|"git clone"| Host
    Dev -->|"git clone"| Mautic
    Dev -->|"git clone"| WP
    Dev -->|"git clone"| Archive

    Base -->|"invoke setup scripts / COPY conf & scripts"| Build
    HAP -->|"invoke setup scripts / COPY conf & scripts"| Build
    Mautic -->|"invoke setup scripts / COPY conf & scripts"| Build
    WP -->|"invoke setup scripts / COPY conf & scripts"| Build
    Host -->|"invoke setup scripts / COPY conf & scripts"| HostProv

    Build -->|"docker build context"| BaseImg
    Build -->|"docker build context"| HAPImg
    Build -->|"docker build context"| MauticImg
    Build -->|"docker build context"| WPImg

    BaseImg -->|"FROM base"| HAPImg
    HAPImg -->|"FROM hap image"| MauticImg
    BaseImg -->|"FROM base"| WPImg

    BaseImg -->|"deployed to"| DockerRuntime
    HAPImg -->|"deployed to"| DockerRuntime
    MauticImg -->|"deployed to"| DockerRuntime
    WPImg -->|"deployed to"| DockerRuntime

    HostProv -->|"bootstrap scripts"| DebHost

    MauticImg -->|"connects to"| MariaDB
    MauticImg -->|"served by"| ApachePHP
    HAPImg -->|"requests certs from"| CA

    %% Click events for component mappings
    click Base "https://github.com/martech-workshop/toolbelt/tree/Prod/Base/"
    click Base_conf "https://github.com/martech-workshop/toolbelt/tree/Prod/Base/conf/"
    click Base_script "https://github.com/martech-workshop/toolbelt/tree/Prod/Base/script/"
    click Base_load "https://github.com/martech-workshop/toolbelt/tree/Prod/Base/loadBase"

    click HAP "https://github.com/martech-workshop/toolbelt/tree/Prod/HAP/"
    click HAP_conf "https://github.com/martech-workshop/toolbelt/tree/Prod/HAP/conf/"
    click HAP_script "https://github.com/martech-workshop/toolbelt/tree/Prod/HAP/script/"
    click HAP_load "https://github.com/martech-workshop/toolbelt/tree/Prod/HAP/loadHAP"

    click Host "https://github.com/martech-workshop/toolbelt/tree/Prod/Host/"
    click Host_conf "https://github.com/martech-workshop/toolbelt/tree/Prod/Host/conf/"
    click Host_script "https://github.com/martech-workshop/toolbelt/tree/Prod/Host/script/"
    click Host_load1 "https://github.com/martech-workshop/toolbelt/tree/Prod/Host/loadHost"
    click Host_load2 "https://github.com/martech-workshop/toolbelt/tree/Prod/Host/loadHost-AWS-LXD"

    click Mautic "https://github.com/martech-workshop/toolbelt/tree/Prod/Mautic/"
    click Mautic_conf "https://github.com/martech-workshop/toolbelt/tree/Prod/Mautic/conf/"
    click Mautic_script "https://github.com/martech-workshop/toolbelt/tree/Prod/Mautic/script/"
    click Mautic_load1 "https://github.com/martech-workshop/toolbelt/tree/Prod/Mautic/loadMautic"
    click Mautic_load2 "https://github.com/martech-workshop/toolbelt/tree/Prod/Mautic/loadDB"
    click Mautic_load3 "https://github.com/martech-workshop/toolbelt/tree/Prod/Mautic/loadAll"

    click WP "https://github.com/martech-workshop/toolbelt/tree/Prod/WP/"
    click WP_load "https://github.com/martech-workshop/toolbelt/tree/Prod/WP/loadWP"

    click Archive "https://github.com/martech-workshop/toolbelt/tree/Prod/archive/"
    click Archive_trafyml "https://github.com/martech-workshop/toolbelt/blob/Prod/archive/Traefik/traefik.yml"
    click Archive_dc "https://github.com/martech-workshop/toolbelt/blob/Prod/archive/Traefik/docker-compose.yml"

    %% Styles
    classDef repo fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef build fill:#b8daff,stroke:#000,stroke-width:1px
    classDef runtime fill:#d4edda,stroke:#000,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#000,stroke-width:1px
    classDef dev fill:#e2e3e5,stroke:#000,stroke-width:1px
```
