# trzsz/trzsz-go architecture

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

- Interactive diagram: https://gitdiagram.com/trzsz/trzsz-go
- Repository: https://github.com/trzsz/trzsz-go

## Overview

##### Project Type and Purpose
- trzsz-go is a command-line file-transfer tool and library written in Go. It implements the trz/tsz protocol (similar to rz/sz) for uploading/downloading files over local shells or SSH sessions, with additional features like drag-and-drop, clipboard integration, and tmux relay.
- It is not a web or service-based system; it is an open-source CLI utility plus a reusable Go library for embedding trz/tsz support in custom SSH clients.

##### File-Structure Analysis
- Top-level “cmd” directory: three executables (trz, tsz, trzsz) with their own main.go entrypoints.
- “trzsz” directory: core library modules, each file implementing one aspect of the protocol or I/O (comm.go, buffer.go, pipeline.go, zmodem.go, transfer.go, filter.go, progress.go, escape.go, relay.go, archive.go, utils_*.go, pty_*.go, version.go).
- Packaging & CI: “.github/workflows”, `goreleaser.yaml`, `Makefile`, “debian/…”, “inno_setup/…”.
- Examples: “examples/ssh_client.go” shows how to embed the library in a custom SSH client.

##### README Insights
- Describes usage patterns: local shell wrapping, SSH wrapping, tmux relay, zmodem fallback, dragfile, osc52 clipboard.

##### Main Components & Their Relationships
a. User & Terminal
- The end user invokes one of the CLI binaries (`trz`, `tsz`, `trzsz`) in a terminal (local shell or SSH session).
b. CLI Entrypoints (cmd/)
- These binaries parse flags (`--dragfile`, `--relay`, `--zmodem`, `--osc52`).
- They initialize the Core Transfer Engine and hand off to the shell or SSH.
c. Core Transfer Library (trzsz/)
- comm: abstracted stdin/stdout reads and writes over a pty.
- pty_unix/windows: create and manage pseudo-terminals on each OS.
- buffer & pipeline: stage and multiplex data streams (stdin, stdout, stderr).
- filter & escape: detect and emit control sequences to enter transfer mode.
- zmodem: packet construction, parsing, CRC, protocol state machine.
- transfer: high-level upload/download orchestration, progress callbacks.
- archive: optional tar/gzip bundling for directories.
- relay: tmux-aware SSH jump-server relay logic.
- utils_*: OS-specific support (clipboard, file dialogs).
d. Shell or SSH Process
- The CLI spawns a local shell or an SSH client process, connecting its pty to comm.
- Data flows bidirectionally: user ↔ CLI Engine ↔ remote shell.
e. External Services/Dependencies
- Optionally invokes `lrzsz` for zmodem fallback on the client.
- On Windows: may require winpty or inno setup for installers.
f. Packaging & CI
- GitHub Actions and goreleaser produce multi-OS binaries.
- Debian and Inno Setup scripts package `.deb` and `.exe` installers.
- Makefile orchestrates build, test, and install.

##### Architectural Patterns and Principles
- Layered design: CLI layer → Core library layer → OS abstraction layer → External process layer.
- Modular packages: each concern (I/O, protocol, UI, OS) lives in its own Go file.
- Dependency injection: the CLI passes configured options into the library’s entrypoints.
- Cross-platform abstraction: build tags (`_unix`, `_windows`, `_darwin`) hide OS details.

##### Summary Checklist
- A side-panel for packaging/CI workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User & Terminal"]:::external

    %% CLI Binaries
    subgraph "CLI Binaries"
        direction TB
        TRZ["trz"]:::cli
        TSZ["tsz"]:::cli
        TRZSZ["trzsz"]:::cli
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        %% I/O Abstraction
        subgraph "I/O Abstraction"
            direction TB
            COMM["comm.go"]:::core
            PTYU["pty_unix.go"]:::os
            PTYW["pty_windows.go"]:::os
        end
        %% Buffering & Multiplexing
        subgraph "Buffering & Multiplexing"
            direction TB
            BUF["buffer.go"]:::core
            PIPE["pipeline.go"]:::core
        end
        %% Control-Sequence Detection & Emission
        subgraph "Control-Sequence"
            direction TB
            FILTER["filter.go"]:::core
            ESC["escape.go"]:::core
        end
        %% Protocol & Transfer
        ZMODEM["zmodem.go"]:::protocol
        TRANSFER["transfer.go"]:::protocol
        ARCHIVE["archive.go"]:::protocol
        PROGRESS["progress.go"]:::protocol
        RELAY["relay.go"]:::protocol
        %% OS Utilities
        subgraph "OS-Specific Utilities"
            direction TB
            U1["utils_darwin.go"]:::os
            U2["utils_unix.go"]:::os
            U3["utils_other.go"]:::os
            U4["utils_windows.go"]:::os
            DRAG["drag.go"]:::os
        end
        VERSION["version.go"]:::core
    end

    %% Shell/SSH Process
    Shell["Shell/SSH Process"]:::external

    %% External Tools
    subgraph "External Tools"
        direction TB
        LRZSZ["lrzsz"]:::external
        WINPTY["winpty"]:::external
    end

    %% Example Integration
    Example["examples/ssh_client.go"]:::external

    %% Packaging & CI
    subgraph "Packaging & CI"
        direction TB
        GOTEST[".github/workflows/gotest.yml"]:::external
        PUBLISH[".github/workflows/publish.yml"]:::external
        GORELEASER[".goreleaser.yaml"]:::external
        MAKEFILE["Makefile"]:::external
        DEBIAN["debian/*"]:::external
        INNO["inno_setup/*"]:::external
    end

    %% Connections
    User -->|invokes| TRZ
    User -->|invokes| TSZ
    User -->|invokes| TRZSZ

    TRZ -->|"init engine"| COMM
    TSZ -->|"init engine"| COMM
    TRZSZ -->|"init engine"| COMM

    COMM -->|spawn pty| PTYU
    COMM -->|spawn pty| PTYW

    COMM --> BUF
    BUF --> PIPE
    PIPE --> FILTER
    FILTER --> ESC
    ESC --> ZMODEM
    ZMODEM --> TRANSFER
    TRANSFER --> PROGRESS
    TRANSFER --> ARCHIVE
    TRANSFER --> RELAY
    RELAY --> Shell

    Shell --> COMM
    ESC --> Shell

    TRANSFER --> DRAG
    ESC --> U1
    ESC --> U2
    ESC --> U3
    ESC --> U4

    %% Optional external
    ZMODEM -->|fallback| LRZSZ
    COMM -->|windows pty helper| WINPTY

    %% Example integration
    Example --> COMM

    %% Packaging flows
    subgraph "Release Pipeline"
        direction TB
        GOTEST --> GORELEASER
        PUBLISH --> GORELEASER
        MAKEFILE --> GORELEASER
        GORELEASER --> DEBIAN
        GORELEASER --> INNO
    end

    %% Click Events
    click TRZ "https://github.com/trzsz/trzsz-go/blob/main/cmd/trz/main.go"
    click TSZ "https://github.com/trzsz/trzsz-go/blob/main/cmd/tsz/main.go"
    click TRZSZ "https://github.com/trzsz/trzsz-go/blob/main/cmd/trzsz/main.go"
    click COMM "https://github.com/trzsz/trzsz-go/blob/main/trzsz/comm.go"
    click PTYU "https://github.com/trzsz/trzsz-go/blob/main/trzsz/pty_unix.go"
    click PTYW "https://github.com/trzsz/trzsz-go/blob/main/trzsz/pty_windows.go"
    click BUF "https://github.com/trzsz/trzsz-go/blob/main/trzsz/buffer.go"
    click PIPE "https://github.com/trzsz/trzsz-go/blob/main/trzsz/pipeline.go"
    click FILTER "https://github.com/trzsz/trzsz-go/blob/main/trzsz/filter.go"
    click ESC "https://github.com/trzsz/trzsz-go/blob/main/trzsz/escape.go"
    click ZMODEM "https://github.com/trzsz/trzsz-go/blob/main/trzsz/zmodem.go"
    click TRANSFER "https://github.com/trzsz/trzsz-go/blob/main/trzsz/transfer.go"
    click ARCHIVE "https://github.com/trzsz/trzsz-go/blob/main/trzsz/archive.go"
    click PROGRESS "https://github.com/trzsz/trzsz-go/blob/main/trzsz/progress.go"
    click RELAY "https://github.com/trzsz/trzsz-go/blob/main/trzsz/relay.go"
    click U1 "https://github.com/trzsz/trzsz-go/blob/main/trzsz/utils_darwin.go"
    click U2 "https://github.com/trzsz/trzsz-go/blob/main/trzsz/utils_unix.go"
    click U3 "https://github.com/trzsz/trzsz-go/blob/main/trzsz/utils_other.go"
    click U4 "https://github.com/trzsz/trzsz-go/blob/main/trzsz/utils_windows.go"
    click DRAG "https://github.com/trzsz/trzsz-go/blob/main/trzsz/drag.go"
    click VERSION "https://github.com/trzsz/trzsz-go/blob/main/trzsz/version.go"
    click Example "https://github.com/trzsz/trzsz-go/blob/main/examples/ssh_client.go"
    click GOTEST "https://github.com/trzsz/trzsz-go/blob/main/.github/workflows/gotest.yml"
    click PUBLISH "https://github.com/trzsz/trzsz-go/blob/main/.github/workflows/publish.yml"
    click GORELEASER "https://github.com/trzsz/trzsz-go/blob/main/.goreleaser.yaml"
    click MAKEFILE "https://github.com/trzsz/trzsz-go/tree/main/Makefile"
    click DEBIAN "https://github.com/trzsz/trzsz-go/tree/main/debian/*"
    click INNO "https://github.com/trzsz/trzsz-go/tree/main/inno_setup/*"

    %% Styles
    classDef cli fill:#DCEEFB,stroke:#0366D6,color:#0366D6;
    classDef core fill:#E6FFFA,stroke:#028A0F,color:#028A0F;
    classDef protocol fill:#ECFDF5,stroke:#027A48,color:#027A48;
    classDef os fill:#FFF7E6,stroke:#B35C00,color:#B35C00;
    classDef external fill:#F0F0F0,stroke:#666666,color:#333333;
```
