# azimjohn/jprq architecture

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

- Interactive diagram: https://gitdiagram.com/azimjohn/jprq
- Repository: https://github.com/azimjohn/jprq

## Overview

##### Project type and purpose
- JPRQ is an open-source self-hostable tunneling service (similar to ngrok) written in Go.
- It consists of a CLI client (`cli/`), a server component (`server/`), and a static website/docs generator (`website/`).
- Purpose: expose local TCP/HTTP services to the public internet, optionally with a built-in HTTP debugger and custom subdomains.

##### File structure
Top-level:
- `cli/` – the user-facing command-line client.
- `server/` – the public server that accepts connections, manages tunnels, auth, and forwards traffic.
- `website/` – a standalone static site (installation docs, auth portal).
- `Makefile`/`build.sh`/`install.sh`/`jprq.service` – build and deployment artifacts.
- `.github/workflows/` – CI pipelines (tests, static analysis, vulnerability scanning).
Patterns & modules:
- `cli/debugger/` – embedded web UI assets for HTTP debugging.
- `server/config/`, `server/events/`, `server/github/` – configuration, internal event bus, GitHub-based auth/invite logic.
- `server/server/` – TCP server accepting client connections over TLS.
- `server/tunnel/` – HTTP and TCP tunnel implementations forwarding public traffic into client tunnels.
Deployment artifacts:
- `jprq.service` – systemd unit to run the server.
- `install.sh`, `build.sh`, `Makefile` – scripts to build and install both client and server.

##### README for insights
- Describes use cases (HTTP, SSH, custom domains, debugger).
- References an auth flow via `jprq auth <token>` (server must validate tokens via GitHub).
- Mentions a members-only hosted service but emphasizes self-hosting.

1. CLI Client
2. Public Tunnel Server
– Control Plane (HTTP/gRPC for auth, session management)
– Data Plane (TCP server accepting tunnel connections)
– GitHub Auth Service (external API)
– Internal Event Bus
3. End-User Local Server (e.g., `localhost:3000`)
4. Optional HTTP Debugger UI (hosted by CLI, proxied via server)
5. Static Website (optional docs site, `website/`)
6. Build & CI pipeline (GitHub Actions, Makefile)
b. Relationships and interactions:
- CLI → Server (Control Plane): authenticate via API, negotiate tunnel parameters (port, subdomain).
- CLI ↔ Server (Data Plane): maintain a long-lived TLS/TCP connection for forwarding traffic.
- Server → Local Server: on incoming public request, forward over the CLI’s tunnel to the user’s local app.
- Debugger: CLI spins up a local HTTP server for debug UI; server forwards debug HTTP events back to this UI.
- Server → GitHub API: validate membership tokens for hosted service.
c. Architectural patterns & principles:
- Separation of control plane vs. data plane.
- Modular Go packages (configuration, events bus, tunnel implementations).
- Single binary distribution (embedded static assets).
- Self-hosting vs. SaaS duality (same codebase, different deployments).
d. Key technologies & libraries:
- Go modules (`go.mod`), standard net/http, crypto/tls.
- Tailwind CSS + static HTML/JS for the debugger UI.
- systemd service file for server deployment.
- GitHub Actions workflows for CI/CD.

[ ] Show persistent TCP connection: Server Data Plane ↔ CLI Tunnel client.
[ ] Optionally note the website/docs server as a standalone process or static site host.
[ ] Include build/deploy artifacts (Makefile, Dockerfile or systemd) in a corner to illustrate CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    GitHub["GitHub API"]:::external
    Internet["Public Internet"]:::internet

    %% User's Environment
    subgraph "CLI Client" 
        direction TB
        CLI_Main["main.go"]:::go
        CLI_JPRQC["jprqc.go"]:::go
        CLI_Config["config.go"]:::go
        subgraph "HTTP Debugger"
            direction TB
            DBG_Server["server.go"]:::go
            DBG_Parser["parser.go"]:::go
            DBG_Index["index.html"]:::go
            DBG_Script["script.js"]:::go
            DBG_Style["style.css"]:::go
            DBG_Tailwind["tailwind.config.js"]:::go
        end
    end

    Browser["User's Browser"]:::internet
    LocalService["Local App (localhost:3000)"]:::local

    subgraph "Public Tunnel Server"
        direction TB
        subgraph "Control Plane"
            direction TB
            Server_Main["main.go"]:::go
            Server_JPRQ["jprq.go"]:::go
            Config_Module["config/config.go"]:::go
            Config_Test["config/config_test.go"]:::go
            EventBus["events/events.go"]:::go
            EventTest["events/event_test.go"]:::go
            GitHubAuth["github/github.go"]:::go
            GitHubTest["github/github_test.go"]:::go
        end
        subgraph "Data Plane"
            direction TB
            TCP_Server["server/tcpserver.go"]:::go
            SampleCRT["sample.crt"]:::go
            SampleKey["sample.key"]:::go
            TCPTest["tcpserver_test.go"]:::go
            subgraph "Tunnel Manager"
                direction TB
                HTTP_Tunnel["http_tunnel.go"]:::go
                TCP_Tunnel["tcp_tunnel.go"]:::go
                TunnelCore["tunnel.go"]:::go
            end
        end
        Utils["utils.go"]:::go
    end

    Website["Static Website / Docs"]:::go
    subgraph "CI/CD"
        direction TB
        Makefile["Makefile"]:::go
        BuildSh["build.sh"]:::go
        InstallSh["install.sh"]:::go
        ServiceUnit["jprq.service"]:::go
        TestsCI["tests.yaml"]:::go
        StaticAnalysisCI["static-analysis.yaml"]:::go
        GovulnCI["govuln.yaml"]:::go
    end

    %% Flows
    CLI_Main -->|build| CLI_JPRQC
    CLI_JPRQC -->|load| CLI_Config

    CLI_JPRQC -->|HTTPS Control Plane| Server_Main
    Server_JPRQ -->|validate token| GitHub
    CLI_JPRQC -- TLS/TCP Data Plane --> TCP_Server
    Internet -->|incoming request| TCP_Server
    TCP_Server -->|forward tunnel| LocalService

    TCP_Server -->|debug events HTTP| DBG_Server
    DBG_Server -->|HTTP| Browser

    Website -.->|hosts docs| Browser

    Makefile -->|runs| BuildSh
    Makefile --> InstallSh
    InstallSh -->|install unit| ServiceUnit
    TestsCI -->|CI| Server_Main
    StaticAnalysisCI -->|CI| Server_Main
    GovulnCI -->|CI| Server_Main

    %% Auth Flow
    CLI_JPRQC -->|jprq auth| Server_JPRQ
    Server_JPRQ -->|HTTPS| GitHub

    %% Legend (implicit by classes)

    %% Click events
    click CLI_Main "https://github.com/azimjohn/jprq/blob/master/cli/main.go"
    click CLI_JPRQC "https://github.com/azimjohn/jprq/blob/master/cli/jprqc.go"
    click CLI_Config "https://github.com/azimjohn/jprq/blob/master/cli/config.go"
    click DBG_Server "https://github.com/azimjohn/jprq/blob/master/cli/debugger/server.go"
    click DBG_Parser "https://github.com/azimjohn/jprq/blob/master/cli/debugger/parser.go"
    click DBG_Index "https://github.com/azimjohn/jprq/blob/master/cli/debugger/static/index.html"
    click DBG_Script "https://github.com/azimjohn/jprq/blob/master/cli/debugger/static/script.js"
    click DBG_Style "https://github.com/azimjohn/jprq/blob/master/cli/debugger/static/style.css"
    click DBG_Tailwind "https://github.com/azimjohn/jprq/blob/master/cli/debugger/static/tailwind.config.js"
    click Server_Main "https://github.com/azimjohn/jprq/blob/master/server/main.go"
    click Server_JPRQ "https://github.com/azimjohn/jprq/blob/master/server/jprq.go"
    click Config_Module "https://github.com/azimjohn/jprq/blob/master/server/config/config.go"
    click Config_Test "https://github.com/azimjohn/jprq/blob/master/server/config/config_test.go"
    click EventBus "https://github.com/azimjohn/jprq/blob/master/server/events/events.go"
    click EventTest "https://github.com/azimjohn/jprq/blob/master/server/events/event_test.go"
    click GitHubAuth "https://github.com/azimjohn/jprq/blob/master/server/github/github.go"
    click GitHubTest "https://github.com/azimjohn/jprq/blob/master/server/github/github_test.go"
    click TCP_Server "https://github.com/azimjohn/jprq/blob/master/server/server/tcpserver.go"
    click SampleCRT "https://github.com/azimjohn/jprq/blob/master/server/server/sample.crt"
    click SampleKey "https://github.com/azimjohn/jprq/blob/master/server/server/sample.key"
    click TCPTest "https://github.com/azimjohn/jprq/blob/master/server/server/tcpserver_test.go"
    click HTTP_Tunnel "https://github.com/azimjohn/jprq/blob/master/server/tunnel/http_tunnel.go"
    click TCP_Tunnel "https://github.com/azimjohn/jprq/blob/master/server/tunnel/tcp_tunnel.go"
    click TunnelCore "https://github.com/azimjohn/jprq/blob/master/server/tunnel/tunnel.go"
    click Utils "https://github.com/azimjohn/jprq/blob/master/server/utils.go"
    click Website "https://github.com/azimjohn/jprq/blob/master/website/main.go"
    click Website "https://github.com/azimjohn/jprq/blob/master/website/static/index.html"
    click Website "https://github.com/azimjohn/jprq/blob/master/website/static/config.json"
    click Website "https://github.com/azimjohn/jprq/blob/master/website/static/install.sh"
    click Website "https://github.com/azimjohn/jprq/blob/master/website/static/token.html"
    click Makefile "https://github.com/azimjohn/jprq/tree/master/Makefile"
    click BuildSh "https://github.com/azimjohn/jprq/blob/master/build.sh"
    click InstallSh "https://github.com/azimjohn/jprq/blob/master/install.sh"
    click ServiceUnit "https://github.com/azimjohn/jprq/blob/master/jprq.service"
    click TestsCI "https://github.com/azimjohn/jprq/blob/master/.github/workflows/tests.yaml"
    click StaticAnalysisCI "https://github.com/azimjohn/jprq/blob/master/.github/workflows/static-analysis.yaml"
    click GovulnCI "https://github.com/azimjohn/jprq/blob/master/.github/workflows/govuln.yaml"

    %% Styles
    classDef go fill:#cce5ff,stroke:#004085,color:#004085;
    classDef local fill:#d4edda,stroke:#155724,color:#155724;
    classDef internet fill:#ffe5b4,stroke:#e69500,color:#a85e00;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#41464b;
```
