refactor: add full documentation and fix theme loading robustness

- Add JSDoc comments across frontend and backend modules
- Improve code readability and maintainability with consistent documentation style
- Document Electron IPC handlers, UI utilities, and theme system
- Add missing function/class documentation in theme loader and app services
- Minor structural improvements and cleanup across Electron main process modules
- Minor fixes on variable names

app/windowManager.js

@@ -1,21 +1,55 @@
+/**
+ * Electron main window module dependencies.
+ * Handles BrowserWindow lifecycle and application UI shell.
+ */
+
 const { BrowserWindow, app } = require("electron");
 const path = require("path");
 const { logger } = require("../server/logger");
 const { configFeatures } = require("../config");
 const config = require("../config");
 
+/**
+ * Singleton reference to the main Electron BrowserWindow instance.
+ * Ensures only one application window exists at runtime.
+ */
 let mainWindow = null;
 
+/**
+ * Creates and initializes the main Electron application window.
+ *
+ * Responsibilities:
+ * - Ensures singleton window instance (prevents duplicates)
+ * - Configures window options (size, icon, preload, security settings)
+ * - Loads frontend application from local dev server
+ * - Handles lifecycle events (close, errors)
+ *
+ * @returns {Promise<BrowserWindow>} The created or existing window instance
+ */
 async function createMainWindow() {
+
+  /**
+   * Prevents multiple instances of the main window.
+   * Returns existing instance if already created.
+   */
   if (mainWindow) {
     logger.warn("Window already exists, no new creation!");
     return mainWindow;
   }
 
+  /**
+   * Resolves application icon path depending on runtime mode:
+   * - Development: local build folder
+   * - Production: packaged Electron resources
+   */
   const iconPath = config.devMode
     ? path.join(__dirname, "../build/app-icon.ico")
     : path.join(process.resourcesPath, "build/app-icon.ico");
 
+  /**
+   * Electron BrowserWindow configuration object.
+   * Defines UI behavior, security settings, and preload bridge.
+   */
   const windowOptions = {
     title: `Freedom Loader ${config.version}`,
     icon: iconPath,
@@ -35,6 +69,10 @@ async function createMainWindow() {
 
   mainWindow = new BrowserWindow(windowOptions);
 
+  /**
+   * Loads the frontend application served by the local dev server.
+   * In production, this could be replaced with a file:// build.
+   */
   try {
     await mainWindow.loadURL(`http://localhost:${config.applicationPort}`);
     logger.info("Window loaded");
@@ -43,6 +81,10 @@ async function createMainWindow() {
     throw err;
   }
 
+  /**
+   * Cleans up window reference when the main window is closed.
+   * Prevents memory leaks and allows recreation if needed.
+   */
   mainWindow.on("closed", () => {
     logger.info("Main window closed");
     mainWindow = null;
@@ -51,6 +93,14 @@ async function createMainWindow() {
   return mainWindow;
 }
 
+/**
+ * Returns the current main window instance.
+ *
+ * Useful for IPC handlers and background services
+ * needing access to the renderer process.
+ *
+ * @returns {BrowserWindow | null}
+ */
 function getMainWindow() {
   return mainWindow;
 }