# bytedz/pclink architecture

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

- Interactive diagram: https://gitdiagram.com/bytedz/pclink
- Repository: https://github.com/bytedz/pclink

## Overview

PCLink is a web-first remote PC management server with a companion mobile client. Users connect through the browser or app, authenticate and pair a device for approval, then use permission-scoped APIs to control and inspect the host. Its major capabilities include peripheral and media control, file/process exploration, terminal access, screen streaming, and extensions. The graph reflects README capabilities and the sampled entry-point, controller, WebSocket, device, and UI code; unsampled route-to-service wiring is omitted where uncertain.

Main entry points: [`src/pclink/api_server/routers/websocket_routes.py`](https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/routers/websocket_routes.py) (WebSocket routes), [`src/pclink/api_server/routers`](https://github.com/bytedz/pclink/tree/main/src/pclink/api_server/routers) (Management routes), [`src/pclink/api_server/api.py`](https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/api.py) (FastAPI server), [`src/pclink/web_ui/router.py`](https://github.com/bytedz/pclink/blob/main/src/pclink/web_ui/router.py) (Web UI router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Clients and server"]
  node_main["Application startup<br/>[main.py]"]
  node_controller["Server controller"]
  node_api["FastAPI server<br/>[api.py]"]
  node_webui["Web UI router<br/>[router.py]"]
end

subgraph group_security["Identity and access"]
  node_auth["Web authentication<br/>[web_auth.py]"]
  node_middleware["API middleware<br/>[middleware.py]"]
  node_pairing["Pairing routes<br/>[pairing.py]"]
  node_devices[("Device manager<br/>[device_manager.py]")]
end

subgraph group_control["Remote management"]
  node_routes["Management routes"]
  node_websocket["WebSocket routes"]
  node_wsmanager["Connection manager<br/>[ws_manager.py]"]
end

subgraph group_platform["Host capabilities"]
  node_input["Peripheral input<br/>[input_service.py]"]
  node_system["System information<br/>[system_service.py]"]
  node_files["Files and transfers<br/>[file_service.py]"]
  node_terminal["Remote terminal"]
  node_media["Media control<br/>[media_service.py]"]
end

subgraph group_extensions["Streaming and extensions"]
  node_stream["Desktop streaming"]
  node_extension["Extension manager"]
end

node_browser(("Web browser"))
node_mobile(("Mobile app"))
node_host(("Managed PC"))

node_browser -->|"opens UI"| node_webui
node_webui -->|"validates session"| node_auth
node_browser -->|"uses HTTPS API"| node_api
node_mobile -->|"connects"| node_api
node_api -->|"checks requests"| node_middleware
node_api -->|"serves UI"| node_webui
node_mobile -->|"requests pairing"| node_pairing
node_pairing -->|"registers device"| node_devices
node_browser -->|"manages PC"| node_routes
node_routes -->|"checks device access"| node_devices
node_websocket -->|"checks permissions"| node_devices
node_websocket -->|"manages connections"| node_wsmanager
node_websocket -->|"dispatches input"| node_input
node_websocket -->|"dispatches controls"| node_media
node_websocket -->|"reads telemetry"| node_system
node_websocket -->|"requests keyframes"| node_stream
node_routes -->|"handles file operations"| node_files
node_routes -->|"handles shell access"| node_terminal
node_routes -->|"handles system queries"| node_system
node_routes -->|"manages extensions"| node_extension
node_main -->|"starts"| node_controller
node_controller -->|"runs server"| node_api
node_input -->|"controls peripherals"| node_host
node_system -->|"reads host state"| node_host
node_files -->|"browses files"| node_host
node_terminal -->|"runs commands"| node_host
node_media -->|"controls playback"| node_host
node_stream -->|"captures display"| node_host
node_extension -.->|"extends capabilities"| node_host

click node_main "https://github.com/bytedz/pclink/blob/main/src/pclink/main.py"
click node_controller "https://github.com/bytedz/pclink/blob/main/src/pclink/core/server_controller.py"
click node_api "https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/api.py"
click node_webui "https://github.com/bytedz/pclink/blob/main/src/pclink/web_ui/router.py"
click node_auth "https://github.com/bytedz/pclink/blob/main/src/pclink/core/web_auth.py"
click node_middleware "https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/middleware.py"
click node_pairing "https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/routers/pairing.py"
click node_devices "https://github.com/bytedz/pclink/blob/main/src/pclink/core/device_manager.py"
click node_routes "https://github.com/bytedz/pclink/tree/main/src/pclink/api_server/routers"
click node_websocket "https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/routers/websocket_routes.py"
click node_wsmanager "https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/ws_manager.py"
click node_input "https://github.com/bytedz/pclink/blob/main/src/pclink/services/input_service.py"
click node_system "https://github.com/bytedz/pclink/blob/main/src/pclink/services/system_service.py"
click node_files "https://github.com/bytedz/pclink/blob/main/src/pclink/services/file_service.py"
click node_terminal "https://github.com/bytedz/pclink/blob/main/src/pclink/services/terminal_service.py"
click node_media "https://github.com/bytedz/pclink/blob/main/src/pclink/services/media_service.py"
click node_stream "https://github.com/bytedz/pclink/blob/main/src/pclink/services/desktop_streaming_service.py"
click node_extension "https://github.com/bytedz/pclink/blob/main/src/pclink/core/extension_manager.py"

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_controller,node_api,node_webui,node_browser toneBlue
class node_auth,node_middleware,node_pairing,node_devices toneAmber
class node_routes,node_websocket,node_wsmanager toneMint
class node_input,node_system,node_files,node_terminal,node_media toneRose
class node_stream,node_extension,node_mobile,node_host toneIndigo
```

## Components

### Clients and server

- [Application startup](https://github.com/bytedz/pclink/blob/main/src/pclink/main.py): `src/pclink/main.py`
- [Server controller](https://github.com/bytedz/pclink/blob/main/src/pclink/core/server_controller.py): `src/pclink/core/server_controller.py`
- [FastAPI server](https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/api.py): `src/pclink/api_server/api.py`
- [Web UI router](https://github.com/bytedz/pclink/blob/main/src/pclink/web_ui/router.py): `src/pclink/web_ui/router.py`

### Identity and access

- [Web authentication](https://github.com/bytedz/pclink/blob/main/src/pclink/core/web_auth.py): `src/pclink/core/web_auth.py`
- [API middleware](https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/middleware.py): `src/pclink/api_server/middleware.py`
- [Pairing routes](https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/routers/pairing.py): `src/pclink/api_server/routers/pairing.py`
- [Device manager](https://github.com/bytedz/pclink/blob/main/src/pclink/core/device_manager.py): `src/pclink/core/device_manager.py`

### Remote management

- [Management routes](https://github.com/bytedz/pclink/tree/main/src/pclink/api_server/routers): `src/pclink/api_server/routers`
- [WebSocket routes](https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/routers/websocket_routes.py): `src/pclink/api_server/routers/websocket_routes.py`
- [Connection manager](https://github.com/bytedz/pclink/blob/main/src/pclink/api_server/ws_manager.py): `src/pclink/api_server/ws_manager.py`

### Host capabilities

- [Peripheral input](https://github.com/bytedz/pclink/blob/main/src/pclink/services/input_service.py): `src/pclink/services/input_service.py`
- [System information](https://github.com/bytedz/pclink/blob/main/src/pclink/services/system_service.py): `src/pclink/services/system_service.py`
- [Files and transfers](https://github.com/bytedz/pclink/blob/main/src/pclink/services/file_service.py): `src/pclink/services/file_service.py`
- [Remote terminal](https://github.com/bytedz/pclink/blob/main/src/pclink/services/terminal_service.py): `src/pclink/services/terminal_service.py`
- [Media control](https://github.com/bytedz/pclink/blob/main/src/pclink/services/media_service.py): `src/pclink/services/media_service.py`

### Streaming and extensions

- [Desktop streaming](https://github.com/bytedz/pclink/blob/main/src/pclink/services/desktop_streaming_service.py): `src/pclink/services/desktop_streaming_service.py`
- [Extension manager](https://github.com/bytedz/pclink/blob/main/src/pclink/core/extension_manager.py): `src/pclink/core/extension_manager.py`

### Other components

- **Web browser**
- **Mobile app**
- **Managed PC**

## Connections

- Web browser → Web UI router: opens UI
- Web UI router → Web authentication: validates session
- Web browser → FastAPI server: uses HTTPS API
- Mobile app → FastAPI server: connects
- FastAPI server → API middleware: checks requests
- FastAPI server → Web UI router: serves UI
- Mobile app → Pairing routes: requests pairing
- Pairing routes → Device manager: registers device
- Web browser → Management routes: manages PC
- Management routes → Device manager: checks device access
- WebSocket routes → Device manager: checks permissions
- WebSocket routes → Connection manager: manages connections
- WebSocket routes → Peripheral input: dispatches input
- WebSocket routes → Media control: dispatches controls
- WebSocket routes → System information: reads telemetry
- WebSocket routes → Desktop streaming: requests keyframes
- Management routes → Files and transfers: handles file operations
- Management routes → Remote terminal: handles shell access
- Management routes → System information: handles system queries
- Management routes → Extension manager: manages extensions
- Application startup → Server controller: starts
- Server controller → FastAPI server: runs server
- Peripheral input → Managed PC: controls peripherals
- System information → Managed PC: reads host state
- Files and transfers → Managed PC: browses files
- Remote terminal → Managed PC: runs commands
- Media control → Managed PC: controls playback
- Desktop streaming → Managed PC: captures display
- Extension manager → Managed PC: extends capabilities