# pkolano/save architecture

> Architecture diagram of the GitHub repository pkolano/save, 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/save
- Repository: https://github.com/pkolano/save

## Overview

##### Project Type and Purpose
- Save is a command-line tool and framework used for IP failover and network high availability.
- Its core purpose is to monitor and manage the active and passive nodes in a networked service, facilitating automated takeover of IP addresses and maintaining configuration consistency.
- The tool integrates heartbeat monitoring (via SSH), IP management communications (ARP/neighbor advertisement), as well as mechanisms for validating and backing up configurations.

##### Analyzing the File Structure
- The top-level files (CHANGES, COPYING, INSTALL, README.md) and documentation folder (doc) indicate standard open-source documentation and licensing.
- The primary executable (or script) “save” and its configuration file “saverc” mark the core of the application.
- The absence of directories for “frontend” or “backend” signals that the focus is on backend and system-level operations rather than a full-stack web application.

##### Key Components
a. Command-Line Interface (CLI) / Controller
- Represents the “save” command entered by administrators.
- Acts as the entry point where the administrator’s actions trigger subsequent processes.

b. Configuration/Policy Module
- Handled primarily via the “saverc” file.
- Governs what actions (validation, archival, synchronization) should be applied when a “save” command is executed.

c. Heartbeat and Monitoring Module
- Implements the SSH-based heartbeat mechanism.
- Ensures that passive nodes can detect the status of the active node.

d. IP Failover Controller
- Manages the IP address hand-off using techniques such as gratuitous ARP (IPv4) and/or unsolicited neighbor advertisement (IPv6).
- Coordinates with the heartbeat module to decide when to trigger failover.

e. Validation, Archival, and Synchronization Engine
- Validates configuration files before they are applied.
- Archives previous configurations if a new configuration causes issues.
- Synchronizes files or commands across nodes based on defined policies.

f. External Dependencies & Network Interfaces
- SSH (for heartbeats and command execution on remote nodes).
- The local network’s ARP/neighbor advertisement systems to manage IP address communication.
- **Note:** Although not represented as “components” within the file tree, these interfaces are critical parts of Save’s operation.

##### Relationships and Interactions to Illustrate
- The CLI (save command) is the starting point. When an administrator appends “save” to a command (such as editing a configuration file), the system reads the “saverc” configuration to determine which of the following modules are engaged.
- The configuration module feeds instructions to:
- The Validation/Archival/Synchronization Engine to process any configuration changes.
- The Heartbeat and Monitoring Module, which continuously monitors the node’s availability.
- The Heartbeat module maintains communication with passive nodes using SSH, enabling them to decide when failover should be triggered.
- The IP Failover Controller then issues the commands (using appropriate network protocols like gratuitous ARP or unsolicited neighbor advertisement) to shift the IP address between nodes as determined by the current state.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Different modules handle distinct responsibilities (CLI input handling, configuration management, monitoring, network interaction).
- Modular and Extensible Design: Each component (validation, archival, synchronization, failover) can be updated or extended independently.
- Fault Tolerance and High Availability: The design supports detecting and reacting to node failures via automated heartbeats and IP failover.

- Clearly labeled components: CLI, Configuration Module, Heartbeat/Monitoring Engine, IP Failover Controller, Validation/Archival/Synchronization Engine, and External Interfaces (SSH, ARP/Neighbor advertisement).
- Annotations for key design principles and the connection between modules (e.g., “failure detection triggers IP handoff”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Components
    CLI["CLI (save command)"]:::cli
    Config["Configuration Module (saverc)"]:::config
    Validate["Validation/Archival/Synchronization Engine"]:::engine
    Heartbeat["Heartbeat & Monitoring Module"]:::engine
    Failover["IP Failover Controller"]:::engine
    External["External Interfaces: SSH, ARP/Neighbor Advertisement"]:::external
    Docs["Documentation & Licensing"]:::docs

    %% Relationships
    CLI -->|"reads_config"| Config
    Config -->|"triggers_validation"| Validate
    Config -->|"initiates_monitoring"| Heartbeat
    Heartbeat -->|"failure_detected"| Failover
    Heartbeat --->|"uses_interface"| External
    Failover --->|"executes_IP_switch"| External

    %% Supporting Documentation (no interactions, just informational)
    CLI ---|"supported_by"| Docs

    %% Click Events
    click CLI "https://github.com/pkolano/save/tree/master/save"
    click Config "https://github.com/pkolano/save/tree/master/saverc"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef config fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef engine fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef docs fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
