Project Structure

Relevant source files

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

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

This document outlines the architectural and file structure of the PIXONA application. The project is a desktop application built using Electron, with a user interface powered by React and Vite. The structure is designed to maintain a clear separation between the native desktop functionalities (Main Process) and the web-based UI (Renderer Process).

The architecture leverages modern web development tools for the frontend, while using Electron's APIs for deep integration with the host operating system, primarily for file system access. This hybrid approach allows for rapid UI development with React and powerful native capabilities like multi-drive photo scanning.

High-Level Architecture

The application operates on Electron's two-process model:

1. Main Process: A Node.js environment responsible for managing the application lifecycle, creating browser windows, and handling native OS interactions. It exposes system-level functionalities to the frontend via Inter-Process Communication (IPC). This is managed by electron/main.ts.
2. Renderer Process: A standard web environment where the React application runs. It is responsible for rendering the UI inside an Electron BrowserWindow. It cannot directly access Node.js or system APIs for security reasons and must communicate with the Main Process via a preload script.

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

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

Directory Layout

The project is organized into several key directories, each with a specific purpose. This structure separates concerns between the Electron backend, the React frontend, build configurations, and static assets.

Directory	Description	Source Files
electron/	Contains all source code for the Electron Main Process.	electron/main.ts, electron/preload.ts
src/	Contains all source code for the React frontend (Renderer Process).	src/App.tsx, src/pages/, src/components/
public/	Stores static assets like icons and images that are copied to the build output.	index.html, public/icon.ico
dist/	The output directory for the compiled React application, generated by Vite.	vite.config.ts:39
dist-electron/	The output directory for the compiled Electron main and preload scripts.	vite.config.ts:18
release/	The output directory for the final packaged application (e.g., .exe installer).	electron-builder.json:6

Sources: README.md:65-89, vite.config.ts:16-24,38-42, electron-builder.json:6-12

Electron Main Process

The Main Process logic is located in the electron/ directory. It is the application's backend, handling all interactions with the operating system.

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

Key Files

• electron/main.ts: The entry point for the Main Process. It is responsible for:
  • Creating and managing the BrowserWindow (createWindow function).
  • Loading the React app into the window, using Vite's dev server in development and the static index.html in production.
  • Setting up IPC handlers (ipcMain.handle) to respond to requests from the Renderer Process. These handlers perform tasks like scanning directories, reading file metadata, and moving files to trash.
  • Managing the application's lifecycle events (app.on('ready'), app.on('window-all-closed')).
• electron/preload.ts: A script that runs in a privileged context before the web page (React app) is loaded into the renderer. It acts as a secure bridge between the renderer and the main process.
  • It uses contextBridge.exposeInMainWorld to selectively expose a window.electron API to the renderer.
  • This API provides functions that the renderer can call, which in turn use ipcRenderer.invoke to trigger the corresponding handlers in main.ts.

IPC Communication Flow

The following sequence diagram shows how the frontend (Renderer Process) requests to scan a directory, and how the Main Process handles it and sends progress updates back.

Sources: electron/main.ts:140-210, electron/preload.ts:11-13, 56-62, src/pages/SettingsPage.tsx:43-55

React Renderer Process (Frontend)

The entire user interface is a React application located in the src/ directory. It is built using Vite and styled with Tailwind CSS.

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

Key Files & Structure

• src/main.tsx: The entry point for the React application. It renders the root App component into the DOM element with id="root" in index.html.
• src/App.tsx: The root component of the application. It sets up global providers (QueryClientProvider, TooltipProvider), the main router (HashRouter), and the overall layout, which includes the Sidebar and the main content area managed by Routes.
• src/components/: Contains reusable UI components. This includes both custom components like Sidebar.tsx and UI primitives from shadcn/ui located in src/components/ui/.
• src/pages/: Contains top-level components that represent the main views of the application (e.g., Library.tsx, SettingsPage.tsx). These are mapped to routes in App.tsx.
• src/lib/: Contains utility functions, database logic (db.ts), and sound management (sounds.ts).

Component and Routing Structure

The application uses react-router-dom for client-side navigation. The main layout is a two-column design with a persistent sidebar.

Sources: src/App.tsx:10-38, src/components/Sidebar.tsx

Build and Configuration

The project's build process, dependencies, and packaging are managed by several configuration files at the root level.

Package Scripts

The package.json file defines the core scripts for development and production builds.

Command	Description
npm run dev	Starts the Vite dev server and the Electron app with hot-reloading.
npm run build	Compiles the TypeScript/React app, bundles the Electron scripts, and packages a production Windows installer using electron-builder.

Sources: package.json:6-8, README.md:204-208

Configuration Files

• vite.config.ts: Configures the Vite build tool. The vite-plugin-electron is used to integrate Vite's development server and build process with Electron's main and preload scripts. It defines entry points for both processes and their respective output directories (dist and dist-electron).
• electron-builder.json: Configures electron-builder for creating distributable application packages. It specifies the appId, productName, output directory (release/), and platform-specific targets like NSIS installers for Windows (.exe).
• tailwind.config.ts & src/index.css: These files manage the application's styling. tailwind.config.ts configures Tailwind CSS, while src/index.css defines the base styles, custom utility classes, and the application's color palette using CSS variables (e.g., --app-bg, --app-text, --app-accent).

Sources: vite.config.ts, electron-builder.json, tailwind.config.ts, src/index.css:8-40

Conclusion

The PIXONA project is structured to create a robust desktop application by combining the strengths of web technologies and native capabilities. The clear separation between the Electron Main Process (backend logic) and the React Renderer Process (UI) is the cornerstone of this architecture. This modularity, enforced by a secure IPC bridge, allows for independent development and testing of the UI and native functionalities, while configuration files for Vite and Electron-Builder streamline the development and packaging workflow.