# arturoeanton/go-grpc-tunnel architecture

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

- Interactive diagram: https://gitdiagram.com/arturoeanton/go-grpc-tunnel
- Repository: https://github.com/arturoeanton/go-grpc-tunnel

## Overview

##### Project Type and Purpose
- Type: Open-source CLI tool for reverse TCP tunneling using Go and gRPC.
- Purpose: Expose services (e.g., a Firebird database) behind NAT/firewall by creating a secure, multiplexed, bidirectional tunnel between a public server and a local agent.

##### File-Structure Analysis
- Top-level:
- cmd/server – entry point for the public tunnel server
- cmd/client – entry point for the local tunnel agent
- proto – Protocol Buffers definitions and generated gRPC stubs
- certs – TLS certificates for securing gRPC channel
- run_server.sh/.ps1 & run_client.sh/.ps1 – scripts to configure and launch components
- Build & Configuration:
- go.mod/go.sum for dependency management
- Shell/PowerShell scripts for environment variables (tokens, ports, certificate paths)

##### Core Architecture (from README)
- Two main components:
a. Tunnel Server
- Listens for gRPC agent connections (with TLS + token auth)
- Listens for incoming TCP connections from external clients
- Multiplexes data over a bidirectional gRPC stream
b. Tunnel Agent (Client)
- Connects outward to the tunnel server’s gRPC endpoint
- Authenticates using shared token and TLS
- Forwards instructions to open local TCP connections to the target service (e.g., Firebird)

##### Main Components
- External Client (e.g., Firebird-client app)
- Tunnel Server (public)
- gRPC/TLS Channel (Internet)
- Tunnel Agent (local)
- Target Service (e.g., Firebird DB on localhost:3050)

##### Relationships and Data Flow
- Step 1: External Client → TCP → Tunnel Server (External Port, e.g., :8080)
- Step 2: Tunnel Server ↔ Bidirectional gRPC/TLS Stream → Tunnel Agent (port :50051)
- Step 3: Tunnel Agent → TCP → Target Service (localhost:3050)
- Multiplexing: single gRPC stream carries frames for multiple concurrent TCP connections, distinguished by ConnectionId

##### Architectural Patterns & Principles
- Client-Server separation: clear split between public endpoint (server) and private network proxy (agent)
- Bidirectional streaming RPC: implements a lightweight multiplexing layer on top of gRPC
- Token-based authentication + TLS for secure channel
- Environment-driven configuration to keep binaries generic and reusable

##### Technologies & Frameworks
- Go language (cmd/server/main.go, cmd/client/main.go)
- gRPC + Protocol Buffers (proto/tunnel.proto)
- TLS certificates (certs/server.crt, certs/server.key)
- Shell/PowerShell scripts for automated runs

##### Essential Details
- Authentication step on gRPC connection setup
- Port numbers (50051 for gRPC, 8080 for external TCP, 3050 for local DB)
- Call out that traffic is encrypted only between server and agent
- Environment variables used by run scripts for clarity

## Diagram (Mermaid)

```mermaid
flowchart TD
    ExternalClient["External Client\n(e.g., Firebird-client"]:::external
    subgraph "Tunnel Server"
        TS_Main["cmd/server/main.go"]:::server
        TS_Scripts["run_server.sh\nrun_server.ps1"]:::script
        TS_Certs["certs/server.crt\ncerts/server.key"]:::cert
    end
    subgraph "gRPC/TLS Channel"
        GRPC["gRPC/TLS\nFrames(ConnectionId,Payload)"]:::grpc
    end
    subgraph "Tunnel Agent"
        TA_Main["cmd/client/main.go"]:::agent
        TA_Scripts["run_client.sh\nrun_client.ps1"]:::script
    end
    TargetService["Target Service\nlocalhost:3050"]:::target
    subgraph "Project Files"
        Proto1["proto/tunnel.proto"]:::proto
        Proto2["proto/tunnel.pb.go\nproto/tunnel_grpc.pb.go"]:::proto
        Config["go.mod\ngo.sum"]:::config
        Docs["README.md\nLICENSE"]:::docs
    end

    ExternalClient -->|"TCP :8080"| TS_Main
    TS_Main -->|"gRPC/TLS :50051"| GRPC
    GRPC -->|"gRPC/TLS :50051"| TA_Main
    TA_Main -->|"TCP :3050"| TargetService

    %% Click Events
    click TS_Main "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/cmd/server/main.go"
    click TS_Scripts "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/run_server.sh"
    click TS_Scripts "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/run_server.ps1"
    click TS_Certs "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/certs/server.crt"
    click TS_Certs "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/certs/server.key"
    click TA_Main "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/cmd/client/main.go"
    click TA_Scripts "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/run_client.sh"
    click TA_Scripts "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/run_client.ps1"
    click Proto1 "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/proto/tunnel.proto"
    click Proto2 "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/proto/tunnel.pb.go"
    click Proto2 "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/proto/tunnel_grpc.pb.go"
    click Config "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/go.mod"
    click Config "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/go.sum"
    click Docs "https://github.com/arturoeanton/go-grpc-tunnel/blob/main/README.md"
    click Docs "https://github.com/arturoeanton/go-grpc-tunnel/tree/main/LICENSE"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000;
    classDef server fill:#90EE90,stroke:#000;
    classDef agent fill:#FFA500,stroke:#000;
    classDef grpc fill:#F08080,stroke-dasharray: 5 5,stroke:#800000;
    classDef target fill:#D3D3D3,stroke:#000;
    classDef script fill:#FFFACD,stroke:#000;
    classDef cert fill:#E6E6FA,stroke:#000;
    classDef proto fill:#98FB98,stroke:#000;
    classDef config fill:#F5F5F5,stroke:#000;
    classDef docs fill:#FFB6C1,stroke:#000;
```
