# passeway/naiveproxy architecture

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

- Interactive diagram: https://gitdiagram.com/passeway/naiveproxy
- Repository: https://github.com/passeway/naiveproxy

## Overview

##### Project type and purpose
- This is an open-source, single-purpose tooling project whose goal is to automate installation, compilation, configuration, and management of NaïveProxy and a Caddy forward-proxy server.
- The README shows end-user “one-click” install scripts (naive.sh, caddy.sh, go.sh), CI definitions (.github/workflows), and a Vercel config for hosting the web installer.

##### File structure
Top-level elements:
- .github/workflows/build.yml – Defines CI steps (lint, test scripts, publish artifacts).
- caddy.sh – Shell script to install/compile Caddy with the forwardproxy plugin.
- go.sh – Script to install/uninstall Go runtime.
- naive.sh – Main installer wrapper; orchestrates go.sh and caddy.sh and configures systemd.
- vercel.json – Configuration that exposes naive.sh (and possibly the static README) via a serverless HTTP endpoint for `bash <(curl…)`.

There is no “frontend” or “backend” code: this is purely a CLI installer/tool.

##### Extract additional insights from the README
- A “one-click” invocation via `bash <(curl -fsSL naiveproxy-sigma.vercel.app)`
- Detailed guide for Go installation, xcaddy build, Caddyfile creation/validation, systemd service management, and eventual uninstallation.
- Target endpoints: Listen on SOCKS5 localhost:1080 and forward to an upstream HTTPS proxy.

##### Components
a. End User Environment
- User’s Shell (bash) on a Linux server or VM
- Systemd & filesystem for service management

b. Installer Hosting
- Vercel CDN/EDGE – Hosts the naive.sh entry point (vercel.json)
- GitHub Repository – Source of truth; triggers CI in GitHub Actions

c. Tools & Dependencies
- go.sh → Installs the Go toolchain
- xcaddy (via go install) → Compiles Caddy with the forwardproxy plugin
- caddy.sh → Wraps xcaddy build, moves binary to /usr/bin

d. Runtime Components
- Caddy Web Server with forwardproxy module
- Caddyfile config (TLS, basic_auth, hide_via, reverse_proxy)
- NaïveProxy client (connects to upstream HTTPS proxy using credentials)

##### Relationships and data flows
- User invokes `curl | bash` to fetch naive.sh from Vercel → executes on host.
- naive.sh calls go.sh to install Go → go.sh pulls from GitHub/golang PPA.
- naive.sh calls go install github.com/caddyserver/xcaddy … → produces xcaddy binary in ~/go/bin.
- caddy.sh uses xcaddy to build Caddy + forwardproxy → installs /usr/bin/caddy.
- naive.sh creates /etc/caddy/Caddyfile, systemd service, then `systemctl start caddy`.
- Caddy listens on 443, terminates TLS, applies forwardproxy, optionally reverse_proxy to a demo backend.
- Client tools (e.g. browsers, system SOCKS5 clients) connect to localhost:1080 → Caddy forwardproxy → upstream HTTPS proxy.

##### Architectural patterns and principles
- Scripting orchestration: clearly separated scripts for dependency (go.sh), build (caddy.sh), and overall installer (naive.sh).
- Infrastructure as code: Caddyfile + systemd unit definition managed by the installer.
- CI/CD pipeline: GitHub Actions ensures scripts remain valid, optionally tests curl install.
- CDN distribution: Vercel serves a static shell script endpoint for zero-touch installs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Distribution Layer
    subgraph "Distribution & Hosting"
        direction TB
        Vercel["Vercel CDN/Edge"]:::infra
        NaiveEntry["naive.sh (Installer Entry Point)"]:::shell
        Vercel -->|"fetch script"| NaiveEntry
    end

    %% CI/CD Layer
    subgraph "CI/CD Pipeline"
        direction TB
        GitHubRepo["GitHub Repository"]:::external
        WorkflowsDir[".github/workflows (CI Workflows Directory)"]:::external
        BuildYML["build.yml (CI/CD Pipeline Definition)"]:::external
        GitHubActions["GitHub Actions"]:::infra
        GitHubRepo -->|triggers CI| WorkflowsDir
        WorkflowsDir --> BuildYML
        BuildYML -->|executes| GitHubActions
    end

    %% Installer Scripts
    subgraph "Installer Scripts"
        direction TB
        GoInstall["go.sh (Go Toolchain Installer)"]:::shell
        XCaddyBuild["xcaddy build step"]:::binary
        CaddyBuild["caddy.sh (Caddy Build Script)"]:::shell
        NaiveEntry -->|calls| GoInstall
        NaiveEntry -->|invokes| XCaddyBuild
        XCaddyBuild -->|wrapped by| CaddyBuild
    end

    %% Installer Execution on Host
    subgraph "Host Installation"
        direction TB
        GoPPA["Go PPA / GitHub"]:::external
        USRCaddy["/usr/bin/caddy (Installed Binary)"]:::binary
        CaddyFile["/etc/caddy/Caddyfile"]:::service
        SystemdUnit["systemd Service Unit"]:::service
        NaiveEntry -->|calls| GoInstall
        GoInstall -->|install Go from| GoPPA
        CaddyBuild -->|installs binary| USRCaddy
        NaiveEntry -->|"write config"| CaddyFile
        NaiveEntry -->|"write unit"| SystemdUnit
        SystemdUnit -->|start service| USRCaddy
    end

    %% Runtime Components
    subgraph "Runtime"
        direction TB
        CaddyService["Caddy Web Server (forwardproxy)"]:::service
        ClientApps["Client Apps (e.g., Browsers, SOCKS5 Clients)"]:::external
        UpstreamProxy["Upstream HTTPS Proxy"]:::external
        USRCaddy -->|runs as| CaddyService
        ClientApps -->|connect SOCKS5| CaddyService
        CaddyService -->|forward to| UpstreamProxy
    end

    %% Documentation
    subgraph "Documentation & Config"
        direction TB
        Readme["README.md (Project Documentation & Usage Guide)"]:::external
        Vercel --> Readme
    end

    %% Click Events
    click NaiveEntry "https://github.com/passeway/naiveproxy/blob/main/naive.sh"
    click GoInstall "https://github.com/passeway/naiveproxy/blob/main/go.sh"
    click CaddyBuild "https://github.com/passeway/naiveproxy/blob/main/caddy.sh"
    click WorkflowsDir "https://github.com/passeway/naiveproxy/tree/main/.github/workflows"
    click BuildYML "https://github.com/passeway/naiveproxy/blob/main/.github/workflows/build.yml"
    click Vercel "https://github.com/passeway/naiveproxy/blob/main/vercel.json"
    click Readme "https://github.com/passeway/naiveproxy/blob/main/README.md"

    %% Styles
    classDef shell fill:#FFEB3B,stroke:#333,stroke-width:1px
    classDef binary fill:#03A9F4,stroke:#333,stroke-width:1px
    classDef service fill:#8BC34A,stroke:#333,stroke-width:1px
    classDef infra fill:#FF9800,stroke:#333,stroke-width:1px
    classDef external fill:#BDBDBD,stroke:#333,stroke-width:1px
```
