Core Services and Configuration

Core Services and Configuration

The src/pclink/core/ directory contains the essential, non-web-facing components that form the foundation of the PCLink server. These modules handle the application's lifecycle, configuration, state, and platform-specific integrations.

controller.py - The Application Orchestrator

The Controller class is the central coordinator of the application. It acts as the bridge between the UI (like the system tray) and the server's backend services.

• Server Lifecycle: It is responsible for starting, stopping, and restarting the Uvicorn web server in a separate thread.
• Secure Mode Activation: A key responsibility is to manage the server's state. The mobile API and discovery service remain disabled until the Web UI setup is complete. The activate_secure_mode method is called after a password is set, which enables these features.
• Service Management: It initializes and controls other core services, such as the DiscoveryService.
• Event Handling: It handles events triggered by the user, such as changing settings or regenerating an API key, and ensures the server restarts if necessary.

config.py - Configuration Management

The ConfigManager class provides a simple and persistent way to manage user-configurable settings.

• Storage: All settings are stored in a human-readable config.json file located in the user's platform-specific application data directory.
• Defaults: It manages a set of default values, ensuring the application can run correctly even if the configuration file is missing or corrupted.
• Key Settings: Manages important configurations such as:
  • server_port: The port the HTTPS server listens on.
  • auto_start: Whether the application should launch on system startup.
  • allow_insecure_shell: A security flag to determine if the terminal can be accessed over unencrypted connections.

device_manager.py - Device Persistence

The DeviceManager is responsible for handling all aspects of paired mobile devices.

• Database: It uses an SQLite database (devices.db) to persistently store information about every device that has been paired.
• Device Lifecycle: It manages the entire lifecycle of a device:
  1. Registration: A new device is first registered with a unique ID and name, but it is not yet approved.
  2. Approval: After the user approves the pairing request via the Web UI, the device is marked as approved.
  3. Authentication: The manager assigns a unique API key to each device, which is used for all subsequent requests.
  4. Revocation: The user can revoke access for any device, permanently deleting it from the database.

Other Important Core Modules

• state.py: A lightweight module for holding global, in-memory application state, such as the list of currently connected devices.
• system_tray.py: Implements the cross-platform system tray icon and its context menu, allowing for background operation and easy access to key functions like opening the Web UI or shutting down the server.
• singleton.py: A crucial utility that prevents more than one instance of PCLink from running at the same time by using a system-wide lock (a named mutex on Windows and a file lock on Linux/macOS).
• web_auth.py: Manages the entire security model for the Web UI. It handles password hashing (using PBKDF2 with a salt), session token generation, and validation. It is the gatekeeper that determines if the initial setup has been completed.```