Skip to content

Quick Reference

Jump to bottom
Azhar Zouhir edited this page Jun 11, 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
├── api_server/                          # FastAPI Web Server
│   ├── api.py                          # App factory & assembly
│   ├── middleware.py                   # Auth & Security layers
│   ├── ws_manager.py                   # WebSocket orchestration
│   └── routers/                        # Modular API endpoints
│       ├── auth.py, pairing.py         # Connection & Auth
│       ├── file_browser.py, info.py    # Core features
│       ├── system.py, processes.py     # System control
│       └── desktop_streaming.py, etc.  # Advanced features
├── services/                           # Business Logic Layer
│   ├── discovery_service.py            # Local network discovery
│   ├── transfer_service.py             # File upload/download logic
│   ├── input_service.py                # Hardware abstractions
│   └── desktop_streaming_service.py    # Screen capture engine
├── core/                               # System Core
│   ├── server_controller.py            # Lifecycle orchestrator
│   ├── startup.py                      # Boot persistence
│   ├── state.py                        # Shared memory state
│   ├── device_manager.py               # SQL persistence
│   └── config.py, constants.py         # App configuration
└── web_ui/                             # Built-in Web Dashboard
    ├── router.py                       # Page routing
    ├── templates/                      # Jinja2 HTML templates
    └── static/                         # Modular JS & CSS assets

Key Components

Application Modes

  • Web Mode (Default) → Web-based interface served at https://localhost:38080
  • Background Mode → Server runs as a background process with system tray integration
  • System Tray → Cross-platform tray integration for quick access

Core Flow

  1. Entry Point → main.py starts the application
  2. Lifecycle → server_controller.py orchestrates server & services
  3. API Server → FastAPI handles mobile app and Web UI requests
  4. State → state.py manages devices and connections
  5. Web UI → Dynamic pages rendered via Jinja2 and modular JS

Essential Files

  • main.py → Startup and mode selection
  • server_controller.py → Central lifecycle coordinator
  • startup.py → Boot persistence manager
  • api.py → REST API and authentication assembly
  • 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

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

Development

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

# Install pre-commit hooks
pre-commit install

# Run tests
pytest
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 4.3.0

Architecture Patterns

Modular Architecture (Cortex)

  • Model → state.py (application state)
  • View → web_ui/ (Jinja2 templates & modular JS)
  • Controller → services/ (business logic) & routers/ (API handling)

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
  • Extension loading via extension_manager.py

API Structure

Main Routers

  • api.py → Core API, WebSockets, pairing
  • system.py → Power commands, volume control
  • info.py → System information (CPU, RAM, disk)
  • input.py → Keyboard and mouse input
  • media.py → Media playback control
  • file_browser.py → File system operations & secure sharing
  • processes.py → Process management
  • extensions.py → Extension management
  • terminal.py → WebSocket terminal access
  • desktop_streaming.py → Real-time screen preview

Authentication

  • Per-Device Token-Auth (UUID)
  • Managed via middleware.py and device_manager.py
  • Required in X-API-Key header for all 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, global service toggles)
  • 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

ServerController (core/server_controller.py)

Central orchestrator managing:

  • Server lifecycle (start/stop/restart)
  • Coordination with system tray
  • API server initialization

StartupManager (core/startup.py)

Handles boot persistence:

  • OS-specific auto-start registration
  • Pre-flight environment setup

DeviceManager (core/device_manager.py)

Device lifecycle management:

  • Registration and approval
  • API key generation
  • Hardware ID banning
  • Device revocation

ConfigManager (core/config.py)

Configuration persistence:

  • Load/save settings
  • Default values
  • Global service kill-switches

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