Technology Stack

Relevant source files

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

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

The PIXONA application is a desktop photo management tool built using a modern stack that leverages web technologies to create a native desktop experience. The core architecture combines the Electron framework for cross-platform capabilities with a React-based frontend for a dynamic and responsive user interface.

This document outlines the key technologies, frameworks, and tools used in the project, covering the frontend, desktop integration, build processes, and styling. The stack is designed for rapid development, high performance, and a polished user experience, as detailed in the project's development roadmap.

Sources: README.md:3-5, README.md:204-213

Core Architecture

The application is fundamentally an Electron app, which consists of a main process and a renderer process. The main process, written in TypeScript, manages the application lifecycle and native OS integrations, while the renderer process runs the React user interface.

Sources: electron/main.ts, src/App.tsx, vite.config.ts:14-29

Architecture Diagram

This diagram illustrates the high-level architecture, showing the relationship between the Electron main process, the preload script, and the React renderer process.

Desktop Integration: Electron

Electron is used to package the web application (HTML, CSS, JS) into a native desktop application. The main process script (electron/main.ts) is the entry point, responsible for creating the BrowserWindow, managing its lifecycle, and handling inter-process communication (IPC).

• Main Process (electron/main.ts): Handles window creation, native OS interactions (dialogs, file system access), and IPC handlers for functions exposed to the renderer.
• Preload Script (electron/preload.ts): Acts as a secure bridge between the renderer process and the Node.js environment of the main process. It uses contextBridge to expose specific APIs (like window.electron.selectFolder) to the React application.
• Security: The BrowserWindow is configured with contextIsolation: true and nodeIntegration: false for security. A Content Security Policy (CSP) is also defined in index.html.

Sources: electron/main.ts:17-33, electron/preload.ts:4-5, index.html:29

Frontend Framework: React & TypeScript

The user interface is built as a single-page application using React and TypeScript.

• React 18: The core UI library for building components.
• TypeScript: Provides static typing for the entire codebase, including frontend components (.tsx) and Electron scripts (.ts).
• Routing: react-router-dom is used for client-side navigation between different pages like Library, Settings, and Places. The HashRouter is employed for compatibility with Electron's file-based serving.
• State Management: @tanstack/react-query is used for managing server state, caching, and data fetching logic.

Sources: package.json:30, 60, 63, src/App.tsx:6-18, tsconfig.json

Build and Development

The project uses Vite for fast development and bundling, along with Electron Builder for creating distributable application packages.

Sources: package.json:8-14, vite.config.ts, electron-builder.json

Build Tool: Vite

Vite serves as the build tool for the frontend and is integrated with Electron via vite-plugin-electron.

• Development: The npm run dev script uses concurrently to start the Vite dev server and the Electron app simultaneously. Vite provides Hot Module Replacement (HMR) for the React code.
• Configuration (vite.config.ts):
  • Defines entry points for the Electron main and preload scripts.
  • Sets up path aliases (@/ pointing to src/).
  • Configures the output directory for production builds to dist/.

// vite.config.ts
export default defineConfig(({ mode }) => ({
  // ...
  plugins: [
    react(),
    mode === "development" && componentTagger(),
    electron({
      main: {
        entry: "electron/main.ts",
        // ...
      },
      preload: {
        input: "electron/preload.ts",
        // ...
      },
      renderer: {},
    }),
  ],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  // ...
}));

Sources: vite.config.ts:8-34, package.json:8

Packaging: Electron Builder

electron-builder is used to package the application into distributable installers for Windows, macOS, and Linux.

• Configuration (electron-builder.json): This file defines all packaging options.
  • appId: com.pixona.photoapp
  • productName: PIXONA
  • files: Specifies which files and directories to include in the final package.
  • win, mac, linux: Platform-specific build targets and configurations, such as icons and installer settings. For Windows, it creates NSIS installers and portable executables.
• Build Script: The npm run build script first runs tsc and vite build, then invokes electron-builder to create the package.

The build process is visualized below:

Available Scripts

The package.json file defines several scripts for development, building, and linting.

Command	Description
npm run dev	Starts the development server with hot-reload.
npm run build	Builds the application for production.
npm run lint	Lints the codebase using ESLint.
npm run preview	Previews the production build locally.

Sources: package.json:7-14

Styling and UI Components

The application's visual design is managed by Tailwind CSS and a curated set of UI components.

Styling Engine: Tailwind CSS

Tailwind CSS is used as a utility-first CSS framework for styling the application.

• Configuration (tailwind.config.ts):
  • content: Scans .ts and .tsx files in the src/ directory to tree-shake unused styles.
  • theme.extend: Defines custom colors, fonts, and animations to match the application's design system. Colors are defined using HSL variables for easy theming.
• Design System (src/index.css):
  • Defines CSS custom properties for light and dark themes (e.g., --background, --foreground, --app-bg).
  • Includes custom component styles (.photo-grid-item) and utility layers.

Sources: tailwind.config.ts:4, 11-66, src/index.css:8-142

Component Library: shadcn/ui

The project uses shadcn/ui, a collection of reusable UI components built on top of Radix UI and Tailwind CSS.

• Configuration (components.json): Defines the style, base color, and path aliases for UI components.
• Dependencies: Key dependencies from Radix UI (e.g., @radix-ui/react-dialog, @radix-ui/react-slot) are listed in package.json.
• Usage: Components like Button, Input, and Sheet are imported from @/components/ui/ and used throughout the application.

Sources: components.json, package.json:17-48, src/pages/SettingsPage.tsx:4-11

Animations: Framer Motion

framer-motion is included for creating smooth animations and transitions within the UI. Its presence is noted in the dependencies and the project's README.md.

Sources: package.json:52, README.md:207

Key Dependencies

The following tables summarize the main production and development dependencies.

Production Dependencies

Package	Description
react / react-dom	Core library for building the user interface.
electron	Framework for building desktop apps with web tech.
react-router-dom	Client-side routing for the React app.
@tanstack/react-query	Data fetching and state management library.
tailwindcss	A utility-first CSS framework for styling.
@radix-ui/*	Primitives for building accessible UI components.
lucide-react	A library of simply beautiful icons.
framer-motion	Animation library for React.
clsx / tailwind-merge	Utilities for constructing dynamic class names.

Sources: package.json:16-80

Development Dependencies

Package	Description
vite	Build tool for modern web projects.
typescript	Superset of JavaScript that adds static types.
electron-builder	A complete solution to package and build a ready for distribution Electron app.
vite-plugin-electron	Integrates Electron with Vite.
@vitejs/plugin-react-swc	Fast React refresh with SWC for Vite.
eslint	Pluggable and configurable linter tool.
concurrently / wait-on	Tools to run multiple commands in parallel during development.

Sources: package.json:82-97

Future Integrations

The project roadmap outlines several technologies planned for future integration:

• face-api.js: For browser-based face recognition.
• Leaflet.js + OpenStreetMap: For an interactive map view of geotagged photos.
• SQLite: For a local database to index photo metadata.
• sharp: For high-performance server-side image processing (likely in the Electron main process).

Sources: README.md:215-219