feat: implement single instance lock to ensure data integrity and resource efficiency

apps/desktop/README.md

@@ -146,6 +146,13 @@ A fully managed update lifecycle powered by `electron-updater`. Background downl
 
 A transparent proxy mechanism that handles cross-origin requests by sanitizing non-standard `app://` and `file://` Origin headers on outgoing requests and injecting permissive CORS response headers on incoming responses — allowing seamless integration with cloud APIs without server-side configuration changes.
 
+### 🔒 Single Instance Lock & Data Integrity
+
+The application enforces a **single running instance** via `app.requestSingleInstanceLock()`. If a user attempts to launch a second instance, the duplicate process is terminated immediately and the existing window is restored and focused. This mechanism serves two critical purposes:
+
+- **Data Integrity**: Prevents race conditions and write conflicts in local databases (IndexedDB/PouchDB) that could arise from concurrent access by multiple Electron processes.
+- **Resource Efficiency**: Avoids duplicate memory allocation, IPC handler registration, and protocol handler conflicts.
+
 ---
 
 ## Hardened Security Perimeter

apps/desktop/src/main/index.ts

@@ -358,9 +358,30 @@ function sendToRenderer(channel: string, ...args: unknown[]): void {
   }
 }
 
-// ─── 7. App Lifecycle ───────────────────────────────────────────
+// ─── 7. Single Instance Lock & App Lifecycle ────────────────────
+//    Prevent multiple instances to protect local database integrity
+//    (IndexedDB/PouchDB) and avoid resource contention.
 
-app.whenReady().then(() => {
+const gotTheLock = app.requestSingleInstanceLock();
+
+if (!gotTheLock) {
+  // Another instance is already running — terminate immediately.
+  app.quit();
+} else {
+  // ── Handle second-instance launch attempts ──────────────────
+  //    If a user tries to open a second instance, restore and
+  //    focus the existing window instead.
+  app.on('second-instance', () => {
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) {
+        mainWindow.restore();
+      }
+      mainWindow.focus();
+    }
+  });
+
+  // ── Primary initialization ──────────────────────────────────
+  app.whenReady().then(() => {
     // Register the custom protocol before creating the window
     registerAppProtocol();
 
@@ -393,17 +414,17 @@ app.whenReady().then(() => {
         createWindow();
       }
     });
-});
+  });
 
-// Quit when all windows are closed (except macOS)
+  // Quit when all windows are closed (except macOS)
-app.on('window-all-closed', () => {
+  app.on('window-all-closed', () => {
     if (process.platform !== 'darwin') {
       app.quit();
     }
-});
+  });
 
-// Security: prevent navigation to unexpected URLs
+  // Security: prevent navigation to unexpected URLs
-app.on('web-contents-created', (_event, contents) => {
+  app.on('web-contents-created', (_event, contents) => {
     contents.on('will-navigate', (event, url) => {
       // Allow navigation within the app protocol and dev server
       if (
@@ -414,4 +435,5 @@ app.on('web-contents-created', (_event, contents) => {
       }
       event.preventDefault();
     });
-});
+  });
+}