# aminmgmt/backpack architecture

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

- Interactive diagram: https://gitdiagram.com/aminmgmt/backpack
- Repository: https://github.com/aminmgmt/backpack

## Overview

BackPack is a Go tunneling and server-operations product. Operators configure the Iran and kharej endpoints through the CLI or web panel; the resulting client/server engines establish reverse tunnels that carry forwarded TCP/UDP traffic. Direct layer-3 tunnels, transport fallback, diagnostics, fleet control, backups, updates, and Telegram monitoring are additional product branches. The main entry point and engine dispatch are evidenced in excerpts; several capability links are documented by the README, while unsampled implementation details are not asserted.

Main entry points: [`main.go`](https://github.com/aminmgmt/backpack/blob/main/main.go) (Process entry), [`internal/client/client.go`](https://github.com/aminmgmt/backpack/blob/main/internal/client/client.go) (Client engine), [`internal/server/server.go`](https://github.com/aminmgmt/backpack/blob/main/internal/server/server.go) (Server engine), [`internal/server/transport`](https://github.com/aminmgmt/backpack/tree/main/internal/server/transport) (Server transports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Operator entry points"]
  node_main["Process entry<br/>[main.go]"]
  node_cli["Interactive CLI<br/>[cli.go]"]
  node_menu["Management menus<br/>[menu.go]"]
  node_config["Tunnel configuration<br/>[config.go]"]
end

subgraph group_tunnel["Tunnel runtime"]
  node_client["Client engine<br/>[client.go]"]
  node_server["Server engine<br/>[server.go]"]
  node_clienttrans["Client transports"]
  node_servertrans["Server transports"]
  node_chain["Fallback chain<br/>[chain.go]"]
  node_forward["Traffic forwarding<br/>[tcp_handler.go]"]
  node_direct["Direct L3 tunnel<br/>[tunnel.go]"]
end

subgraph group_operations["Operations and fleet"]
  node_health["Health diagnostics<br/>[health.go]"]
  node_backup["Backup and restore<br/>[backup.go]"]
  node_updates["Verified updates<br/>[update.go]"]
  node_fleet["Fleet management<br/>[fleet.go]"]
  node_nodes["Managed nodes<br/>[runner.go]"]
  node_metrics["Runtime metrics<br/>[metrics.go]"]
end

subgraph group_interfaces["Monitoring interfaces"]
  node_webserver["Web panel server<br/>[server.go]"]
  node_panel["Panel interface<br/>[main.js]"]
  node_panelapi["Panel API client<br/>[api.js]"]
  node_telegram["Telegram monitoring<br/>[telegram.go]"]
end

node_operator(("Operator"))

node_operator -->|"starts"| node_main
node_main -->|"dispatches"| node_cli
node_main -->|"opens"| node_menu
node_main -.->|"runs configured engine"| node_client
node_main -.->|"runs configured engine"| node_server
node_cli -.->|"configures"| node_config
node_menu -.->|"configures"| node_config
node_client -->|"runs fallback"| node_chain
node_server -->|"runs fallback"| node_chain
node_client -->|"starts transport"| node_clienttrans
node_server -->|"starts transport"| node_servertrans
node_servertrans -.->|"forwards traffic"| node_forward
node_client -.->|"supports direct mode"| node_direct
node_server -.->|"supports direct mode"| node_direct
node_operator -.->|"manages tunnels"| node_panel
node_panel -->|"requests data"| node_panelapi
node_panelapi -->|"calls API"| node_webserver
node_webserver -->|"serves fleet operations"| node_fleet
node_webserver -->|"routes node operations"| node_nodes
node_operator -.->|"runs diagnostics"| node_health
node_operator -.->|"backs up state"| node_backup
node_operator -.->|"applies updates"| node_updates
node_telegram -->|"reads monitoring data"| node_metrics
node_clienttrans -.->|"reports tunnel metrics"| node_metrics
node_servertrans -.->|"reports tunnel metrics"| node_metrics

click node_main "https://github.com/aminmgmt/backpack/blob/main/main.go"
click node_cli "https://github.com/aminmgmt/backpack/blob/main/internal/cli/cli.go"
click node_menu "https://github.com/aminmgmt/backpack/blob/main/internal/menu/menu.go"
click node_config "https://github.com/aminmgmt/backpack/blob/main/config/config.go"
click node_client "https://github.com/aminmgmt/backpack/blob/main/internal/client/client.go"
click node_server "https://github.com/aminmgmt/backpack/blob/main/internal/server/server.go"
click node_clienttrans "https://github.com/aminmgmt/backpack/tree/main/internal/client/transport"
click node_servertrans "https://github.com/aminmgmt/backpack/tree/main/internal/server/transport"
click node_chain "https://github.com/aminmgmt/backpack/blob/main/internal/tunnel/chain/chain.go"
click node_forward "https://github.com/aminmgmt/backpack/blob/main/internal/utils/handlers/tcp_handler.go"
click node_direct "https://github.com/aminmgmt/backpack/blob/main/internal/tunnel/l3/tunnel.go"
click node_webserver "https://github.com/aminmgmt/backpack/blob/main/internal/webui/server.go"
click node_panel "https://github.com/aminmgmt/backpack/blob/main/internal/webui/panel/js/main.js"
click node_panelapi "https://github.com/aminmgmt/backpack/blob/main/internal/webui/panel/js/api.js"
click node_health "https://github.com/aminmgmt/backpack/blob/main/internal/manage/health/health.go"
click node_backup "https://github.com/aminmgmt/backpack/blob/main/internal/manage/backup/backup.go"
click node_updates "https://github.com/aminmgmt/backpack/blob/main/internal/manage/update.go"
click node_fleet "https://github.com/aminmgmt/backpack/blob/main/internal/control/fleet.go"
click node_nodes "https://github.com/aminmgmt/backpack/blob/main/internal/node/runner.go"
click node_telegram "https://github.com/aminmgmt/backpack/blob/main/internal/telegram/telegram.go"
click node_metrics "https://github.com/aminmgmt/backpack/blob/main/internal/metrics/metrics.go"

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_main,node_cli,node_menu,node_config toneBlue
class node_client,node_server,node_clienttrans,node_servertrans,node_chain,node_forward,node_direct toneAmber
class node_health,node_backup,node_updates,node_fleet,node_nodes,node_metrics toneMint
class node_webserver,node_panel,node_panelapi,node_telegram toneRose
class node_operator toneIndigo
```

## Components

### Operator entry points

- [Process entry](https://github.com/aminmgmt/backpack/blob/main/main.go): `main.go`
- [Interactive CLI](https://github.com/aminmgmt/backpack/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [Management menus](https://github.com/aminmgmt/backpack/blob/main/internal/menu/menu.go): `internal/menu/menu.go`
- [Tunnel configuration](https://github.com/aminmgmt/backpack/blob/main/config/config.go): `config/config.go`

### Tunnel runtime

- [Client engine](https://github.com/aminmgmt/backpack/blob/main/internal/client/client.go): `internal/client/client.go`
- [Server engine](https://github.com/aminmgmt/backpack/blob/main/internal/server/server.go): `internal/server/server.go`
- [Client transports](https://github.com/aminmgmt/backpack/tree/main/internal/client/transport): `internal/client/transport`
- [Server transports](https://github.com/aminmgmt/backpack/tree/main/internal/server/transport): `internal/server/transport`
- [Fallback chain](https://github.com/aminmgmt/backpack/blob/main/internal/tunnel/chain/chain.go): `internal/tunnel/chain/chain.go`
- [Traffic forwarding](https://github.com/aminmgmt/backpack/blob/main/internal/utils/handlers/tcp_handler.go): `internal/utils/handlers/tcp_handler.go`
- [Direct L3 tunnel](https://github.com/aminmgmt/backpack/blob/main/internal/tunnel/l3/tunnel.go): `internal/tunnel/l3/tunnel.go`

### Operations and fleet

- [Health diagnostics](https://github.com/aminmgmt/backpack/blob/main/internal/manage/health/health.go): `internal/manage/health/health.go`
- [Backup and restore](https://github.com/aminmgmt/backpack/blob/main/internal/manage/backup/backup.go): `internal/manage/backup/backup.go`
- [Verified updates](https://github.com/aminmgmt/backpack/blob/main/internal/manage/update.go): `internal/manage/update.go`
- [Fleet management](https://github.com/aminmgmt/backpack/blob/main/internal/control/fleet.go): `internal/control/fleet.go`
- [Managed nodes](https://github.com/aminmgmt/backpack/blob/main/internal/node/runner.go): `internal/node/runner.go`
- [Runtime metrics](https://github.com/aminmgmt/backpack/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`

### Monitoring interfaces

- [Web panel server](https://github.com/aminmgmt/backpack/blob/main/internal/webui/server.go): `internal/webui/server.go`
- [Panel interface](https://github.com/aminmgmt/backpack/blob/main/internal/webui/panel/js/main.js): `internal/webui/panel/js/main.js`
- [Panel API client](https://github.com/aminmgmt/backpack/blob/main/internal/webui/panel/js/api.js): `internal/webui/panel/js/api.js`
- [Telegram monitoring](https://github.com/aminmgmt/backpack/blob/main/internal/telegram/telegram.go): `internal/telegram/telegram.go`

### Other components

- **Operator**

## Connections

- Operator → Process entry: starts (evidence: `main.go`)
- Process entry → Interactive CLI: dispatches (evidence: `main.go`)
- Process entry → Management menus: opens (evidence: `main.go`)
- Process entry → Client engine: runs configured engine
- Process entry → Server engine: runs configured engine
- Interactive CLI → Tunnel configuration: configures
- Management menus → Tunnel configuration: configures
- Client engine → Fallback chain: runs fallback (evidence: `internal/client/client.go`)
- Server engine → Fallback chain: runs fallback (evidence: `internal/server/server.go`)
- Client engine → Client transports: starts transport (evidence: `internal/client/client.go`)
- Server engine → Server transports: starts transport (evidence: `internal/server/server.go`)
- Server transports → Traffic forwarding: forwards traffic
- Client engine → Direct L3 tunnel: supports direct mode
- Server engine → Direct L3 tunnel: supports direct mode
- Operator → Panel interface: manages tunnels (evidence: `README.md`)
- Panel interface → Panel API client: requests data (evidence: `internal/webui/panel/js/main.js`)
- Panel API client → Web panel server: calls API (evidence: `internal/webui/panel/js/api.js`)
- Web panel server → Fleet management: serves fleet operations (evidence: `internal/webui/server.go`)
- Web panel server → Managed nodes: routes node operations
- Operator → Health diagnostics: runs diagnostics (evidence: `README.md`)
- Operator → Backup and restore: backs up state (evidence: `README.md`)
- Operator → Verified updates: applies updates (evidence: `README.md`)
- Telegram monitoring → Runtime metrics: reads monitoring data (evidence: `internal/telegram/telegram.go`)
- Client transports → Runtime metrics: reports tunnel metrics
- Server transports → Runtime metrics: reports tunnel metrics
