Architecture Overview

Relevant source files

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

• electron/main.ts
• electron/preload.ts
• src/App.tsx
• package.json
• vite.config.ts
• electron-builder.json
• README.md

Pixona is a desktop photo management application built using Electron, which allows for the creation of native desktop applications with web technologies. The architecture is fundamentally divided into two main parts: the Electron Main Process which acts as the backend and has access to Node.js APIs, and the Renderer Process which is a standard React web application that renders the user interface.

Communication between these two isolated processes is handled securely through a Preload Script. This script acts as a bridge, exposing specific backend functionalities (like file system access) to the frontend in a controlled manner via Inter-Process Communication (IPC). The application is built and bundled using Vite for the frontend and electron-builder for creating the final distributable installer.

Sources: README.md, electron/main.ts, electron/preload.ts

Core Technologies

The application leverages a modern technology stack for both its desktop integration and user interface.

| Category | Technology | Description | Source -
| Desktop Framework | Electron | Allows for building cross-platform desktop apps with web technologies. | package.json:39 -
| Build Tool | Vite | Provides a fast development server and bundles the React application. | package.json:62, vite.config.ts -
| UI Library | React | A JavaScript library for building user interfaces. | package.json:49 -
| Language | TypeScript | Provides static typing for JavaScript to improve code quality and maintainability. | package.json:76, tsconfig.json -
| Styling | Tailwind CSS | A utility-first CSS framework for rapid UI development. | package.json:75, tailwind.config.ts -
| UI Components | shadcn/ui | A collection of re-usable UI components. | README.md:200, components.json -

| Packaging | electron-builder | Packages and builds a ready-for-distribution Electron app. | package.json:40, electron-builder.json -

Application Structure

The application follows the standard Electron process model, separating the application's main logic from its user interface.

This diagram illustrates the high-level architecture of the Pixona application.

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

Main Process

The Main Process is the entry point of the Electron application and runs in a Node.js environment. It is responsible for managing the application's lifecycle, creating and managing browser windows, and handling all interactions with the native operating system.

Source: electron/main.ts

Key Responsibilities:

• Window Management: Creates the main BrowserWindow, sets its dimensions, and loads the React application.
  Sources: electron/main.ts:15-49
• Application Lifecycle: Handles events like ready, window-all-closed, and activate. It also enforces a single instance lock to prevent multiple app instances from running.
  Sources: electron/main.ts:63-90
• IPC Handlers: Listens for and responds to asynchronous messages from the Renderer Process. This is how the frontend requests access to native resources.
  Sources: electron/main.ts:95-294
• Native Integration: Uses Electron and Node.js APIs like dialog, shell, and fs to perform OS-level tasks such as opening file dialogs, accessing the file system, and moving files to trash.
  Sources: electron/main.ts:1-3, 108-121, 240-244

Renderer Process

The Renderer Process is responsible for rendering the user interface. It is a standard React single-page application (SPA) that runs in a Chromium browser window. It is sandboxed and does not have direct access to Node.js or the file system for security reasons.

Source: src/App.tsx

Key Components:

• Root Component: src/App.tsx is the main component that sets up routing, providers (QueryClientProvider, TooltipProvider), and the main layout including the Sidebar.
  Sources: src/App.tsx:10-41
• Routing: Uses react-router-dom with HashRouter to manage different pages/views within the application like Library, People, and Settings.
  Sources: src/App.tsx:12, 29-37
• UI Components: The UI is built with shadcn/ui components and styled with Tailwind CSS. Custom styles and theme variables are defined in src/index.css.
  Sources: package.json:16-38, src/index.css
• State Management: Uses React's built-in state management (useState, useEffect) and @tanstack/react-query for managing server state and caching.
  Sources: package.json:39, src/pages/SettingsPage.tsx:2-4, 40-47

Inter-Process Communication (IPC)

IPC is the mechanism that allows the sandboxed Renderer Process to communicate with the privileged Main Process. This is achieved via a preload script, which is a critical security feature in Electron.

Sources: electron/preload.ts, electron/main.ts

The electron/preload.ts script uses contextBridge.exposeInMainWorld to securely expose a specific set of functions to the Renderer's window object under the electron key. These functions can then be called from the React application to trigger IPC events handled by the Main Process.

The following sequence diagram shows the flow for scanning a directory:

Exposed API

The preload.ts script exposes the following API to the Renderer process:

Method	Description	Main Process Handler
getDrives()	Gets available system drives.	get-drives
selectFolder()	Opens a native dialog to select folders.	select-folder
scanDirectory()	Recursively scans a directory for media files.	scan-directory
getFileMetadata()	Retrieves metadata for a specific file.	get-file-metadata
fileExists()	Checks if a file exists at a given path.	file-exists
readFile()	Reads a file and returns its content as Base64.	read-file
moveToTrash()	Moves a file to the system's trash.	move-to-trash
copyFile()	Copies a file from a source to a destination.	copy-file
moveFile()	Moves/renames a file.	move-file
openFile()	Opens a file with its default application.	open-file
showInFolder()	Shows a file in the native file explorer.	show-in-folder
getAppVersion()	Gets the application version from package.json.	get-app-version
setAutoStart()	Enables or disables app auto-start on login.	set-auto-start
getAutoStart()	Gets the current auto-start status.	get-auto-start
onScanProgress()	Listens for real-time progress during a scan.	scan-progress (event)

Sources: electron/preload.ts:4-57, electron/main.ts:98-291

Build and Packaging

The project uses Vite for development and building the frontend, and electron-builder for packaging the final application for distribution.

Sources: package.json:6-12, vite.config.ts, electron-builder.json

The build process is initiated by the npm run build script.

This diagram shows the steps involved in creating a production build of the application.

Sources: package.json:7, vite.config.ts:30-34, electron-builder.json:5-10

The electron-builder.json file defines configurations for different target platforms (Windows, macOS, Linux), including installer options, icons, and artifact names.

Sources: electron-builder.json