Data Flow and State Management

Relevant source files

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

• electron/main.ts
• electron/preload.ts
• src/App.tsx
• src/pages/SettingsPage.tsx
• src/types/electron.d.ts
• README.md

This document outlines the data flow architecture and state management strategies employed in the PIXONA application. The system is built on Electron, which separates the application into a Main process (backend) and a Renderer process (frontend), each with distinct responsibilities for handling data and state.

The core of the architecture involves secure communication between the React-based frontend and the Node.js-based backend, facilitated by an IPC (Inter-Process Communication) bridge. State is managed at multiple levels: volatile UI state within React components, and persistent application settings stored locally.

High-Level Architecture

PIXONA's architecture consists of three key parts: the Electron Main process, the Electron Renderer process, and a Preload script that acts as a secure bridge between them.

This diagram illustrates the separation of concerns. The Main process handles all backend and OS-level tasks, while the Renderer process is responsible for the user interface. The Preload script selectively exposes backend functionality to the frontend.

Sources: electron/main.ts, electron/preload.ts, src/App.tsx

Main Process (Backend Logic)

Sources: electron/main.ts

The Main process, defined in electron/main.ts, serves as the application's backend. It is responsible for creating and managing the application window, interacting with the operating system, and handling all file system operations. It exposes functionality to the Renderer process through a set of secure IPC handlers.

Key Responsibilities

• Window Management: Creating and configuring the BrowserWindow.
• File System Operations: Reading directories, accessing file metadata, and performing file operations like moving to trash.
• Native UI: Displaying native OS dialogs for selecting files and folders.
• IPC Handling: Listening for and responding to requests from the Renderer process via ipcMain.

IPC Handlers

The Main process sets up handlers for various asynchronous tasks. These are invoked from the Renderer process.

Channel Name	Description	File & Lines
get-drives	Fetches a list of available system drives (e.g., C:/).	electron/main.ts:111-131
select-folder	Opens a native dialog to select one or more directories.	electron/main.ts:134-149
scan-directory	Recursively scans a directory for media files, sending progress updates.	electron/main.ts:152-220
get-file-metadata	Retrieves metadata (size, creation date, etc.) for a specific file.	electron/main.ts:223-236
file-exists	Checks if a file exists at a given path.	electron/main.ts:239-245
read-file	Reads a file and returns its content as a Base64 encoded buffer.	electron/main.ts:248-254
move-to-trash	Moves a specified file to the system's trash or recycling bin.	electron/main.ts:257-263
set-auto-start	Configures the application to launch at system startup.	electron/main.ts:296-305
get-app-version	Returns the current application version from package.json.	electron/main.ts:291-293

A special one-way IPC channel, scan-progress, is used to send real-time updates from the scan-directory handler back to the renderer without waiting for a request.

Sources: electron/main.ts:108-310

Renderer-Main Communication (IPC Bridge)

Sources: electron/preload.ts, src/types/electron.d.ts

Direct access to Node.js APIs from the Renderer process is disabled for security reasons (nodeIntegration: false). Communication is enabled through a preload script (electron/preload.ts), which runs in a privileged context.

The window.electron API

The preload script uses contextBridge.exposeInMainWorld to attach a custom electron object to the global window object in the renderer. This object contains a curated set of functions that map to the ipcMain handlers.

// electron/preload.ts
contextBridge.exposeInMainWorld('electron', {
  // Get available drives
  getDrives: () => ipcRenderer.invoke('get-drives'),
  
  // Select folder dialog
  selectFolder: () => ipcRenderer.invoke('select-folder'),
  
  // Scan directory for photos/videos
  scanDirectory: (directoryPath: string) => 
    ipcRenderer.invoke('scan-directory', directoryPath),

  // Listen to scan progress
  onScanProgress: (callback: (progress: any) => void) => {
    const subscription = (_event: any, progress: any) => callback(progress);
    ipcRenderer.on('scan-progress', subscription);
    
    // Return unsubscribe function
    return () => {
      ipcRenderer.removeListener('scan-progress', subscription);
    };
  },
});

Sources: electron/preload.ts:4-53

The API's structure is formally defined in src/types/electron.d.ts to provide TypeScript intellisense and type safety in the React codebase.

Sequence of an IPC Call

The following diagram shows the sequence of events when a user action in the UI triggers a file system operation.

This diagram illustrates the asynchronous, promise-based flow for requesting data from the main process.

Sources: src/pages/SettingsPage.tsx:40-54, electron/preload.ts:10-10, electron/main.ts:134-149

Renderer Process (Frontend State Management)

Sources: src/App.tsx, src/pages/SettingsPage.tsx

The Renderer process is responsible for the entire user interface, built with React. State management is handled using a combination of React hooks and specialized libraries.

Component-Level State

Standard React hooks like useState and useEffect are used to manage the local, volatile state of individual components. For example, in SettingsPage.tsx, form inputs and UI toggles are controlled by state variables.

// src/pages/SettingsPage.tsx
export default function SettingsPage() {
  const [libraryPath, setLibraryPath] = useState("C:\\Users\\Photos");
  const [autoScan, setAutoScan] = useState(false);
  // ... other state variables
}

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

The useEffect hook is used to fetch initial data when a component mounts, such as loading saved settings.

// src/pages/SettingsPage.tsx
useEffect(() => {
    // Load settings from database
    const loadSettings = async () => {
      // ...
      const savedAutoStart = await db.getSetting<boolean>('autoStart');
      if (savedAutoStart !== undefined) setAutoStart(savedAutoStart);
    };
    loadSettings();
}, []);

Sources: src/pages/SettingsPage.tsx:27-35

Application-Level State

The root App component sets up providers for application-wide concerns:

• QueryClientProvider: From @tanstack/react-query, this is used for managing server state, caching, and background data fetching. In this context, the "server" is the Electron Main process.
• TooltipProvider: Manages tooltips across the application.
• HashRouter: Handles client-side routing between different pages (Library, Settings, etc.).

Sources: src/App.tsx:19-38

Data Persistence Interface

While the source for src/lib/db.ts is not provided, its interface can be inferred from its usage in SettingsPage.tsx. It appears to be a simple key-value store for persisting application settings. The README.md suggests this is implemented with SQLite.

Method	Description
db.getSetting<T>(key)	Asynchronously retrieves a setting value by its key.
db.setSetting(key, value)	Asynchronously saves or updates a setting.
db.clearAllData()	Asynchronously clears all stored data (e.g., cache).

This persistence layer is crucial for remembering user preferences and application state between sessions.

Sources: src/pages/SettingsPage.tsx:32-33, 59-66, 78-80, README.md:100-100

Summary

The data and state management in PIXONA is clearly defined. The Electron Main process acts as a trusted backend, handling all sensitive operations. The React-based Renderer process manages the UI and its state, communicating with the backend via a secure IPC bridge defined by the preload script. State is managed both locally within components and persistently through a dedicated data storage module, ensuring a robust and secure user experience.