# pkolano/ballast architecture

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

- Interactive diagram: https://gitdiagram.com/pkolano/ballast
- Repository: https://github.com/pkolano/ballast

## Overview

##### Project Type and Purpose
- Ballast is a specialized framework designed to balance SSH load by dynamically redirecting SSH connections within a bastion architecture.
- The README explains that the system is composed of three main parts: a Ballast agent (running on each “balanced” host), a Ballast server (aggregating load information and making balancing decisions), and a Ballast client (invoked by SSH on bastions and internal hosts to resolve host aliases).
- The project includes components in both C (in the c/ directory) and Perl (in the perl/ directory), in addition to Debian packaging files and documentation.

##### File Structure
- Top-level directories:
– c/: Contains C source files (e.g., ballast.c) component which might implement low‐level or performance-critical parts.
– perl/: Contains scripts for ballast, ballast-agent, and ballastd, indicating that parts of the system (likely the agent, server, or client wrappers) are implemented in Perl.
– debian/: Packaging files for preparing Ballast for Debian distributions.
– doc/: Contains manual pages and documentation that detail usage and configuration.
– etc/: Provides default configuration files (e.g., ballastrc) and systemd service units, which give insight into how the system is deployed and controlled.
- The presence of systemd service definitions in etc/systemd indicates that Ballast components (the agent, server, and/or possibly a timer for the agent) are managed as services.

a. Primary Components:
– Ballast Agent: Deployed on every balanced (internal) host. It periodically gathers load information and sends it to the Ballast server. (Referenced in perl/ballast-agent and the systemd unit file ballast-agent.service.)
– Ballast Server: Aggregates load data from all agents and decides which host should be used when a balancing decision is invoked. (Appears related to ballastd as per perl/ballastd and the man page doc/ballastd.1.)
– Ballast Client: Runs on bastion and internal hosts to intercept SSH connections. It contacts the Ballast server to resolve host aliases into actual hostnames. (See perl/ballast and the documentation in doc/ballast.1.)
– TCP Relay/External Utilities: The server returns the chosen host, and then a built-in TCP relay (or something like netcat) facilitates the connection.

b. Relationships & Data Flow:
– Load Monitoring Flow: Each Ballast Agent (on balanced hosts) collects system load metrics → Sends data to the Ballast Server.
– Connection/Load Balancing Flow: A user initiates an SSH connection using a balancing alias → The Ballast Client is triggered → It contacts the Ballast Server → The server uses the aggregated load data (and user-specific policies) to select one (or more) host(s) → The client initiates a connection via a TCP relay to the chosen host.

c. Architectural Patterns and Design Principles:
– Distributed Load Monitoring: A decentralized approach where each host provides its own performance data.
– Centralized Decision Making: A resilient, central Ballast Server aggregates metrics and makes dynamic routing decisions.
– Client-Side Integration: Transparent integration with SSH, leveraging existing client aliasing/proxying capabilities without modifying external access patterns.

d. Technologies, Frameworks, and Libraries:
– C and Perl are used for performance-critical components and higher-level glue scripts.
– systemd service unit files indicate that process supervision and scheduling are managed via systemd.
– TCP relay mechanisms and possibly utilities like netcat are used to establish final SSH connections.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ballast Components Subgraph
    subgraph "Ballast Components"
        A["Ballast Agent (Perl)"]:::agent
        S["Ballast Server (Perl/C)"]:::server
        C["Ballast Client (Perl)"]:::client
        P["Performance Component (C)"]:::performance
    end

    %% External Components Subgraph
    subgraph "External Components"
        T["TCP Relay/Netcat"]:::external
        BH["Balanced Host"]:::external
    end

    %% Deployment & Configuration Subgraph
    subgraph "Deployment & Configuration"
        Config["Configuration (ballastrc)"]:::config
        Debian["Debian Packaging"]:::config
        SysdA1["Systemd: ballast-agent.service"]:::config
        SysdA2["Systemd: ballast-agent.timer"]:::config
        SysdS["Systemd: ballast.service"]:::config
        DocA["Documentation: ballast-agent.1"]:::config
        DocS["Documentation: ballastd.1"]:::config
        DocC["Documentation: ballast.1"]:::config
    end

    %% Data Flows
    A -->|"LoadData"| S
    C -->|"AliasRequest"| S
    S -->|"HostSelection"| C
    C -->|"TCPRelay"| T
    T -->|"Connect"| BH

    %% Associations with Deployment & Configuration
    A --- DocA
    A --- SysdA1
    A --- SysdA2
    S --- DocS
    S --- SysdS
    C --- DocC
    Config --- A
    Config --- S
    Config --- C
    P --- S
    Debian --- Config

    %% Click Events for Ballast Agent
    click A "https://github.com/pkolano/ballast/tree/master/perl/ballast-agent"
    click DocA "https://github.com/pkolano/ballast/blob/master/doc/ballast-agent.1"
    click SysdA1 "https://github.com/pkolano/ballast/blob/master/etc/systemd/system/ballast-agent.service"
    click SysdA2 "https://github.com/pkolano/ballast/blob/master/etc/systemd/system/ballast-agent.timer"

    %% Click Events for Ballast Server
    click S "https://github.com/pkolano/ballast/tree/master/perl/ballastd"
    click DocS "https://github.com/pkolano/ballast/blob/master/doc/ballastd.1"
    click SysdS "https://github.com/pkolano/ballast/blob/master/etc/systemd/system/ballast.service"

    %% Click Events for Ballast Client
    click C "https://github.com/pkolano/ballast/tree/master/perl/ballast"
    click DocC "https://github.com/pkolano/ballast/blob/master/doc/ballast.1"

    %% Click Events for Configuration & Packaging
    click Config "https://github.com/pkolano/ballast/tree/master/etc/ballastrc"
    click Debian "https://github.com/pkolano/ballast/tree/master/debian/"

    %% Click Event for Performance Component
    click P "https://github.com/pkolano/ballast/blob/master/c/ballast.c"

    %% Styles
    classDef agent fill:#ffdddd,stroke:#cc0000,stroke-width:2px;
    classDef server fill:#ddffdd,stroke:#009900,stroke-width:2px;
    classDef client fill:#ddddff,stroke:#0000cc,stroke-width:2px;
    classDef performance fill:#ffeedd,stroke:#cc6600,stroke-width:2px;
    classDef external fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef config fill:#ddffff,stroke:#009999,stroke-width:2px;
```
