# anomalyco/opentunnel architecture

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

- Interactive diagram: https://gitdiagram.com/anomalyco/opentunnel
- Repository: https://github.com/anomalyco/opentunnel

## Overview

OpenTunnel provides CLI and SDK clients for creating named TLS tunnels, claiming routes, and forwarding visitor connections to local applications while keeping TLS termination and private keys on the client. The server coordinates API and certificate issuance, stores tunnel state, and relays encrypted traffic; the website explains the service. The graph preserves the major server subsystems identified in the source index. Some internal wiring is not shown in the excerpts, so only documented or source-index-supported relationships are connected.

Main entry points: [`crates/opentunnel-server/src/http.rs`](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/http.rs) (HTTP API), [`crates/opentunnel-server/src/service.rs`](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/service.rs) (Tunnel records and bridges), [`crates/opentunnel-server/src/jobs.rs`](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/jobs.rs) (Issuance jobs), [`crates/opentunnel/src/client.rs`](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel/src/client.rs) (Rust client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client applications"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_cli_control["Background service<br/>[control.rs]"]
  node_rust_client["Rust client<br/>[client.rs]"]
  node_rust_tunnel["Local TLS tunnel<br/>[tunnel.rs]"]
  node_rust_storage["Rust identity storage<br/>[storage.rs]"]
  node_sdk["TypeScript SDK<br/>[client.ts]"]
  node_sdk_routes["SDK routes<br/>[routes.ts]"]
  node_sdk_storage["SDK identity storage<br/>[storage.ts]"]
end

subgraph group_shared["Shared protocol"]
  node_protocol["Wire and API contract<br/>[bridge-protocol.ts]"]
end

subgraph group_server["Server traffic and API"]
  node_server_http["HTTP API<br/>[http.rs]"]
  node_server_ingress["TLS ingress and routing<br/>[tls.rs]"]
  node_server_bridge["Encrypted bridge relay<br/>[bridge.rs]"]
  node_server_tunnels["Tunnel records and bridges<br/>[service.rs]"]
  node_server_cluster["Cluster mesh<br/>[cluster.rs]"]
  node_server_net["Network helpers<br/>[net.rs]"]
  node_analytics["Service analytics<br/>[analytics.rs]"]
  node_metrics["Prometheus metrics<br/>[metrics.rs]"]
end

subgraph group_issuance["Certificates and state"]
  node_limits["Abuse limits<br/>[limits.rs]"]
  node_jobs["Issuance jobs<br/>[jobs.rs]"]
  node_acme["ACME issuance<br/>[acme.rs]"]
  node_dns["DNS challenges<br/>[dns.rs]"]
  node_store[("MySQL state store<br/>[store.rs]")]
  node_crypto["Token cryptography<br/>[crypto.rs]"]
  node_clock["Time and scheduling<br/>[clock.rs]"]
end

subgraph group_web["Website"]
  node_website["Landing website<br/>[App.tsx]"]
end

node_user(("Tunnel operator"))
node_visitor(("Visitor"))
node_local_app["Local application"]

node_user -->|"configures routes"| node_cli
node_cli -->|"starts service"| node_cli_control
node_cli -.->|"uses client"| node_rust_client
node_user -->|"configures tunnels"| node_sdk
node_sdk -->|"claims routes"| node_sdk_routes
node_sdk -->|"persists identities"| node_sdk_storage
node_rust_client -->|"loads identities"| node_rust_storage
node_rust_client -->|"runs tunnel"| node_rust_tunnel
node_rust_client -.->|"calls API"| node_server_http
node_sdk -.->|"calls API"| node_server_http
node_rust_client -->|"uses wire contract"| node_protocol
node_sdk -->|"uses wire contract"| node_protocol
node_visitor -->|"sends TLS traffic"| node_server_ingress
node_server_ingress -->|"forwards encrypted stream"| node_server_bridge
node_server_bridge -->|"uses live bridges"| node_server_tunnels
node_server_bridge -->|"carries encrypted stream"| node_rust_tunnel
node_rust_tunnel -->|"forwards plaintext"| node_local_app
node_server_http -->|"handles tunnel API"| node_server_tunnels
node_server_http -->|"serves website"| node_website
node_server_http -->|"checks quotas"| node_limits
node_server_http -->|"hashes admin token"| node_crypto
node_server_tunnels -->|"persists records"| node_store
node_server_tunnels -->|"announces events"| node_server_cluster
node_server_tunnels -->|"publishes events"| node_analytics
node_jobs -->|"loads jobs"| node_store
node_jobs -->|"requests issuance"| node_acme
node_jobs -->|"sets challenges"| node_dns
node_jobs -->|"uses crypto"| node_crypto
node_jobs -->|"schedules renewals"| node_clock
node_limits -->|"stores rates"| node_store
node_server_ingress -.->|"uses network helpers"| node_server_net
node_server_cluster -->|"uses network helpers"| node_server_net
node_server_tunnels -.->|"records metrics"| node_metrics
node_website -->|"explains service"| node_visitor

click node_cli "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-cli/src/main.rs"
click node_cli_control "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-cli/src/control.rs"
click node_rust_client "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel/src/client.rs"
click node_rust_tunnel "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel/src/tunnel.rs"
click node_rust_storage "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel/src/storage.rs"
click node_sdk "https://github.com/anomalyco/opentunnel/blob/dev/packages/client/src/effect/client.ts"
click node_sdk_routes "https://github.com/anomalyco/opentunnel/blob/dev/packages/client/src/effect/routes.ts"
click node_sdk_storage "https://github.com/anomalyco/opentunnel/blob/dev/packages/client/src/effect/storage.ts"
click node_protocol "https://github.com/anomalyco/opentunnel/blob/dev/packages/protocol/src/bridge-protocol.ts"
click node_server_http "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/http.rs"
click node_server_ingress "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/tls.rs"
click node_server_bridge "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/bridge.rs"
click node_server_tunnels "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/service.rs"
click node_server_cluster "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/cluster.rs"
click node_server_net "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/net.rs"
click node_limits "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/limits.rs"
click node_jobs "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/jobs.rs"
click node_acme "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/acme.rs"
click node_dns "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/dns.rs"
click node_store "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/store.rs"
click node_crypto "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/crypto.rs"
click node_analytics "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/analytics.rs"
click node_metrics "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/metrics.rs"
click node_clock "https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/clock.rs"
click node_website "https://github.com/anomalyco/opentunnel/blob/dev/packages/website/src/App.tsx"

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,node_cli_control,node_rust_client,node_rust_tunnel,node_rust_storage,node_sdk,node_sdk_routes,node_sdk_storage toneBlue
class node_protocol toneAmber
class node_server_http,node_server_ingress,node_server_bridge,node_server_tunnels,node_server_cluster,node_server_net,node_analytics,node_metrics toneMint
class node_limits,node_jobs,node_acme,node_dns,node_store,node_crypto,node_clock toneRose
class node_website,node_user,node_visitor,node_local_app toneIndigo
```

## Components

### Client applications

- [CLI commands](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-cli/src/main.rs): `crates/opentunnel-cli/src/main.rs`
- [Background service](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-cli/src/control.rs): `crates/opentunnel-cli/src/control.rs`
- [Rust client](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel/src/client.rs): `crates/opentunnel/src/client.rs`
- [Local TLS tunnel](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel/src/tunnel.rs): `crates/opentunnel/src/tunnel.rs`
- [Rust identity storage](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel/src/storage.rs): `crates/opentunnel/src/storage.rs`
- [TypeScript SDK](https://github.com/anomalyco/opentunnel/blob/dev/packages/client/src/effect/client.ts): `packages/client/src/effect/client.ts`
- [SDK routes](https://github.com/anomalyco/opentunnel/blob/dev/packages/client/src/effect/routes.ts): `packages/client/src/effect/routes.ts`
- [SDK identity storage](https://github.com/anomalyco/opentunnel/blob/dev/packages/client/src/effect/storage.ts): `packages/client/src/effect/storage.ts`

### Shared protocol

- [Wire and API contract](https://github.com/anomalyco/opentunnel/blob/dev/packages/protocol/src/bridge-protocol.ts): `packages/protocol/src/bridge-protocol.ts`

### Server traffic and API

- [HTTP API](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/http.rs): `crates/opentunnel-server/src/http.rs`
- [TLS ingress and routing](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/tls.rs): `crates/opentunnel-server/src/tls.rs`
- [Encrypted bridge relay](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/bridge.rs): `crates/opentunnel-server/src/bridge.rs`
- [Tunnel records and bridges](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/service.rs): `crates/opentunnel-server/src/service.rs`
- [Cluster mesh](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/cluster.rs): `crates/opentunnel-server/src/cluster.rs`
- [Network helpers](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/net.rs): `crates/opentunnel-server/src/net.rs`
- [Service analytics](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/analytics.rs): `crates/opentunnel-server/src/analytics.rs`
- [Prometheus metrics](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/metrics.rs): `crates/opentunnel-server/src/metrics.rs`

### Certificates and state

- [Abuse limits](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/limits.rs): `crates/opentunnel-server/src/limits.rs`
- [Issuance jobs](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/jobs.rs): `crates/opentunnel-server/src/jobs.rs`
- [ACME issuance](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/acme.rs): `crates/opentunnel-server/src/acme.rs`
- [DNS challenges](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/dns.rs): `crates/opentunnel-server/src/dns.rs`
- [MySQL state store](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/store.rs): `crates/opentunnel-server/src/store.rs`
- [Token cryptography](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/crypto.rs): `crates/opentunnel-server/src/crypto.rs`
- [Time and scheduling](https://github.com/anomalyco/opentunnel/blob/dev/crates/opentunnel-server/src/clock.rs): `crates/opentunnel-server/src/clock.rs`

### Website

- [Landing website](https://github.com/anomalyco/opentunnel/blob/dev/packages/website/src/App.tsx): `packages/website/src/App.tsx`

### Other components

- **Tunnel operator**
- **Visitor**
- **Local application**

## Connections

- Tunnel operator → CLI commands: configures routes (evidence: `README.md`)
- CLI commands → Background service: starts service (evidence: `crates/opentunnel-cli/src/main.rs`)
- CLI commands → Rust client: uses client
- Tunnel operator → TypeScript SDK: configures tunnels (evidence: `README.md`)
- TypeScript SDK → SDK routes: claims routes (evidence: `packages/client/src/effect/client.ts`)
- TypeScript SDK → SDK identity storage: persists identities (evidence: `packages/client/src/effect/client.ts`)
- Rust client → Rust identity storage: loads identities (evidence: `crates/opentunnel/src/client.rs`)
- Rust client → Local TLS tunnel: runs tunnel (evidence: `crates/opentunnel/src/client.rs`)
- Rust client → HTTP API: calls API
- TypeScript SDK → HTTP API: calls API
- Rust client → Wire and API contract: uses wire contract (evidence: `README.md`)
- TypeScript SDK → Wire and API contract: uses wire contract (evidence: `packages/client/src/effect/client.ts`)
- Visitor → TLS ingress and routing: sends TLS traffic (evidence: `README.md`)
- TLS ingress and routing → Encrypted bridge relay: forwards encrypted stream (evidence: `README.md`)
- Encrypted bridge relay → Tunnel records and bridges: uses live bridges (evidence: `crates/opentunnel-server/src/service.rs`)
- Encrypted bridge relay → Local TLS tunnel: carries encrypted stream (evidence: `README.md`)
- Local TLS tunnel → Local application: forwards plaintext (evidence: `README.md`)
- HTTP API → Tunnel records and bridges: handles tunnel API (evidence: `crates/opentunnel-server/src/http.rs`)
- HTTP API → Landing website: serves website (evidence: `crates/opentunnel-server/src/http.rs`)
- HTTP API → Abuse limits: checks quotas (evidence: `crates/opentunnel-server/src/http.rs`)
- HTTP API → Token cryptography: hashes admin token (evidence: `crates/opentunnel-server/src/http.rs`)
- Tunnel records and bridges → MySQL state store: persists records (evidence: `crates/opentunnel-server/src/service.rs`)
- Tunnel records and bridges → Cluster mesh: announces events (evidence: `crates/opentunnel-server/src/service.rs`)
- Tunnel records and bridges → Service analytics: publishes events (evidence: `crates/opentunnel-server/src/service.rs`)
- Issuance jobs → MySQL state store: loads jobs (evidence: `crates/opentunnel-server/src/jobs.rs`)
- Issuance jobs → ACME issuance: requests issuance (evidence: `crates/opentunnel-server/src/jobs.rs`)
- Issuance jobs → DNS challenges: sets challenges (evidence: `crates/opentunnel-server/src/jobs.rs`)
- Issuance jobs → Token cryptography: uses crypto (evidence: `crates/opentunnel-server/src/jobs.rs`)
- Issuance jobs → Time and scheduling: schedules renewals (evidence: `crates/opentunnel-server/src/jobs.rs`)
- Abuse limits → MySQL state store: stores rates (evidence: `crates/opentunnel-server/src/limits.rs`)
- TLS ingress and routing → Network helpers: uses network helpers
- Cluster mesh → Network helpers: uses network helpers (evidence: `crates/opentunnel-server/src/cluster.rs`)
- Tunnel records and bridges → Prometheus metrics: records metrics (evidence: `crates/opentunnel-server/src/service.rs`)
- Landing website → Visitor: explains service (evidence: `packages/website/src/App.tsx`)