# playit-cloud/playit-agent architecture

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

- Interactive diagram: https://gitdiagram.com/playit-cloud/playit-agent
- Repository: https://github.com/playit-cloud/playit-agent

## Overview

playit is a game-server tunneling agent, delivered as a background service with a CLI and Windows tray companion. The main operational path is CLI or tray interaction over IPC to the daemon, which manages the agent; the agent maintains control-plane connectivity and forwards TCP/UDP traffic to configured local origins. The README confirms the program’s installable, runnable role, while source-index references support several internal links. Some daemon-to-agent and tray-to-service wiring was not shown, so those links are marked unverified rather than asserted.

Main entry points: [`packages/agent_core/src/playit_agent.rs`](https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/playit_agent.rs) (Agent runtime), [`packages/playit-cli/src/main.rs`](https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/main.rs) (CLI commands), [`packages/playit-ipc/src/ipc.rs`](https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-ipc/src/ipc.rs) (IPC client), [`packages/playitd/src/daemon.rs`](https://github.com/playit-cloud/playit-agent/blob/master/packages/playitd/src/daemon.rs) (Daemon lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_cli_ops["Service operations<br/>[client.rs]"]
  node_cli_service["Service startup<br/>[service.rs]"]
  node_terminal_ui["Terminal UI<br/>[mod.rs]"]
  node_tui["Status TUI<br/>[tui_app.rs]"]
  node_tray["Windows tray<br/>[frontend.rs]"]
end

subgraph group_service["Service and IPC"]
  node_daemon["Daemon lifecycle<br/>[daemon.rs]"]
  node_ipc_server["IPC server<br/>[ipc_server.rs]"]
  node_ipc_client["IPC client<br/>[ipc.rs]"]
  node_ipc_model["IPC messages<br/>[model.rs]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_runtime["Agent runtime<br/>[playit_agent.rs]"]
  node_control_state["Control lifecycle"]
  node_address_selection["Control address selection"]
  node_tcp_forwarding["TCP forwarding<br/>[tcp_clients.rs]"]
  node_udp_forwarding["UDP forwarding<br/>[udp_clients.rs]"]
  node_origin_lookup["Local origin lookup<br/>[origin_lookup.rs]"]
  node_stats["Tunnel statistics<br/>[stats.rs]"]
end

subgraph group_protocol["Control and networking"]
  node_control_protocol["Control messages"]
  node_control_feed["Control feed<br/>[control_feed.rs]"]
  node_api["Playit API client<br/>[api.rs]"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"dispatches to"| node_cli_ops
node_cli -->|"presents prompts"| node_terminal_ui
node_terminal_ui -->|"uses views"| node_tui
node_cli_ops -->|"sends requests"| node_ipc_client
node_cli -->|"manages service"| node_cli_service
node_cli_service -->|"starts or stops"| node_daemon
node_ipc_client -->|"encodes messages"| node_ipc_model
node_ipc_server -->|"handles messages"| node_ipc_model
node_ipc_client -.->|"exchanges IPC"| node_ipc_server
node_tray -.->|"uses IPC"| node_ipc_client
node_daemon -->|"starts server"| node_ipc_server
node_daemon -.->|"runs agent"| node_agent_runtime
node_agent_runtime -->|"maintains control"| node_control_state
node_control_state -->|"selects addresses"| node_address_selection
node_control_state -.->|"uses messages"| node_control_protocol
node_agent_runtime -->|"runs TCP clients"| node_tcp_forwarding
node_agent_runtime -->|"runs UDP clients"| node_udp_forwarding
node_agent_runtime -.->|"consumes feed"| node_control_feed
node_tcp_forwarding -.->|"looks up origins"| node_origin_lookup
node_udp_forwarding -->|"looks up origins"| node_origin_lookup
node_tcp_forwarding -->|"updates counters"| node_stats
node_udp_forwarding -->|"updates counters"| node_stats
node_agent_runtime -->|"tracks statistics"| node_stats
node_agent_runtime -.->|"uses API"| node_api

click node_cli "https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/main.rs"
click node_cli_ops "https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/client.rs"
click node_cli_service "https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/service.rs"
click node_terminal_ui "https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/ui/mod.rs"
click node_tui "https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/ui/tui_app.rs"
click node_tray "https://github.com/playit-cloud/playit-agent/blob/master/packages/playitd-tray/src/windows/frontend.rs"
click node_daemon "https://github.com/playit-cloud/playit-agent/blob/master/packages/playitd/src/daemon.rs"
click node_ipc_server "https://github.com/playit-cloud/playit-agent/blob/master/packages/playitd/src/ipc_server.rs"
click node_ipc_client "https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-ipc/src/ipc.rs"
click node_ipc_model "https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-ipc/src/model.rs"
click node_agent_runtime "https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/playit_agent.rs"
click node_control_state "https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/agent_control/maintained_control.rs"
click node_address_selection "https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/agent_control/address_selector.rs"
click node_tcp_forwarding "https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/network/tcp/tcp_clients.rs"
click node_udp_forwarding "https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/network/udp/udp_clients.rs"
click node_origin_lookup "https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/network/origin_lookup.rs"
click node_control_protocol "https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_proto/src/control_messages.rs"
click node_control_feed "https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_proto/src/control_feed.rs"
click node_api "https://github.com/playit-cloud/playit-agent/blob/master/packages/api_client/src/api.rs"
click node_stats "https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/stats.rs"

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_ops,node_cli_service,node_terminal_ui,node_tui,node_tray toneBlue
class node_daemon,node_ipc_server,node_ipc_client,node_ipc_model toneAmber
class node_agent_runtime,node_control_state,node_address_selection,node_tcp_forwarding,node_udp_forwarding,node_origin_lookup,node_stats toneMint
class node_control_protocol,node_control_feed,node_api toneRose
class node_operator toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/main.rs): `packages/playit-cli/src/main.rs`
- [Service operations](https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/client.rs): `packages/playit-cli/src/client.rs`
- [Service startup](https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/service.rs): `packages/playit-cli/src/service.rs`
- [Terminal UI](https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/ui/mod.rs): `packages/playit-cli/src/ui/mod.rs`
- [Status TUI](https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-cli/src/ui/tui_app.rs): `packages/playit-cli/src/ui/tui_app.rs`
- [Windows tray](https://github.com/playit-cloud/playit-agent/blob/master/packages/playitd-tray/src/windows/frontend.rs): `packages/playitd-tray/src/windows/frontend.rs`

### Service and IPC

- [Daemon lifecycle](https://github.com/playit-cloud/playit-agent/blob/master/packages/playitd/src/daemon.rs): `packages/playitd/src/daemon.rs`
- [IPC server](https://github.com/playit-cloud/playit-agent/blob/master/packages/playitd/src/ipc_server.rs): `packages/playitd/src/ipc_server.rs`
- [IPC client](https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-ipc/src/ipc.rs): `packages/playit-ipc/src/ipc.rs`
- [IPC messages](https://github.com/playit-cloud/playit-agent/blob/master/packages/playit-ipc/src/model.rs): `packages/playit-ipc/src/model.rs`

### Agent runtime

- [Agent runtime](https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/playit_agent.rs): `packages/agent_core/src/playit_agent.rs`
- [Control lifecycle](https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/agent_control/maintained_control.rs): `packages/agent_core/src/agent_control/maintained_control.rs`
- [Control address selection](https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/agent_control/address_selector.rs): `packages/agent_core/src/agent_control/address_selector.rs`
- [TCP forwarding](https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/network/tcp/tcp_clients.rs): `packages/agent_core/src/network/tcp/tcp_clients.rs`
- [UDP forwarding](https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/network/udp/udp_clients.rs): `packages/agent_core/src/network/udp/udp_clients.rs`
- [Local origin lookup](https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/network/origin_lookup.rs): `packages/agent_core/src/network/origin_lookup.rs`
- [Tunnel statistics](https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_core/src/stats.rs): `packages/agent_core/src/stats.rs`

### Control and networking

- [Control messages](https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_proto/src/control_messages.rs): `packages/agent_proto/src/control_messages.rs`
- [Control feed](https://github.com/playit-cloud/playit-agent/blob/master/packages/agent_proto/src/control_feed.rs): `packages/agent_proto/src/control_feed.rs`
- [Playit API client](https://github.com/playit-cloud/playit-agent/blob/master/packages/api_client/src/api.rs): `packages/api_client/src/api.rs`

### Other components

- **Operator**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Service operations: dispatches to (evidence: `packages/playit-cli/src/main.rs`)
- CLI commands → Terminal UI: presents prompts (evidence: `packages/playit-cli/src/main.rs`)
- Terminal UI → Status TUI: uses views (evidence: `packages/playit-cli/src/ui/mod.rs`)
- Service operations → IPC client: sends requests (evidence: `packages/playit-cli/src/client.rs`)
- CLI commands → Service startup: manages service (evidence: `packages/playit-cli/src/main.rs`)
- Service startup → Daemon lifecycle: starts or stops (evidence: `packages/playit-cli/src/service.rs`)
- IPC client → IPC messages: encodes messages (evidence: `packages/playit-ipc/src/ipc.rs`)
- IPC server → IPC messages: handles messages
- IPC client → IPC server: exchanges IPC
- Windows tray → IPC client: uses IPC
- Daemon lifecycle → IPC server: starts server (evidence: `packages/playitd/src/daemon.rs`)
- Daemon lifecycle → Agent runtime: runs agent
- Agent runtime → Control lifecycle: maintains control (evidence: `packages/agent_core/src/playit_agent.rs`)
- Control lifecycle → Control address selection: selects addresses (evidence: `packages/agent_core/src/agent_control/maintained_control.rs`)
- Control lifecycle → Control messages: uses messages
- Agent runtime → TCP forwarding: runs TCP clients (evidence: `packages/agent_core/src/playit_agent.rs`)
- Agent runtime → UDP forwarding: runs UDP clients (evidence: `packages/agent_core/src/playit_agent.rs`)
- Agent runtime → Control feed: consumes feed
- TCP forwarding → Local origin lookup: looks up origins
- UDP forwarding → Local origin lookup: looks up origins (evidence: `packages/agent_core/src/network/udp/udp_clients.rs`)
- TCP forwarding → Tunnel statistics: updates counters
- UDP forwarding → Tunnel statistics: updates counters (evidence: `packages/agent_core/src/network/udp/udp_clients.rs`)
- Agent runtime → Tunnel statistics: tracks statistics (evidence: `packages/agent_core/src/playit_agent.rs`)
- Agent runtime → Playit API client: uses API
