# zzjin/portproxy architecture

> Architecture diagram of the GitHub repository zzjin/portproxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zzjin/portproxy
- Repository: https://github.com/zzjin/portproxy

## Overview

portproxy assigns stable local URLs to development servers and routes requests arriving from an existing TLS-terminating reverse proxy. The main workflow infers a name, chooses or accepts an app port, starts the command, registers its route, and ensures the on-demand proxy is available. Workspace fleets, worktree-aware naming, static aliases, route cleanup, and URL lookup/listing are separate capabilities. The sampled excerpts show proxy forwarding and route persistence; some CLI command wiring and proxy lifecycle details are documented in the README but not fully sampled.

Main entry points: [`src/main.rs`](https://github.com/zzjin/portproxy/blob/main/src/main.rs) (Run applications), [`src/proxy.rs`](https://github.com/zzjin/portproxy/blob/main/src/proxy.rs) (HTTP proxy), [`src/routes.rs`](https://github.com/zzjin/portproxy/blob/main/src/routes.rs) (Route store), [`src/naming.rs`](https://github.com/zzjin/portproxy/blob/main/src/naming.rs) (Name inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and process launch"]
  node_cli_dispatch["CLI dispatch<br/>[main.rs]"]
  node_run_apps["Run applications<br/>[main.rs]"]
  node_port_select["Port selection<br/>[ports.rs]"]
  node_proxy_control["Proxy lifecycle<br/>[main.rs]"]
  node_route_commands["Route commands<br/>[main.rs]"]
  node_url_output["URL lookup and listing<br/>[main.rs]"]
  node_npm_install["npm installer<br/>[install.js]"]
end

subgraph group_names["Names and workspaces"]
  node_name_inference["Name inference<br/>[naming.rs]"]
  node_workspace_discovery["Workspace discovery<br/>[workspace.rs]"]
  node_worktree_suffix["Worktree suffix<br/>[worktree.rs]"]
end

subgraph group_routing["Routes and proxy"]
  node_route_store[("Route store<br/>[routes.rs]")]
  node_route_record["Route record<br/>[types.rs]"]
  node_proxy_server["HTTP proxy<br/>[proxy.rs]"]
  node_websocket_tunnel["WebSocket tunnel<br/>[proxy.rs]"]
end

subgraph group_settings["Configuration and utilities"]
  node_project_config["Project configuration<br/>[config.rs]"]
  node_global_config["Global configuration<br/>[config.rs]"]
  node_shared_utils["Shared utilities<br/>[utils.rs]"]
end

node_developer(("Developer"))
node_front_proxy["Caddy / Nginx"]
node_app["Development server"]

node_developer -->|"runs commands"| node_cli_dispatch
node_cli_dispatch -->|"dispatches run"| node_run_apps
node_run_apps -->|"infers name"| node_name_inference
node_name_inference -->|"checks workspace"| node_workspace_discovery
node_name_inference -.->|"adds suffix"| node_worktree_suffix
node_run_apps -->|"loads overrides"| node_project_config
node_run_apps -->|"chooses port"| node_port_select
node_run_apps -->|"registers route"| node_route_store
node_run_apps -->|"ensures proxy"| node_proxy_control
node_run_apps -->|"starts command"| node_app
node_workspace_discovery -->|"enumerates packages"| node_run_apps
node_proxy_control -->|"loads listen settings"| node_global_config
node_proxy_control -->|"starts proxy"| node_proxy_server
node_route_commands -->|"adds or prunes"| node_route_store
node_route_store -->|"persists routes"| node_route_record
node_route_store -->|"checks process liveness"| node_shared_utils
node_proxy_server -->|"loads route table"| node_route_store
node_front_proxy -->|"forwards HTTP"| node_proxy_server
node_proxy_server -->|"forwards requests"| node_app
node_proxy_server -->|"dispatches upgrades"| node_websocket_tunnel
node_websocket_tunnel -->|"tunnels connection"| node_app
node_cli_dispatch -->|"handles get and list"| node_url_output
node_url_output -->|"formats URLs"| node_global_config
node_developer -->|"installs package"| node_npm_install

click node_cli_dispatch "https://github.com/zzjin/portproxy/blob/main/src/main.rs"
click node_run_apps "https://github.com/zzjin/portproxy/blob/main/src/main.rs"
click node_port_select "https://github.com/zzjin/portproxy/blob/main/src/ports.rs"
click node_proxy_control "https://github.com/zzjin/portproxy/blob/main/src/main.rs"
click node_route_commands "https://github.com/zzjin/portproxy/blob/main/src/main.rs"
click node_name_inference "https://github.com/zzjin/portproxy/blob/main/src/naming.rs"
click node_workspace_discovery "https://github.com/zzjin/portproxy/blob/main/src/workspace.rs"
click node_worktree_suffix "https://github.com/zzjin/portproxy/blob/main/src/worktree.rs"
click node_project_config "https://github.com/zzjin/portproxy/blob/main/src/config.rs"
click node_global_config "https://github.com/zzjin/portproxy/blob/main/src/config.rs"
click node_shared_utils "https://github.com/zzjin/portproxy/blob/main/src/utils.rs"
click node_route_store "https://github.com/zzjin/portproxy/blob/main/src/routes.rs"
click node_route_record "https://github.com/zzjin/portproxy/blob/main/src/types.rs"
click node_proxy_server "https://github.com/zzjin/portproxy/blob/main/src/proxy.rs"
click node_websocket_tunnel "https://github.com/zzjin/portproxy/blob/main/src/proxy.rs"
click node_url_output "https://github.com/zzjin/portproxy/blob/main/src/main.rs"
click node_npm_install "https://github.com/zzjin/portproxy/blob/main/npm/install.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_dispatch,node_run_apps,node_port_select,node_proxy_control,node_route_commands,node_url_output,node_npm_install toneBlue
class node_name_inference,node_workspace_discovery,node_worktree_suffix toneAmber
class node_route_store,node_route_record,node_proxy_server,node_websocket_tunnel,node_app toneMint
class node_project_config,node_global_config,node_shared_utils toneRose
class node_developer,node_front_proxy toneIndigo
```

## Components

### CLI and process launch

- [CLI dispatch](https://github.com/zzjin/portproxy/blob/main/src/main.rs): `src/main.rs`
- [Run applications](https://github.com/zzjin/portproxy/blob/main/src/main.rs): `src/main.rs`
- [Port selection](https://github.com/zzjin/portproxy/blob/main/src/ports.rs): `src/ports.rs`
- [Proxy lifecycle](https://github.com/zzjin/portproxy/blob/main/src/main.rs): `src/main.rs`
- [Route commands](https://github.com/zzjin/portproxy/blob/main/src/main.rs): `src/main.rs`
- [URL lookup and listing](https://github.com/zzjin/portproxy/blob/main/src/main.rs): `src/main.rs`
- [npm installer](https://github.com/zzjin/portproxy/blob/main/npm/install.js): `npm/install.js`

### Names and workspaces

- [Name inference](https://github.com/zzjin/portproxy/blob/main/src/naming.rs): `src/naming.rs`
- [Workspace discovery](https://github.com/zzjin/portproxy/blob/main/src/workspace.rs): `src/workspace.rs`
- [Worktree suffix](https://github.com/zzjin/portproxy/blob/main/src/worktree.rs): `src/worktree.rs`

### Routes and proxy

- [Route store](https://github.com/zzjin/portproxy/blob/main/src/routes.rs): `src/routes.rs`
- [Route record](https://github.com/zzjin/portproxy/blob/main/src/types.rs): `src/types.rs`
- [HTTP proxy](https://github.com/zzjin/portproxy/blob/main/src/proxy.rs): `src/proxy.rs`
- [WebSocket tunnel](https://github.com/zzjin/portproxy/blob/main/src/proxy.rs): `src/proxy.rs`

### Configuration and utilities

- [Project configuration](https://github.com/zzjin/portproxy/blob/main/src/config.rs): `src/config.rs`
- [Global configuration](https://github.com/zzjin/portproxy/blob/main/src/config.rs): `src/config.rs`
- [Shared utilities](https://github.com/zzjin/portproxy/blob/main/src/utils.rs): `src/utils.rs`

### Other components

- **Developer**
- **Caddy / Nginx**
- **Development server**

## Connections

- Developer → CLI dispatch: runs commands (evidence: `README.md`)
- CLI dispatch → Run applications: dispatches run (evidence: `src/main.rs`)
- Run applications → Name inference: infers name (evidence: `README.md`)
- Name inference → Workspace discovery: checks workspace (evidence: `src/naming.rs`)
- Name inference → Worktree suffix: adds suffix
- Run applications → Project configuration: loads overrides (evidence: `README.md`)
- Run applications → Port selection: chooses port (evidence: `README.md`)
- Run applications → Route store: registers route (evidence: `README.md`)
- Run applications → Proxy lifecycle: ensures proxy (evidence: `README.md`)
- Run applications → Development server: starts command (evidence: `README.md`)
- Workspace discovery → Run applications: enumerates packages (evidence: `README.md`)
- Proxy lifecycle → Global configuration: loads listen settings (evidence: `README.md`)
- Proxy lifecycle → HTTP proxy: starts proxy (evidence: `README.md`)
- Route commands → Route store: adds or prunes (evidence: `src/main.rs`)
- Route store → Route record: persists routes (evidence: `src/routes.rs`)
- Route store → Shared utilities: checks process liveness (evidence: `src/routes.rs`)
- HTTP proxy → Route store: loads route table (evidence: `src/proxy.rs`)
- Caddy / Nginx → HTTP proxy: forwards HTTP (evidence: `README.md`)
- HTTP proxy → Development server: forwards requests (evidence: `src/proxy.rs`)
- HTTP proxy → WebSocket tunnel: dispatches upgrades (evidence: `src/proxy.rs`)
- WebSocket tunnel → Development server: tunnels connection (evidence: `src/proxy.rs`)
- CLI dispatch → URL lookup and listing: handles get and list (evidence: `README.md`)
- URL lookup and listing → Global configuration: formats URLs (evidence: `src/config.rs`)
- Developer → npm installer: installs package (evidence: `README.md`)
