Skip to content

Developer Guide & Architecture

Jump to bottom
Ekrem EDALI edited this page May 20, 2026 · 1 revision

KoBar's architecture is designed to handle complex OS-level integrations (clipboard reading, window pinning, system tray, SMTC media controls) while maintaining a buttery-smooth React frontend.

This guide provides a high-level overview of how KoBar is built.

🏗 High-Level Architecture

KoBar follows a strict separation of concerns utilizing Electron's process models:

  1. Main Process (electron/main.cts): Handles window creation, system tray, native OS APIs (Node.js), and global shortcuts.
  2. Preload Script (electron/preload.cts): Acts as the Context Bridge. It securely exposes a strongly-typed window.api to the React frontend.
  3. Renderer Process (src/): The React frontend. It strictly handles UI and user interactions. It has no direct access to Node.js modules.
  4. Worker Threads (electron/smtc-worker.cts): Heavy background tasks, such as monitoring Windows System Media Transport Controls, are offloaded to worker threads to prevent blocking the main event loop.

👻 The "Ghost Window" Pattern

One of the most unique engineering solutions in KoBar is how it handles the "Always on Top" and "Free-Floating" mechanics without creating multiple native windows.

Instead of a small window that moves around the screen, KoBar initializes as a massive, transparent, click-through window (e.g., 6000x4000px on Windows) that covers all connected monitors.

  • The UI: The actual React components (the sidebar) are rendered within this giant transparent canvas.
  • Mouse Events: We dynamically monitor hover states over the React components. If the mouse is over KoBar, we intercept the click. If the mouse is over the transparent void, we use win.setIgnoreMouseEvents(true, { forward: true }) to pass the click down to the applications running underneath.

This approach allows KoBar to be dragged seamlessly across multiple monitors and docked anywhere without native OS window-snapping restrictions.

💾 State Management (Zustand)

KoBar uses Zustand for all global state management. Redux is not used in this project to keep the bundle size small and the API footprint minimal.

  • useAppStore.ts: Manages global app settings, orientation (left/right/free), themes, and UI toggles.
  • useClipboardStore.ts: Handles the complex FIFO queue logic for the Sequential Clipboard Manager.
  • useChatStore.ts: Manages AI Hub context and message history.
  • useScreenshotStore.ts: Manages the Konva.js drawing state and captured images.

Rule of Thumb: useState should only be used for purely isolated, local UI toggles (e.g., opening a dropdown menu).

🖥 Cross-Platform Guidelines

KoBar is built with a "Windows-First, macOS-Ready" mindset. When contributing to the backend, you must adhere to the OS Detection Rule:

const isMac = process.platform === 'darwin';
const isWin = process.platform === 'win32';

if (isWin) {
    // Execute PowerShell or Windows-native API
} else if (isMac) {
    // Execute AppleScript or Mac-native API
} else {
    console.warn('Feature not supported on this OS');
}

Never write code that assumes the OS. Always provide a fallback or safely ignore the execution if the OS doesn't support the feature.

Next Step: Learn about our strict security practices in Security, Privacy & IPC.

Clone this wiki locally