Contributing to Pixona
Relevant source files
The following files were used as context for generating this wiki page:Pixona is a desktop photo management application built with modern web technologies, including React, TypeScript, and Electron. This guide provides developers with the necessary information to set up the development environment, understand the project's architecture, and contribute effectively. The project is structured as a monorepo with the Electron main process code in the electron/ directory and the React frontend application in the src/ directory.
Contributions are welcome. To contribute, please fork the repository, create a feature branch, commit your changes, and open a pull request for review.
Sources: README.md:3-5, 203-207
1. Getting Started
1.1. Prerequisites
Before you begin, ensure you have the following software installed on your system.
- Node.js: Version 18.x or higher
- npm: Version 9.x or higher (comes with Node.js)
- Git: For cloning the repository
Sources: README.md:31-34
1.2. Installation
To set up the project locally, follow these steps:
- Clone the repository:
git clone https://github.com/tirumalad-del/pixona-your-photo-library.git cd pixona-your-photo-library - Install dependencies:
This command installs all required packages for both the Electron application and the React frontend.npm install
Sources: README.md:44-55
1.3. Running in Development Mode
To start the application in a development environment with hot-reloading:
npm run dev
This script, defined in package.json, uses concurrently to start the Vite development server for the React frontend and then launches the Electron application, which loads the Vite server URL.
Sources: package.json:8, README.md:61-63
The development startup process is illustrated below.
This diagram shows the sequence of commands executed by npm run dev to launch the development environment.
Sources: package.json:8, vite.config.ts:9, electron/main.ts:40
2. Project Architecture
The application is divided into two main parts: the Electron main process (backend) and the React renderer process (frontend).
2.1. Project Structure
The repository is organized into several key directories.
| Path | Description |
|---|---|
electron/ | Contains the Electron main process source code (main.ts) and preload script (preload.ts). |
src/ | Contains the React application source code. |
src/components/ | Reusable React components, including shadcn/ui components. |
src/pages/ | Top-level page components for each view (e.g., Library, Settings). |
src/lib/ | Utility functions, helpers, and the IndexedDB wrapper (db.ts). |
public/ | Static assets like icons. |
release/ | Output directory for production builds generated by electron-builder. |
electron-builder.json | Configuration for packaging the application for production. |
vite.config.ts | Configuration for the Vite build tool. |
package.json | Project dependencies and scripts. |
Sources: README.md:76-100, electron-builder.json:6
2.2. Technology Stack
The project utilizes a modern web development stack.
| Category | Technology |
|---|---|
| Desktop Framework | Electron |
| Frontend | React 18, TypeScript, React Router |
| Styling | Tailwind CSS, shadcn/ui, Framer Motion |
| Build Tool | Vite with vite-plugin-electron |
| Packaging | electron-builder |
| Local Database | IndexedDB |
Sources: README.md:162-172, package.json
3. Backend (Electron Main Process)
The main process is the entry point of the Electron application, responsible for creating browser windows and handling all native OS interactions, including file system access.
Sources: electron/main.ts
3.1. Inter-Process Communication (IPC)
The frontend (renderer process) communicates with the backend (main process) through an IPC bridge defined in electron/preload.ts. This script securely exposes specific Node.js functionalities to the React application via the window.electron object.
The diagram below illustrates the flow of an IPC call from a React component to the main process to scan a directory.
This sequence shows how the renderer process securely requests file system access from the main process.
Sources: electron/preload.ts:11-12, electron/main.ts:133, src/components/ImportDialog.tsx:43
3.2. Exposed API
The following functions are exposed to the renderer process via the preload script.
| Method | Description | IPC Channel |
|---|---|---|
getDrives() | Gets available system drives (e.g., C:/, D:/). | get-drives |
selectFolder() | Opens a native dialog to select folders. | select-folder |
scanDirectory() | Recursively scans a directory for media files. | scan-directory |
onScanProgress() | Listens for real-time progress during a directory scan. | scan-progress (event) |
moveToTrash() | Moves a file to the system's trash. | move-to-trash |
getAppVersion() | Returns the application's version string. | get-app-version |
setAutoStart() | Enables or disables launching the app on system startup. | set-auto-start |
Sources: electron/preload.ts:5-49, electron/main.ts:91-267
4. Frontend (React Renderer Process)
The frontend is a single-page application built with React and TypeScript, responsible for the entire user interface.
4.1. Local Database (IndexedDB)
Pixona uses IndexedDB for persistent storage of photo metadata, settings, and other application data. The src/lib/db.ts file provides a class-based wrapper (PhotoDatabase) around the IndexedDB API for easier interaction.
The database schema is defined by the object stores created during the onupgradeneeded event.
This ER diagram outlines the tables (Object Stores) and their primary keys within the application's IndexedDB.
Sources: src/lib/db.ts:3-44, 69-102
The PhotoDatabase class in src/lib/db.ts exposes methods for CRUD operations on these stores, such as addPhoto, getAllPhotos, getSetting, and setSetting.
Sources: src/lib/db.ts:105, 143, 248, 264
5. Building for Production
To create a distributable installer for the application, use the npm run build command. This script triggers Vite to build the React app and then uses electron-builder to package it.
Sources: package.json:9
5.1. Build Scripts
| Command | Description |
|---|---|
npm run build | Builds the application for the host OS. |
npm run build:win | Specifically builds for Windows. |
npm run build:mac | Specifically builds for macOS. |
npm run build:linux | Specifically builds for Linux. |
Sources: package.json:9-12
5.2. Build Configuration
The build process is configured in electron-builder.json. Key settings include:
appId:com.pixona.photoappproductName:PIXONAdirectories.output:release- Windows Target (
win): Creates an NSIS installer (.exe) for 64-bit and 32-bit architectures, as well as a portable version. - macOS Target (
mac): Creates a DMG and ZIP file. - Linux Target (
linux): Creates an AppImage, DEB, and RPM package.
The NSIS installer for Windows is configured to allow users to change the installation directory and creates desktop and start menu shortcuts.
Sources: electron-builder.json:3-5, 11-33