Skip to content

Architecture and Processes

Jump to bottom
Sparks Skywere edited this page May 14, 2026 · 1 revision

Architecture and Processes

This page explains the project structure, registry and path model, launch flow, and core process management components.

Home

4. Architecture and Project Structure

4.1 Directory Layout

The following describes the complete project directory structure and the purpose of each component:

Servermanager/                      # Project root
├── Start-ServerManager.pyw         # Entry point — starts the application
├── Stop-ServerManager.pyw          # Entry point — stops all components
├── Update-ServerManager.pyw        # GUI tool for database schema updates
├── install.ps1                     # Windows PowerShell installer (3100+ lines)
├── install.sh                      # Linux Bash installer
├── uninstaller.ps1                 # Windows uninstaller
├── uninstaller.sh                  # Linux uninstaller
├── requirements.txt                # Python package dependencies
├── README.md                       # Quick-start readme
│
├── Modules/                        # Core application modules (split by domain)
│   ├── core/                       # Core framework and startup components
│   │   ├── common.py               # Shared utilities, registry access, base classes
│   │   ├── server_logging.py       # Centralised logging management
│   │   ├── launcher.py             # Process launcher and child process manager
│   │   └── timer.py                # Dashboard periodic update timers
│   │
│   ├── server/                     # Server runtime and console components
│   │   ├── server_manager.py       # Core server lifecycle (start/stop/install/update)
│   │   ├── server_console.py       # Real-time interactive server console
│   │   ├── server_operations.py    # Simplified server operations facade
│   │   └── minecraft.py            # Minecraft server management utilities
│   │
│   ├── services/                   # Background service and process-control components
│   │   ├── webserver.py            # Flask web server with REST API
│   │   ├── trayicon.py             # System tray icon (pystray)
│   │   ├── server_automation.py    # MOTD broadcasting and restart warnings
│   │   ├── scheduler.py            # Task scheduling and timer management
│   │   ├── service_wrapper.py      # Windows service wrapper (pywin32)
│   │   └── stop_servermanager.py   # Shutdown utility
│   │
│   ├── updates/                    # Update and Java tooling
│   │   ├── server_updates.py       # Scheduled update checking and execution
│   │   ├── java_configurator.py    # CLI tool for Java version management
│   │   └── auto_app_update.py      # Application self-update helper
│   │
│   ├── ui/                         # UI helpers and dialogs
│   │   ├── automation_ui.py        # Tkinter GUI for automation settings
│   │   ├── documentation.py        # Help and About dialog boxes
│   │   ├── analytics.py            # Real-time analytics and metrics collection
│   │   └── agents.py               # Cluster agent management with GUI
│   │
│   ├── security/                   # Security and identity modules
│   │   ├── security.py             # Core cryptographic security primitives
│   │   ├── web_security.py         # Web application security (rate limit, CSRF, etc.)
│   │   ├── network_security.py     # Network-level access control decorators
│   │   ├── cluster_security.py     # Cluster membership management
│   │   ├── ssl_utils.py            # SSL/TLS certificate generation and management
│   │   └── user_management.py      # User CRUD with 2FA support
│   │
│   ├── network/                    # Network operations
│   │   └── network.py              # Ping, port scan, and firewall helpers
│   │
│   ├── Database/                   # Database modules
│   │   ├── database_utils.py       # Shared DB connection utilities
│   │   ├── SQL_Connection.py       # Unified SQL connection interface
│   │   ├── server_configs_database.py  # Server configurations ORM and manager
│   │   ├── user_database.py        # User database initialisation
│   │   ├── authentication.py       # Authentication backend (SQL + Windows)
│   │   ├── steam_database.py       # Steam apps database setup
│   │   ├── minecraft_database.py   # Minecraft database setup
│   │   ├── cluster_database.py     # Cluster database with 10+ tables
│   │   ├── console_database.py     # Console state persistence
│   │   └── scanners/               # Database population scanners
│   │       ├── AppIDScanner.py     # Steam AppID scanner and DB builder
│   │       └── MinecraftIDScanner.py # Minecraft version scanner
│   │
│   ├── SMNP/                       # Monitoring integrations
│   │   ├── snmp_manager.py         # SNMP monitoring module
│   │   └── graphana.py             # Grafana/Prometheus metrics
│   │
│   └── SMTP/                       # Email subsystem
│       ├── mailserver.py           # SMTP mail server with OAuth 2.0
│       ├── notifications.py        # Email notification templates
│       └── Mail-Templates/         # HTML/text email templates
│           ├── welcome_html.html
│           ├── password_reset_html.html
│           ├── account_locked_html.html
│           ├── server_alert_html.html
│           ├── maintenance_html.html
│           ├── custom_html.html
│           ├── mail-template.css
│           └── (corresponding _subject.txt and _text.txt files)
│
├── Host/                           # Desktop dashboard modules
│   ├── dashboard.py                # Main Tkinter dashboard (~1000 lines)
│   ├── dashboard_functions.py      # Dashboard utility functions (~3700 lines)
│   ├── dashboard_dialogs.py        # Server configuration dialogs
│   ├── dashboard_server_config.py  # Server configuration UI
│   ├── dashboard_server_ops.py     # Server operations UI
│   ├── dashboard_settings.py       # Dashboard settings UI
│   ├── dashboard_ui.py             # UI component builders
│   └── admin_dashboard.py          # Admin dashboard for user/email management
│
├── api/                            # REST API modules
│   └── cluster.py                  # Cluster API Flask Blueprint
│
├── services/                       # Background service modules
│   ├── command_queue.py            # File-based command queue for server stdin
│   ├── stdin_relay.py              # Named pipe stdin relay
│   ├── persistent_stdin.py         # Persistent stdin pipe for subprocesses
│   ├── dashboard_tracker.py        # Dashboard and server process tracker
│   └── service_helper.py           # Windows service management CLI helper
│
├── debug/                          # Diagnostics and debugging
│   ├── debug.py                    # System diagnostics engine
│   └── debug_manager.py            # Debug center GUI
│
├── www/                            # Web interface static files
│   ├── index.html                  # Redirect to login
│   ├── login.html                  # Login page
│   ├── dashboard.html              # Main web dashboard
│   ├── create-server.html          # Server creation wizard
│   ├── admin.html                  # Admin panel
│   ├── cluster.html                # Cluster management page
│   ├── diagnostics.html            # Authentication diagnostics
│   ├── css/                        # Stylesheets
│   │   ├── common.css              # Shared layout styles (header, nav, user menu, themes)
│   │   ├── dashboard.css
│   │   ├── login.css
│   │   ├── normalize.css
│   │   ├── notifications.css
│   │   ├── shared.css
│   │   ├── style.css
│   │   └── theme.css
│   └── js/                         # JavaScript modules
│       ├── api.js                  # API client class
│       ├── auth.js                 # Authentication module
│       ├── dashboard.js            # Dashboard page logic with Chart.js
│       ├── serverControls.js       # Server control functions
│       ├── charts.js               # Chart configuration
│       ├── config.js               # Client configuration
│       ├── theme.js                # Dark/light theme toggle
│       ├── timerange.js            # Time range selector
│       └── utils.js                # Utility functions
│
├── db/                             # Database files (created at install)
├── ssl/                            # SSL certificates
├── icons/                          # Application icons
├── logs/                           # Log file directories
│   ├── components/                 # Per-component log files
│   ├── debug/                      # Debug log files
│   └── services/                   # Service log files
├── temp/                           # Temporary/runtime files
│   ├── launcher.pid                # Launcher process ID file
│   ├── webserver.pid               # Web server process ID file
│   ├── trayicon.pid                # Tray icon process ID file
│   ├── dashboard.pid               # Dashboard process ID file
│   ├── server_automation.pid       # Automation process ID file
│   └── command_queues/             # File-based command queues per server
├── tools/                          # Standalone utility scripts
│   ├── reset_admin_password.py     # Admin password reset utility
│   ├── reset_admin_2FA.py          # Admin 2FA reset utility
│   ├── verify_database.py          # Database verification tool
│   └── verify_dedicated_servers.py # Post-scan server verification
├── docs/                           # Documentation and screenshots
└── WIKI.md                         # This file

4.2 Module Dependency Map

The application follows a layered architecture where modules depend on shared utilities and communicate through well-defined interfaces:

Foundation Layer:

  • Modules/core/server_logging.py — All logging flows through the centralised LogManager singleton. Every module calls get_component_logger() or setup_module_logging() to get a properly configured logger with rotating file handlers.
  • Modules/core/common.py — Provides ServerManagerModule (base class for all major modules), RegistryModule (lightweight base class for registry-backed modules such as SecurityManager and ServerOperations), ServerManagerPaths (registry-based path resolution), ProcessManager (PID file management), ConfigManager (application configuration via database), and numerous utility functions including make_2fa_callbacks() (shared 2FA dialog logic), send_command_to_server() (unified command delivery), and make_canvas_width_updater() (shared UI factory).

Core Layer:

  • Modules/server/server_manager.py — The engine of the application. Handles SteamCMD-based and Minecraft server installations, server start/stop with multiple fallback strategies, and process monitoring.
  • Modules/core/launcher.py — Orchestrates the application startup by launching child processes (tray icon, web server, automation) based on the cluster role.
  • Modules/services/webserver.py — The Flask web server that serves the web interface and exposes the REST API.

Database Layer:

  • Modules/Database/ — All database operations are isolated here. database_utils.py provides shared connection factory functions. Each domain has its own module (server configs, users, steam apps, minecraft, cluster, console states).

UI Layer:

  • Host/dashboard.py + Host/dashboard_functions.py + Host/dashboard_ui.py + Host/dashboard_dialogs.py + Host/dashboard_server_config.py + Host/dashboard_server_ops.py + Host/dashboard_settings.py — The Tkinter desktop dashboard.
  • www/ — The web interface static files served by the Flask web server.

Services Layer:

  • services/ — Background processes and IPC mechanisms for command delivery to server processes.

4.3 Registry Configuration

All installation and runtime configuration is stored in the Windows Registry under:

HKEY_LOCAL_MACHINE\Software\SkywereIndustries\Servermanager

The following values are stored:

Value Name Type Description
Servermanagerdir REG_SZ Absolute path to the Server Manager installation directory
CurrentVersion REG_SZ Installed version number (e.g., "1.2")
UserWorkspace REG_SZ Path to the user workspace directory
InstallDate REG_SZ Date and time of installation
LastUpdate REG_SZ Date and time of last update
ModulePath REG_SZ Path to the Modules directory
LogPath REG_SZ Path to the logs directory
SteamCmdPath REG_SZ Path to the SteamCMD installation
WebPort REG_SZ Web server port number (default: 8080)
HostType REG_SZ Cluster role — either "Host" or "Subhost"
HostAddress REG_SZ (Subhost only) IP address of the Host node
ClusterCreated REG_SZ Whether cluster configuration exists

If the registry keys are not available (e.g., due to permissions or running on Linux), the application falls back to using the script directory as the root path. This fallback is implemented in ServerManagerPaths.initialise_fallback().

5. Starting and Stopping the Application

5.1 Desktop Mode

To start Server Manager in desktop mode, run the Start-ServerManager.pyw script. This script performs the following startup sequence:

  1. Privilege Check — Verifies the process is running with Administrator privileges. If not, it prompts for UAC elevation.
  2. Singleton Check — Reads PID files from the temp/ directory. If another instance of Server Manager is already running (launcher, tray icon, or web server PID exists and the process is alive), it prompts the user about whether to restart.
  3. Orphaned PID Cleanup — Scans all PID files and removes any that reference processes which are no longer running. This handles cases where the application did not shut down cleanly.
  4. Directory Verification — Ensures required directories exist (logs/, temp/, logs/components/, logs/debug/, logs/services/).
  5. Launcher Start — Launches Modules/core/launcher.py using pythonw.exe (windowless Python) with CREATE_NO_WINDOW and DETACHED_PROCESS flags so it runs in the background.

The launcher (Modules/core/launcher.py) then takes over and starts the appropriate child processes based on the cluster role:

  • Host Role: Starts the system tray icon, web server, and server automation process.
  • Subhost Role: Starts the system tray icon and a subhost dashboard process (on port 5002).
  • Unknown Role: Starts the system tray icon and web server.

5.2 Windows Service Mode

Server Manager can run as a Windows service for unattended operation. The service is managed through Modules/services/service_wrapper.py which implements win32serviceutil.ServiceFramework.

Service Details:

  • Service Name: ServerManagerService
  • Display Name: Server Manager Service
  • Startup Type: Automatic (configured during installation)
  • Health Monitoring: The service performs health checks every 30 seconds and will automatically restart failed components.

Installing the Service:

.\install.ps1 -ServiceAction Install

Managing the Service:

.\install.ps1 -ServiceAction Start
.\install.ps1 -ServiceAction Stop
.\install.ps1 -ServiceAction Restart
.\install.ps1 -ServiceAction Status
.\install.ps1 -ServiceAction Uninstall

Alternatively, you can use the services/service_helper.py CLI:

python services/service_helper.py install
python services/service_helper.py start
python services/service_helper.py stop
python services/service_helper.py status
python services/service_helper.py uninstall

Or manage it through standard Windows service management tools (services.msc, sc command, or the PowerShell *-Service cmdlets).

5.3 Shutdown Procedure

To stop Server Manager, run Stop-ServerManager.pyw or use the "Exit" option from the system tray icon menu. The Stop-ServerManager.pyw script launches Modules/services/stop_servermanager.py.

The shutdown utility (ServerManagerStopper) executes a carefully ordered shutdown sequence to prevent data loss and orphaned processes:

  1. Stop All Game Servers — Attempts to gracefully stop all managed game servers using their configured stop commands.
  2. Stop Processes from PID Files — Reads PID files for launcher, web server, tray icon, dashboard, automation, and debug-center processes (including debug.pid). For each: sends terminate(), waits up to 10 seconds, then uses taskkill /F /T (force kill with child processes).
  3. Stop Processes by Name/Path — Scans running processes for Server Manager targets using command line plus executable-path validation to catch missed processes while avoiding false-positive system processes.
  4. Wait and Re-Scan — Waits briefly, then re-scans to ensure all processes have exited.
  5. Final Cleanup Kill — As a last resort, uses taskkill with COMMANDLINE filters to forcefully kill any remaining python.exe or pythonw.exe processes associated with Server Manager.
  6. PID File Removal — Removes all PID files from the temp/ directory.

CLI Arguments:

  • --debug — Enable verbose debug logging during shutdown.
  • --force — Force kill all processes without graceful shutdown attempts.

6. The Launcher and Process Management

The launcher (Modules/core/launcher.py) is the central process orchestrator. It extends ServerManagerModule (inheriting path resolution, config management, and PID file handling) and manages the lifecycle of all child processes.

Key Behaviours:

  • Cluster Role Detection — On startup, the launcher reads the HostType registry value to determine whether this node is a Host, Subhost, or Unknown. For Subhost nodes, it also reads the HostAddress value to know which Host to connect to.

  • Process Launching — Each child process (tray icon, web server, automation) is launched as a separate Python process using subprocess.Popen with CREATE_NO_WINDOW and DETACHED_PROCESS flags. The tray icon uses pythonw.exe (windowless), while other processes use the regular python executable.

  • Port Verification — After launching the web server, the launcher verifies it is actually listening on the configured port. It performs up to 15 retry cycles, checking socket connectivity, before reporting a startup failure.

  • Process Monitoring — A 5-second monitoring loop runs continuously, checking that all child processes are still alive. If a child process dies unexpectedly, the launcher will attempt to restart it up to 3 times. The restart counter resets after a successful restart.

  • PID File Management — PID files are stored as JSON in the temp/ directory with the following structure:

    {
    "ProcessId": 12345,
    "StartTime": "2026-01-15T10:30:00.000000",
    "ProcessType": "launcher"
}

  • Cleanup — On shutdown (signal handler or explicit call), the launcher terminates all child processes using psutil's process tree walking (children(recursive=True)) to ensure no orphaned grandchild processes remain. It falls back to taskkill /F /T if psutil fails.

CLI Arguments:

  • --service — Run as a Windows service (affects startup behaviour).
  • --debug — Enable DEBUG-level logging.
  • --force — Force start even if another instance is detected.

Server Manager Wiki

Clone this wiki locally