Feature: Application Settings

Relevant source files

The following files were used as context for generating this wiki page:

• src/pages/SettingsPage.tsx
• src/lib/db.ts
• electron/main.ts
• electron/preload.ts
• src/index.css
• src/App.tsx
• tailwind.config.ts

The Application Settings feature provides a centralized user interface for configuring the behavior and appearance of the PIXONA application. Users can modify settings related to their photo library, performance, system integration, and visual theme. These configurations are persisted locally on the user's machine, ensuring a customized experience across application sessions.

The settings are managed through the SettingsPage React component, which interacts with a local IndexedDB for data persistence and with the Electron main process for native operating system functionalities like file dialogs and auto-start management. The settings page is accessible via the /settings route within the application's main router.

Sources: src/pages/SettingsPage.tsx, src/lib/db.ts, src/App.tsx:28

Architecture

The settings feature architecture involves three main parts: the React frontend component (SettingsPage.tsx), the IndexedDB persistence layer (db.ts), and the Electron main process (main.ts) for native OS interactions.

The diagram below illustrates the high-level interaction between these components.

State Management and Persistence

Settings are managed within the SettingsPage.tsx component using React's useState hooks for each individual setting. When the component mounts, it loads the saved values from IndexedDB. When the user saves changes, the component's state is written back to the database.

Loading and Saving Settings

1. Loading: An useEffect hook triggers the loadSettings function on component mount. This function retrieves saved values for settings like autoStart from the settings object store in IndexedDB via db.getSetting.
2. Saving: The handleSaveSettings function is called when the user clicks the "Save Settings" button. It iterates through the current state of all settings and persists each one as a key-value pair in the database using db.setSetting.

Sources: src/pages/SettingsPage.tsx:31-40, 78-93, src/lib/db.ts:285-310

The following sequence diagram shows the flow for saving settings.

Database Schema

Settings are stored in the settings object store within the pixona_photos_db IndexedDB. This store uses a simple key-value structure.

Configurable Settings

The settings are grouped into several categories on the UI.

Settings UI State

The table below lists the state variables managed by the SettingsPage component.

State Variable	Type	Default Value	UI Control	Description
libraryPath	string	"C:\\Users\\Photos"	Input	The root path of the user's photo library.
autoScan	boolean	false	Switch	Toggles auto-scanning for new photos on startup.
watchChanges	boolean	false	Switch	Toggles monitoring library folders for real-time changes.
faceDetection	boolean	true	Switch	Enables or disables face detection feature.
autoNameFaces	boolean	false	Switch	Toggles automatic naming suggestions for faces.
cacheSize	string	"2048"	Input	The size of the thumbnail cache in MB.
theme	"dark" | "light"	"dark"	Select	The application's visual theme.
soundEnabled	boolean	true	Switch	Toggles UI sound effects.
soundVolume	number	0.3	Slider	Sets the volume for UI sound effects.
autoStart	boolean	false	Switch	Toggles launching PIXONA on system startup.

Sources: src/pages/SettingsPage.tsx:16-26

Library Settings

This section allows configuration of the photo library's location and scanning behavior.

• Library Path: The user can change the library path by clicking the "Browse" button, which triggers the handleBrowseFolder function. This function calls window.electron.selectFolder(), an API exposed via preload.ts that invokes the select-folder IPC handler in main.ts. This handler opens a native "open directory" dialog.

Sources: src/pages/SettingsPage.tsx:42-58, 170-180, electron/preload.ts:8-9, electron/main.ts:133-147

Appearance

Users can switch between a light and dark theme.

• Theme: The handleThemeChange function is called when the user selects a theme. It updates the theme state and toggles the .dark class on the root <html> element. The application's styling, defined with CSS variables in src/index.css, responds to the presence of this class to apply the appropriate theme colors.

The CSS variables for both themes are defined as follows:

/* src/index.css:10-43 */
@layer base {
  :root {
    --background: 0 0% 4%;
    --foreground: 0 0% 95%;
    /* ... other dark theme variables ... */
    --app-bg: 0 0% 4%;
    --app-surface: 0 0% 6%;
    --app-text: 0 0% 95%;
  }

  .light {
    --background: 0 0% 100%;
    --foreground: 0 0% 10%;
    /* ... other light theme variables ... */
    --app-bg: 0 0% 98%;
    --app-surface: 0 0% 100%;
    --app-text: 0 0% 10%;
  }
}

Sources: src/pages/SettingsPage.tsx:149-154, 206-227, src/index.css:10-111, tailwind.config.ts:18-62

Storage & Performance

This section provides tools for managing application storage.

• Clear Thumbnail Cache: The handleClearCache button prompts the user for confirmation. If confirmed, it calls db.clearAllData(), which clears all data from all object stores in the IndexedDB, including photos, albums, settings, and cache.

The flow for clearing the cache is as follows:

Windows Settings

This section contains settings specific to the desktop environment, which are only rendered if the app is running in Electron (window.electron is available).

• Start with Windows: This toggle controls whether the application launches automatically at system startup. The handleAutoStartToggle function saves the boolean state to IndexedDB and also communicates with the Electron main process via the set-auto-start IPC channel to register or unregister the application with the OS login items.

The sequence for enabling auto-start is shown below.