PasteBarApp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

PasteBar is a cross-platform clipboard manager built with Tauri (Rust + TypeScript/React). It provides unlimited clipboard history, custom clip management, collections, and advanced features like programming language detection and web scraping.

Technology Stack:

• Backend: Rust with Tauri framework, Diesel ORM (SQLite), Reqwest, Serde, Tokio
• Frontend: TypeScript, React, React Query, Vite, TailwindCSS, Jotai, Zustand
• Platforms: macOS and Windows (including Apple Silicon M1, Intel, AMD, and ARM)

Development Commands

Prerequisites

First install the Diesel CLI:

cargo install diesel_cli --no-default-features --features sqlite

Main Development Commands

# Development (starts both frontend and backend in dev mode)
npm start
# or
npm run dev

# Build for production
npm run build

# Build debug version
npm run app:build:debug

# Platform-specific builds
npm run app:build:osx:universal
npm run app:build:osx:x86_64
npm run app:build:windows:arm

# Database migrations
npm run diesel:migration:run

# Code formatting
npm run format

# Version management
npm run version:sync

Frontend Development (packages/pastebar-app-ui/)

The frontend is a workspace package that builds separately:

cd packages/pastebar-app-ui
npm run dev    # Development server on port 4422
npm run build  # Build to dist-ui/

Rust/Tauri Development (src-tauri/)

cd src-tauri
cargo run --no-default-features  # Development mode
cargo build --release           # Production build

Architecture Overview

High-Level Structure

Tauri Architecture: The app uses Tauri's hybrid architecture where:

• Rust backend handles core functionality (clipboard monitoring, database operations, system integration)
• TypeScript/React frontend provides the UI
• Communication happens via Tauri commands and events

Core Components:

1. Clipboard Monitoring (src-tauri/src/clipboard/mod.rs)

   • Real-time clipboard monitoring using clipboard-master
   • Automatic image capture and text processing
   • Language detection for code snippets
   • Configurable exclusion lists and masking

2. Database Layer (src-tauri/src/db.rs + Diesel)

   • SQLite database with migrations in migrations/
   • Custom data location support with path transformation
   • Connection pooling with r2d2

3. System Integration (src-tauri/src/main.rs)

   • System tray menu with dynamic content
   • Global hotkeys and window management
   • Platform-specific features (macOS accessibility, Windows compatibility)

4. State Management (Frontend)

   • Jotai for atomic state management
   • Zustand stores for settings, collections, clipboard history
   • React Query for server state and caching

Key Patterns

Path Transformation System:

• Images are stored with {{base_folder}} placeholders for relative paths
• to_relative_image_path() and to_absolute_image_path() handle conversion
• Enables custom database locations without breaking image references

Event-Driven Communication:

• Tauri events for real-time updates between backend and frontend
• Settings synchronization across multiple windows
• Menu rebuilding on state changes

Multi-Window Architecture:

• Main window (primary interface)
• History window (clipboard history view)
• QuickPaste window (contextual paste menu)

Database Schema

Main entities:

• items - Custom clips and menu items
• clipboard_history - Automatic clipboard captures
• collections - Organization containers
• tabs - Sub-organization within collections
• link_metadata - Web scraping and link preview data
• settings - User preferences and configuration

Frontend Structure

packages/pastebar-app-ui/src/
├── components/     # Reusable UI components
├── pages/         # Main application pages
├── store/         # State management (Jotai + Zustand)
├── hooks/         # Custom React hooks
├── lib/           # Utilities and helpers
├── locales/       # Internationalization
└── assets/        # Static assets

Backend Structure

src-tauri/src/
├── commands/      # Tauri command handlers
├── services/      # Business logic layer
├── models/        # Database models
├── clipboard/     # Clipboard monitoring
├── menu.rs        # System tray menu
├── db.rs          # Database configuration
└── main.rs        # Application entry point

Important Development Notes

Settings Management

• Settings are stored as generic key-value pairs in the database
• Frontend uses settingsStore.ts with automatic synchronization
• Use updateSetting() function and include invoke('build_system_menu') for settings that affect the system tray

Custom Data Locations

• The app supports custom database locations via user settings
• All file operations must use get_data_dir(), get_clip_images_dir(), etc.
• Path transformation ensures image references work across location changes

Image Handling

• Images are stored in both thumbnail and full resolution
• Use path transformation helpers when storing/retrieving image paths
• Images support relative paths with {{base_folder}} placeholders

Internationalization

• Backend translations in src-tauri/src/services/translations/translations.yaml
• Frontend translations in packages/pastebar-app-ui/src/locales/lang/
• Use t() function in React components and Translations::get() in Rust

Debug Logging

• Use debug_output(|| { println!("message") }) in Rust for debug-only logging
• Debug messages only appear in debug builds, keeping release builds clean

System Tray Menu

• Dynamic menu built from database items and settings
• Rebuild required when items or relevant settings change
• Use invoke('build_system_menu') after operations that affect menu content

Database Migrations

• Use Diesel migrations for schema changes
• Place migration files in migrations/ directory
• Run migrations with npm run diesel:migration:run