# jarektoro/tunnyd architecture

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

- Interactive diagram: https://gitdiagram.com/jarektoro/tunnyd
- Repository: https://github.com/jarektoro/tunnyd

## Overview

##### Project Type and Purpose
- The README clearly states that Tunnyd is tailored for secure Docker container tunneling through SSH, eliminating the need for opening SSH ports or setting up bastion hosts.
- This is a CLI tool meant to interface with Docker containers directly by utilizing container labels and custom naming patterns.
- The project is written in Rust and leverages SSH for secure intermediary communications.

##### Key Components from the File Structure
- Top-level files, such as Cargo.toml and Cargo.lock, indicate that this is a Rust project.
- The src directory includes several modules:
- main.rs: Likely contains the application entry point.
- cli.rs: Presumably handles command-line argument processing and user input (e.g., parsing SSH target names).
- docker.rs: Contains the logic for interfacing with Docker (executing commands, managing container tunnels).
- server.rs: Implements the server-side functionality, likely operating as the custom SSH service running on port 2222.
- GitHub workflows and configuration files (.github, .deepsource.toml) indicate that continuous integration and code quality checks are part of the project but are not central to the architectural design of the tunneling system.

##### Architectural Insights from the README
- The README describes Tunnyd operating as a “surrogate SSH daemon” that:
– Accepts an SSH connection initiated by the user.
– Redirects this connection to a custom SSH service (listening on port 2222).
– Captures SSH session details (e.g., username, target container name based on a custom naming pattern).
– Executes Docker commands (via docker exec) to effectively “tunnel” the SSH session into the targeted container.
- The readme content also outlines how the SSH configuration is set up and how Docker container labels are used, which shows a clear coupling between container metadata and SSH target resolution.

##### How to Represent This
a. Main Components to Include:
- SSH Client: Represents the end user initiating the secure connection using an SSH command (with embedded remote command options).
- Tunnyd SSH Service (Server Module): Acts as the intermediary that listens on port 2222, intercepting the SSH session.
- CLI Module: Handles the command-line interface logic and parsing of SSH configurations (triggering proper routing within the application).
- Docker Module: Interfaces with the Docker engine by executing Docker commands (especially “docker exec”) to connect the SSH session to the appropriate container.
- Docker Engine/Container(s): Represents the Docker host where containers are running; these containers are identified/selected based on the labels defined in the Docker Compose configuration.

b. Relationships and Interactions:
- The SSH Client connects to the Tunnyd SSH Service (via the configuration in ~/.ssh/config).
- The SSH Service (server.rs) receives the connection, extracts connection details (from CLI and container matching logic).
- Communication flows from the SSH Service to the Docker Module, which then invokes Docker commands to “exec” into the container matching the custom name pattern.
- The standard input/output (the SSH session streams) is piped back and forth between the SSH Service and the container process.

c. Architectural Patterns and Principles:
- The design is modularized into distinct responsibilities (parsing, connection handling, and Docker interfacing) that can be represented as separate components.
- The system leverages a proxy pattern: the Tunnyd SSH Service acts as a proxy between the client and the Docker container.
- Dependency inversion is implied as the tool decouples the SSH access mechanism from direct container configuration by using labels.

d. Technologies and Frameworks:
- Rust is the primary language, with likely use of asynchronous operations (if needed) for handling I/O streams.
- Docker is critical for container management, and the tool interacts with it likely via command execution or a Docker API.
- SSH is used as the secure transport protocol.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    SSH_Client["SSH Client"]:::external
    Docker_Host["Docker Engine/Containers"]:::external
    CI_CD["CI/CD & Code Quality"]:::external

    %% Initialization subgraph
    subgraph "Initialization Layer"
        MainEntry["Tunnyd Main Entry"]:::internal
        CLI_Module["Tunnyd CLI Module"]:::internal
    end

    %% Core Proxy and Docker subgraph
    subgraph "SSH Proxy & Docker Interaction"
        SSH_Service["Tunnyd SSH Service Module"]:::internal
        Docker_Module["Docker Module"]:::internal
    end

    %% Connections
    SSH_Client -->|"SSH_connection"| SSH_Service
    MainEntry -->|"initialize"| CLI_Module
    CLI_Module -->|"configure_service"| SSH_Service
    SSH_Service -->|"execute_docker_exec"| Docker_Module
    Docker_Module -->|"pipe_IO"| Docker_Host
    Docker_Host -->|"return_output"| Docker_Module

    %% CI/CD as a separate concern (not part of main flow)
    CI_CD --- MainEntry

    %% Click events for internal components (component mapping)
    click MainEntry "https://github.com/jarektoro/tunnyd/blob/main/src/main.rs"
    click CLI_Module "https://github.com/jarektoro/tunnyd/blob/main/src/cli.rs"
    click SSH_Service "https://github.com/jarektoro/tunnyd/blob/main/src/server.rs"
    click Docker_Module "https://github.com/jarektoro/tunnyd/blob/main/src/docker.rs"
    click CI_CD "https://github.com/jarektoro/tunnyd/tree/main/.github/"

    %% Styles
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#f9c,stroke:#333,stroke-width:2px;
```
