# brndnsvr/remote-diff-tool architecture

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

- Interactive diagram: https://gitdiagram.com/brndnsvr/remote-diff-tool
- Repository: https://github.com/brndnsvr/remote-diff-tool

## Overview

##### Project Purpose & Type
- The tool is a command-line utility, written in Go, for collecting files from remote servers via SSH and then comparing (analyzing) them to highlight configuration inconsistencies.
- It fits into systems management and DevOps use cases with secure remote communication, file collection, and diff analysis.

##### File Structure
- Top-level files like main.go signal the entry point for the CLI. The internal directory is split into modules:
- internal/collect: Contains the logic to connect via SSH, execute remote file collection, packaging into a tarball, extraction, and checksum generation.
- internal/analyze: Implements the file diffing/analyzing functionality, including checksum comparisons and generating unified diffs.
- internal/config: Manages configuration settings (possibly reading command-line flags and configuration files).
- internal/sshutil: Contains code to abstract SSH connections and remote command execution.
- internal/util: Contains supporting helper functions.
- Other files (go.mod, go.sum, LICENSE, README) indicate dependency management and licensing.

##### Key Components
- Command-Line Interface (CLI)/Main entry (main.go)
- Accepts global options and command-specific options (collect, analyze, or run both commands).
- Configuration Module:
- Reads flags and/or a config file (config.json) from the output directory.
- Handles environment variables for SSH authentication.
- SSH/Remote Connectivity Module:
- Uses the SSH client (via golang.org/x/crypto/ssh) and possibly SFTP (via pkg/sftp) for secure file transfers.
- Collection Module:
- Initiates connections to remote servers.
- Uploads and executes a temporary script for file collection.
- Downloads and extracts collected files.
- Updates the manifest (with checksums and file metadata).
- Analysis Module:
- Loads the manifest.
- Performs checksum comparisons and, where differences exist, runs detailed content diffing.
- (Optionally) Generates and saves unified diff files.
- Output/Logging Module:
- Writes logs (using logrus) into a specific logs directory.
- Structures output directories for the config, collected files (maintaining the server directory hierarchy), and diff output.
- Concurrency Control:
- Use of packages supporting concurrency like golang.org/x/sync/semaphore for handling multiple server operations concurrently.

##### Relationships & Data Flow
- The CLI/Entry Point triggers the configuration module, which then passes parameters to the collection module.
- For the Collection phase, the tool initiates SSH connections to each listed remote server. Data flows from remote servers back to the local machine where the files are stored and a manifest is updated.
- After collection, the Analysis module uses the manifest to compare file checksums and content; if differences are detected, diff files are generated.
- Throughout these processes, the logging component records significant events and potential errors.
- There is a clear separation between remote collection (gathering data) and local analysis (diffing), yet they are orchestrated by the main CLI tool.

##### Architectural Patterns & Technologies
- Modularity: Each functionality (collection, analysis, configuration, SSH operations) is encapsulated in its own module.
- Concurrency: Parallel processing is used for accessing multiple servers, enhancing efficiency.
- Secure Communication: Emphasis on secure SSH protocols for transferring files.
- External Libraries: Use of packages like cobra (CLI), logrus (logging), errors (error handling), and specific SSH libraries.
- Output Structure and Manifest: Storage of collected files in a clear organized output directory which includes a manifest for further comparisons, and a diff output directory when required.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Config Layer
    subgraph "CLI & Config Layer"
        A["CLI Entry (main.go)"]:::cli
        B["Configuration Module"]:::config
    end

    %% Processing Layer
    subgraph "Processing Layer"
        D["Collection Module"]:::collection
        C["SSH/Remote Connectivity Module"]:::ssh
        E["Analysis Module"]:::analysis
        G["Utility/Helper Functions"]:::utility
    end

    %% Output & Logging Layer
    subgraph "Output & Logging"
        F["Logging & Output Storage"]:::logging
    end

    %% Remote Server (External Entity)
    RS(("Remote Server")):::remote

    %% Relationships
    A -->|"parsesOptions"| B
    B -->|"passesConfig"| D
    D -->|"initiatesSSH"| C
    C -->|"connectsTo"| RS
    RS -->|"sendsFilesTo"| D
    D -->|"updatesManifest"| E
    D -->|"logsEvents"| F
    E -->|"generatesDiffs"| F
    D -->|"usesHelpers"| G
    E -->|"usesHelpers"| G

    %% Click Events
    click A "https://github.com/brndnsvr/remote-diff-tool/blob/master/main.go"
    click B "https://github.com/brndnsvr/remote-diff-tool/blob/master/internal/config/config.go"
    click C "https://github.com/brndnsvr/remote-diff-tool/blob/master/internal/sshutil/sshutil.go"
    click D "https://github.com/brndnsvr/remote-diff-tool/blob/master/internal/collect/collect.go"
    click E "https://github.com/brndnsvr/remote-diff-tool/blob/master/internal/analyze/analyze.go"
    click G "https://github.com/brndnsvr/remote-diff-tool/blob/master/internal/util/util.go"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef config fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef ssh fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef remote fill:#F5CBA7,stroke:#AF601A,stroke-width:2px;
    classDef collection fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef analysis fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef logging fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef utility fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
```
