Skip to content

CLAUDE.md

Latest commit

 

History

History
122 lines (95 loc) · 5.46 KB

CLAUDE.md

File metadata and controls

122 lines (95 loc) · 5.46 KB

CLAUDE.md

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

Build Commands

CrossPaste is a Kotlin Multiplatform application using Gradle. Key commands:

  • Run the application: ./gradlew app:run
  • Build: ./gradlew build
  • Run tests: ./gradlew test
  • Code formatting: ./gradlew ktlintFormat
  • Code style check: ./gradlew ktlintCheck
  • Run single test: ./gradlew test --tests "ClassName.testMethodName"

First startup downloads JBR (JetBrains Runtime) and gradle dependencies automatically.

Code Architecture

High-Level Structure

  • Desktop multiplatform app: Built with Compose Multiplatform and Kotlin
  • Database: SQLite with SQLDelight for type-safe queries
  • Networking: Ktor for client/server communication with custom encryption
  • UI: Compose Multiplatform with Material 3 design
  • DI: Koin for dependency injection across modules

Multi-Platform Strategy

CrossPaste is a cross-platform product covering Desktop (this repo) and Mobile (Android/iOS, separate private repos). The commonMain code is designed to be shared across both Desktop and Mobile platforms — it gets copied to the mobile projects. When modifying commonMain code, always consider mobile compatibility: avoid desktop-only APIs, keep interfaces platform-agnostic, and ensure changes won't break mobile consumers.

Key Source Directories

  • app/src/commonMain/kotlin/: Shared business logic across Desktop and Mobile platforms
  • app/src/desktopMain/kotlin/: Desktop-specific implementations
  • app/src/desktopTest/kotlin/: Desktop platform tests
  • app/src/commonMain/sqldelight/: Database schema definitions

Core Module Organization

The application follows a modular architecture defined in CrossPasteModule.kt:

  • appModule(): Core application services and managers
  • sqlDelightModule(): Database layer and DAOs
  • networkModule(): Client/server networking with encryption
  • securityModule(): Cryptographic services and secure storage
  • pasteTypePluginModule(): Handlers for different clipboard data types
  • pasteComponentModule(): Clipboard monitoring and processing
  • uiModule(): UI components and screen providers
  • viewModelModule(): ViewModels for UI state management

Key Architectural Patterns

  • Dependency Injection: Koin modules organize services by domain
  • Repository Pattern: DAOs abstract database operations
  • Plugin Architecture: Extensible paste type handlers (text, images, files, etc.)
  • Platform Abstraction: Common interfaces with platform-specific implementations
  • Secure Communication: End-to-end encryption for cross-device sync

Database Schema

SQLDelight manages database schema in .sq files:

  • PasteDatabase.sq: Main paste item storage
  • PasteTaskDatabase.sq: Background task management
  • SecureDatabase.sq: Encrypted data storage
  • SyncRuntimeInfoDatabase.sq: Device synchronization state

Native Platform Integration

  • macOS: Swift integration via MacosApi.swift compiled to dylib
  • Windows/Linux: JNA for native API access
  • Global shortcuts: Platform-specific keyboard listeners
  • System tray: Cross-platform tray implementation

Development Environment

Platform-Specific Setup

  • macOS: Xcode tools required for Swift compilation
  • All platforms: JBR is automatically downloaded to jbr/ directory
  • Proxy configuration: Available in gradle.properties for restricted networks

Testing

  • Tests use MockK for mocking
  • Platform-specific test utilities in desktopTest/
  • System property appEnv=TEST is set automatically during test runs

Code Style and Conventions

  • Commit messages: Use emoji prefixes (see doc/en/CommitMessage.md)
  • Code formatting: Enforced via ktlint with exclusions for generated code
  • Package structure: Organized by feature domain under com.crosspaste
  • Platform files: Use .desktop.kt suffix for platform-specific implementations
  • Utility usage: Always check com.crosspaste.utils and prefer existing utility classes (e.g., FileUtils, DateUtils, StringUtils) instead of implementing new ones.

Key Technical Details

  • Encryption: Asymmetric encryption for secure device-to-device communication
  • Discovery: mDNS/Bonjour for local network device discovery
  • Storage: Local-only architecture with no cloud dependencies
  • Performance: Coroutines for async operations, caching for clipboard history

Code Formatting

Before attempting to compile or build the project, always run ./gradlew ktlintFormat first. If the command fails with errors, investigate and fix the issues. If it succeeds and modifies files, understand that the changes are purely stylistic and semantically equivalent to the original code — do not treat reformatted code as something that needs review or further modification.

Commit Message Convention

Format: <emoji code> <description>

Types:

  • ✨ new feature
  • 🐛 Bug fix
  • 🔨 Refactoring
  • 📝 docs
  • 🎨 code style
  • ⚡ performance
  • ✅ test
  • 👷 build/ci
  • ➕ add dependency
  • ➖ remove dependency
  • ⬆️ dependency upgrade
  • ⬇️ dependency downgrade

Examples from this project:

  • ✨ add OCR support for images
  • 🐛 resolve navigation crash on back press
  • 🔨 extract SwipeableDeviceRow component
  • 👷 bump kotlin to 2.0.0

Language: English for commit messages