Skip to content

Quick Reference

Jump to bottom
Azhar Zouhir edited this page Dec 4, 2025 · 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 REST API
│   ├── api.py                          # Main routes & auth
│   ├── discovery.py                    # Device pairing
│   ├── file_browser.py                 # File operations
│   ├── process_manager.py              # Process control
│   ├── applications_router.py          # App discovery & launch
│   ├── macro_router.py                 # Macro execution
│   └── terminal.py                     # Shell access
├── core/                               # Business logic
│   ├── controller.py                   # Main orchestrator
│   ├── state.py                        # Global state management
│   ├── device_manager.py               # Connection tracking
│   ├── constants.py                    # App configuration
│   ├── system_tray.py                  # System tray integration
│   └── utils.py, etc.                  # Utilities
├── web_ui/                             # Web interface
│   ├── router.py                       # Web UI router
│   └── static/                         # HTML, CSS, JS files
└── assets/                             # Icons & resources

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

# 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

# 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
  • terminal.py → WebSocket terminal access

Authentication

  • API key-based authentication (UUID)
  • Stored in device database
  • Required in X-API-Key header for all 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
  • api_key.txt → Main API key

Default Settings

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

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