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/autoUpdater.js

@@ -1,11 +1,42 @@
+/**
+ * Electron auto-update system using electron-updater.
+ *
+ * Handles:
+ * - update detection
+ * - user confirmation dialogs
+ * - download progress streaming to renderer
+ * - application restart and installation
+ */
+
 const { autoUpdater } = require("electron-updater");
 const { dialog } = require("electron");
 const { logger } = require("../server/logger");
 
+/**
+ * Configures autoUpdater behavior:
+ * - disables automatic download
+ * - disables automatic install on quit
+ * (manual user-controlled update flow)
+ */
 autoUpdater.autoDownload = false;
 autoUpdater.autoInstallOnAppQuit = false;
 
+/**
+ * Initializes application auto-update lifecycle.
+ *
+ * Registers update event listeners and binds them to:
+ * - UI dialogs (Electron dialog)
+ * - renderer communication (webContents)
+ * - download/install flow control
+ *
+ * @param {BrowserWindow} mainWindow - main Electron window instance
+ */
 function initAutoUpdater(mainWindow) {
+
+  /**
+   * Triggered when a new version is detected.
+   * Prompts user to install or defer update.
+   */
   autoUpdater.on("update-available", async (info) => {
     logger.info(`Update available: ${info.version}`);
 
@@ -28,6 +59,10 @@ function initAutoUpdater(mainWindow) {
     }
   });
 
+  /**
+   * Streams update download progress to renderer process.
+   * Used to update UI progress bar and status indicators.
+   */
   autoUpdater.on("download-progress", (progress) => {
     logger.info(`Download progress: ${Math.round(progress.percent)}%`);
     mainWindow?.webContents.send("update-progress", {
@@ -36,6 +71,10 @@ function initAutoUpdater(mainWindow) {
     });
   });
 
+  /**
+   * Triggered when update has been fully downloaded.
+   * Prompts user to restart application and install update.
+   */
   autoUpdater.on("update-downloaded", async (info) => {
     logger.info(`Update downloaded: ${info.version}`);
 
@@ -52,6 +91,10 @@ function initAutoUpdater(mainWindow) {
     if (response === 0) autoUpdater.quitAndInstall();
   });
 
+  /**
+   * Handles update system errors.
+   * Logs failure and displays an error dialog to user.
+   */
   autoUpdater.on("error", (err) => {
     logger.error("Auto update error:", err.message);
     dialog.showErrorBox("Update Error", err.message);
@@ -60,6 +103,10 @@ function initAutoUpdater(mainWindow) {
   checkForUpdates();
 }
 
+/**
+ * Manually triggers update check on startup.
+ * Separated from init for reusability and testability.
+ */
 async function checkForUpdates() {
   try {
     await autoUpdater.checkForUpdates();
@@ -68,6 +115,10 @@ async function checkForUpdates() {
   }
 }
 
+/**
+ * Manually triggers update download.
+ * Used when user accepts update prompt.
+ */
 async function downloadUpdate() {
   try {
     await autoUpdater.downloadUpdate();
@@ -76,6 +127,9 @@ async function downloadUpdate() {
   }
 }
 
+/**
+ * Immediately quits application and installs downloaded update.
+ */
 function installUpdate() {
   autoUpdater.quitAndInstall();
 }