Skip to content

Quick Reference

Jump to bottom
Azhar Zouhir edited this page Mar 22, 2026 · 6 revisions

Quick Reference

A quick reference guide for PCLink developers and contributors.

Project Structure

src/pclink/ ├── main.py, main.py, launcher.py # Entry points ├── headless.py # Headless/background mode ├── api_server/ # FastAPI Web Server │ ├── api.py # App factory & assembly │ ├── middleware.py # Auth & Security layers │ ├── ws_manager.py # WebSocket orchestration │ └── routers/ # Modular API endpoints │ ├── pairing.py, devices.py # Connection & Auth │ ├── file_browser.py, info.py # Core features │ └── terminal.py, macro.py # Advanced features ├── services/ # Business Logic Layer │ ├── discovery_service.py # Local network discovery │ ├── transfer_service.py # File upload/download logic │ └── input_service.py, etc. # Hardware abstractions ├── core/ # System Core │ ├── controller.py # Main orchestrator │ ├── state.py # Shared memory state │ ├── device_manager.py # SQL persistence │ └── config.py, constants.py # App configuration └── web_ui/ # Built-in Web Dashboard ├── router.py # Static file serving └── static/ # Frontend assets (Tailwind/JS)


## Key Components

### Application Modes

- **Web Mode (Default)** → Web-based interface served at `https://localhost:38080`
- **Headless Mode** → Background server with `HeadlessApp` and system tray
- **System Tray** → Cross-platform tray integration for quick access

### Core Flow

1. **Entry Point** → `main.py` starts the application
2. **Controller** → `controller.py` orchestrates server & services
3. **API Server** → FastAPI handles mobile app requests
4. **State** → `state.py` manages devices and connections
5. **Web UI** → Real-time updates via WebSocket connections

### Essential Files

- `main.py` → Startup and mode selection
- `headless.py` → Headless application manager
- `controller.py` → Central coordinator
- `api.py` → REST API and authentication
- `state.py` → Thread-safe device state management
- `system_tray.py` → System tray integration

## Common Commands

### Running the Application

```bash
# Run as a module (recommended)
python -m pclink

# Direct execution
python src/pclink/main.py

# Headless/background mode
python -m pclink --startup

# Using convenience script
python run_pclink.py

Development

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest
pytest tests/unit/
pytest tests/integration/
pytest --cov=src

# Code formatting
black src tests
isort src tests

# Run all pre-commit checks
pre-commit run --all-files

# Type checking
mypy src

Building

# Portable archive (one-dir build)
python scripts/build.py --format portable

# Single executable file
python scripts/build.py --format onefile

# Windows installer
python scripts/build.py --format installer

# Linux packages (.deb and .rpm)
python scripts/build.py --format nfpm

# Install Fedora RPM
sudo dnf install ./pclink-*.rpm

# Python wheel distribution
python scripts/build.py --format wheel

# Debug build with console output
python scripts/build.py --debug

# Clean build artifacts first
python scripts/build.py --clean

# Create release
python scripts/release.py --version 1.2.0

Architecture Patterns

MVC Pattern

  • Model → state.py (application state)
  • View → web_ui/ (web interface)
  • Controller → controller.py (business logic)

Singleton Pattern

  • Ensures only one PCLink instance runs system-wide
  • Implemented in core/singleton.py
  • Uses mutex (Windows) or file lock (Linux/macOS)

Observer Pattern

  • WebSocket connections for real-time updates
  • State changes broadcast to connected clients
  • Device connections trigger notifications

Factory Pattern

  • Dynamic API router creation
  • Dialog creation based on context

API Structure

Main Routers

  • api.py → Core API, WebSockets, pairing
  • system_router.py → Power commands, volume control
  • info_router.py → System information (CPU, RAM, disk)
  • input_router.py → Keyboard and mouse input
  • media_router.py → Media playback control
  • utils_router.py → Clipboard, screenshots
  • file_browser.py → File system operations
  • process_manager.py → Process management
  • extension_router.py → Extension management
  • terminal.py → WebSocket terminal access

Authentication

  • Per-Device Token-Auth (UUID)
  • Managed via middleware.py and devices.py
  • Required in X-API-Key header for and REST requests

Security

  • HTTPS only (self-signed certificates)
  • Certificate generation on first run
  • Secure device pairing with approval flow

Configuration

Configuration Files

Located in platform-specific app data directory:

  • config.json → Server settings (port, auto-start, etc.)
  • devices.db → SQLite database of paired devices
  • cert.pem / key.pem → SSL certificates

Default Settings

  • Port: 38080 (HTTPS)
  • Auto-start: Disabled by default
  • Discovery: Enabled after setup

Key Classes

Controller (core/controller.py)

Central orchestrator managing:

  • Server lifecycle (start/stop/restart)
  • Device connections
  • Discovery service
  • Configuration changes

State (core/state.py)

Thread-safe state management:

  • Connected devices list
  • Server status
  • Real-time updates via WebSocket

DeviceManager (core/device_manager.py)

Device lifecycle management:

  • Registration and approval
  • API key generation
  • Connection tracking
  • Device revocation

ConfigManager (core/config.py)

Configuration persistence:

  • Load/save settings
  • Default values
  • Platform-specific paths

Useful Links

Tips

Debugging

  • Use --debug flag when building for console output
  • Check logs in app data directory (pclink.log)
  • Use browser DevTools for Web UI debugging
  • Enable verbose logging in core/logging.py

Testing

  • Write tests for new features
  • Test on multiple platforms
  • Use pytest fixtures for common setup
  • Mock external dependencies

Performance

  • Profile with cProfile for bottlenecks
  • Use async/await for I/O operations
  • Minimize WebSocket message frequency
  • Cache expensive computations

Security

  • Never commit API keys or certificates
  • Validate all user input
  • Use parameterized SQL queries
  • Keep dependencies updated

Clone this wiki locally