Welcome to the Pixona Wiki

Relevant source files

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

• README.md
• package.json
• electron-builder.json
• electron/main.ts
• electron/preload.ts
• src/App.tsx
• src/lib/db.ts
• src/pages/SettingsPage.tsx
• src/components/Sidebar.tsx
• src/index.css
• vite.config.ts

Pixona is a desktop photo management application for Windows, inspired by Apple Photos. It is built using modern web technologies, with a frontend powered by React and TypeScript, and packaged into a native desktop application using the Electron framework. This provides a rich user interface with native capabilities like file system access.

The application's architecture is based on Electron's multi-process model, separating the user interface (Renderer Process) from the backend operations (Main Process). This separation ensures that the UI remains responsive even during intensive tasks like scanning large photo libraries. Communication between these processes is handled securely through a preload script and Inter-Process Communication (IPC).

Architecture Overview

Pixona follows the standard Electron architecture, which consists of a Main process and one or more Renderer processes.

• Main Process: A Node.js environment responsible for creating and managing application windows (BrowserWindow), handling native OS interactions (dialogs, menus), and performing all file system operations. It serves as the backend of the application.
• Renderer Process: A Chromium browser environment responsible for rendering the user interface. In Pixona, this is a React application. It cannot directly access Node.js APIs or the file system for security reasons.
• Preload Script: A script that runs in a privileged context with access to both the window object of the Renderer process and Node.js APIs. It acts as a secure bridge, exposing specific backend functionalities from the Main process to the Renderer process via the window.electron API.

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

Project Structure

The repository is organized into several key directories that separate concerns between the Electron backend, React frontend, and build configurations.

Directory	Description
electron/	Contains all files related to the Electron Main process, including the main entry point (main.ts) and the preload script (preload.ts).
src/	Contains the source code for the React frontend application, including pages, components, libraries, and styles.
public/	Stores static assets like icons and images that are copied to the build output.
release/	The output directory for production builds, containing the packaged application installer.
dist/	The output directory for the built React application files.
dist-electron/	The output directory for the compiled Electron main and preload scripts.

Sources: README.md:58-82, electron-builder.json:7-10

Frontend (Renderer Process)

The frontend is a single-page application built with React, TypeScript, and Vite. It is responsible for all aspects of the user interface.

Sources: package.json:20-56, README.md:204-210

Technology Stack

Technology	Purpose
React 18	Core UI framework for building components.
TypeScript	Provides static typing for robust and maintainable code.
Vite	Build tool and development server, offering fast hot-reloading.
React Router	Handles client-side navigation between different views.
Tailwind CSS	A utility-first CSS framework for styling the application.
shadcn/ui	A collection of reusable UI components.
Framer Motion	Used for creating smooth animations and transitions.
React Query	Manages server state, caching, and data fetching.

Sources: package.json:20-56, README.md:204-210, vite.config.ts

Routing

Client-side routing is managed by react-router-dom. The main application component, App.tsx, defines the routes for each page, which are displayed alongside a persistent Sidebar.

// src/App.tsx:28-38
<HashRouter>
  <div className="flex h-screen w-full overflow-hidden bg-background">
    <Sidebar />
    <Routes>
      <Route path="/" element={<Library />} />
      <Route path="/calendar" element={<Calendar />} />
      <Route path="/people" element={<People />} />
      <Route path="/albums" element={<Albums />} />
      <Route path="/places" element={<Places />} />
      <Route path="/duplicates" element={<Duplicates />} />
      <Route path="/settings" element={<SettingsPage />} />
      <Route path="*" element={<NotFound />} />
    </Routes>
  </div>
</HashRouter>

Sources: src/App.tsx:28-38, src/components/Sidebar.tsx:16-23

Styling

The application uses a custom design system built on top of Tailwind CSS. Colors, fonts, and other design tokens are defined as CSS variables in src/index.css, allowing for features like light and dark mode theming.

/* src/index.css:48-57 */
/* Custom PIXONA tokens */
--app-bg: 0 0% 4%;
--app-surface: 0 0% 6%;
--app-hover: 0 0% 10%;
--app-border: 0 0% 16%;
--app-text: 0 0% 95%;
--app-text-muted: 0 0% 60%;
--app-accent: 211 100% 52%;
--app-accent-hover: 211 100% 45%;

Sources: src/index.css:48-57, tailwind.config.ts:18-53

Backend (Main Process) & IPC

The Main process, defined in electron/main.ts, handles all interactions with the operating system and file system. These functionalities are exposed to the Renderer process through an IPC (Inter-Process Communication) bridge.

IPC API

The electron/preload.ts script exposes a set of asynchronous functions on the window.electron object. The Renderer process calls these functions to request operations from the Main process.

The following diagram shows the sequence of a photo scanning operation.

The table below lists the key functions available through the IPC bridge.

Function	Description	Main Process Handler
getDrives()	Retrieves a list of available disk drives on the system.	get-drives
selectFolder()	Opens a native dialog for the user to select one or more folders.	select-folder
scanDirectory(path)	Recursively scans a directory for supported image and video files.	scan-directory
moveToTrash(path)	Moves a specified file to the system's trash or recycling bin.	move-to-trash
setAutoStart(enabled)	Configures the application to launch on system startup.	set-auto-start
onScanProgress(callback)	Listens for real-time progress updates during a directory scan.	scan-progress (event)

Sources: electron/preload.ts:4-53, electron/main.ts:83-263

Database and Data Persistence

Pixona uses the browser's IndexedDB API to store photo metadata, application settings, and cache. This provides a persistent, local database without requiring an external database engine. The database logic is encapsulated in the PhotoDatabase class.

Sources: src/lib/db.ts

Database Schema

The database pixona_photos_db is structured with several object stores to manage different types of data.

This ER diagram shows the relationships between the main data entities.

Data Models

The core data structures are defined as TypeScript interfaces.

PhotoMetadata Interface:
This interface represents a single photo or video in the library.

Field	Type	Description
id	string	Unique identifier.
path	string	Absolute file path on the disk.
name	string	File name.
type	'image' | 'video'	The type of the media file.
created	Date	The creation date of the file.
hash	string	A hash of the file for duplicate detection.

Sources: src/lib/db.ts:15-38

Settings Interface:
This is a simple key-value store for application settings.

Field	Type	Description
key	string	The unique key for the setting (e.g., 'theme').
value	any	The value of the setting.

Sources: src/lib/db.ts:48-51, src/pages/SettingsPage.tsx:64-73

Build and Packaging

The project uses Vite for development and electron-builder for creating distributable production installers.

Build Process

The npm run build command orchestrates the entire build process.

This flowchart outlines the steps involved in creating a production build.

Build Configuration

The electron-builder.json file defines how the application is packaged for different platforms. Key configurations for Windows include:

• Target: Creates an NSIS installer (.exe) and a portable version.
• Architectures: Supports both x64 and ia32.
• Installer Options: Allows changing the installation directory and creates desktop/start menu shortcuts.

// electron-builder.json:14-25
"win": {
  "target": [
    {
      "target": "nsis",
      "arch": ["x64", "ia32"]
    },
    {
      "target": "portable",
      "arch": ["x64"]
    }
  ],
  "icon": "public/icon.ico",
  "artifactName": "${productName}-${version}-${arch}-Setup.${ext}",
  "publisherName": "PIXONA",
  "requestedExecutionLevel": "asInvoker"
}

Sources: electron-builder.json:14-25, README.md:183-191