This document provides a high-level introduction to the CrossPaste desktop application codebase, explaining its purpose, core architecture, and how the major systems fit together. For detailed information about specific subsystems, see the child pages: Features and Capabilities, Technology Stack, Architecture Overview, and Roadmap and Version History.
CrossPaste is a cross-device clipboard synchronization application that enables seamless clipboard sharing across macOS, Windows, and Linux desktop computers. The application monitors the system clipboard, stores clipboard history locally in SQLite, and synchronizes content to other devices on the local network using encrypted peer-to-peer communication. Key characteristics include:
app), a native CLI tool (cli), a web extension (web), and shared logic (core, shared, shared-ui). [gradle/libs.versions.toml1-120]Sources: [README.md1-41], [README.zh-CN.md1-41], [app/src/desktopTest/kotlin/com/crosspaste/mcp/McpToolProviderTest.kt84-92]
The following diagram maps the high-level system architecture to the actual Koin dependency injection modules and key service classes. The system is highly modular, separating concerns into specialized Koin modules:
System Architecture with Code Entities
Sources: [app/src/desktopTest/kotlin/com/crosspaste/mcp/McpToolProviderTest.kt70-92]
The following diagram illustrates how clipboard data flows through the system, from capture to persistence and synchronization, using actual class and interface names:
Clipboard Data Flow with Code Entities
Sources: [app/src/desktopTest/kotlin/com/crosspaste/mcp/McpToolProviderTest.kt70-92], [app/src/commonMain/kotlin/com/crosspaste/sync/SyncPollingManager.kt17-30]
The application is organized into the following major subsystems, each documented in detail on separate wiki pages:
| Subsystem | Purpose | Key Classes | Wiki Page |
|---|---|---|---|
| Paste Type Plugins | Handle 7 clipboard content types with specialized processors | DesktopTextTypePlugin, DesktopImageTypePlugin, DesktopFilesTypePlugin | Paste Type Plugin System |
| Data Persistence | SQLite-based storage with SQLDelight type-safe DAOs | SqlPasteDao, SqlPasteTagDao, SqlSyncRuntimeInfoDao | Data Persistence |
| Device Synchronization | Discovery, connection management, and encrypted sync | SyncPollingManager, SyncManager, PasteClientApi | Device Synchronization |
| User Interface | Compose Multiplatform UI with MainWindow and SearchWindow | DesktopScreenProvider, MainWindow, SearchWindow | User Interface |
| Network Layer | Ktor client/server for device communication | PasteClientApi, PasteRouting, PullRouting | Network Layer |
| Extensions | Specialized modules for OCR and AI integration | DesktopOCRModule, DesktopMcpServer, McpToolProvider | Extensions and Modules |
Sources: [app/src/desktopTest/kotlin/com/crosspaste/mcp/McpToolProviderTest.kt84-92], [app/src/commonMain/kotlin/com/crosspaste/sync/SyncPollingManager.kt17-30]
The codebase follows a Kotlin Multiplatform structure with several specialized modules:
:core: The lowest-level shared library. Contains PasteType definitions, PasteItem hierarchy, and SecureKeyPair. Targets JVM and JS (for browser extension). [gradle/libs.versions.toml100-101]:shared: SQLDelight database layer (SqlPasteDao), path providers, and config management. [app/src/desktopTest/kotlin/com/crosspaste/mcp/McpToolProviderTest.kt70-78]:shared-ui: Shared UI components and themes built with Compose Multiplatform.:app: The main desktop application containing platform-specific implementations. [README.md54]:cli: A native command-line tool built with Kotlin/Native and Clikt for terminal interaction. [gradle/libs.versions.toml58]:web: Chrome browser extension (Manifest V3) using React and Kotlin/JS.Sources: [gradle/libs.versions.toml1-120], [README.md54]
The application initializes through the following sequence:
CrossPaste.main() initializes the environment and path providers.SqlPasteDao and SyncPollingManager are instantiated. [app/src/commonMain/kotlin/com/crosspaste/sync/SyncPollingManager.kt69-81]MainWindow.For detailed lifecycle documentation, see Application Core.
Sources: [app/src/commonMain/kotlin/com/crosspaste/sync/SyncPollingManager.kt69-81]
The project uses semantic versioning. Current version: v1.2.7. [CHANGELOG.md5-6] The release pipeline includes:
For roadmap details, see Roadmap and Version History.
Sources: [CHANGELOG.md5-6], [README.md18-26]
CrossPaste is built on the following core technologies:
| Technology | Purpose |
|---|---|
| Kotlin | Primary language (Multiplatform 2.3.x) [gradle/libs.versions.toml25] |
| Compose Multiplatform | UI framework (1.10.x) [gradle/libs.versions.toml7] |
| Ktor | HTTP client/server (3.4.x) [gradle/libs.versions.toml34] |
| SQLDelight | Type-safe SQLite database access [gradle/libs.versions.toml47] |
| Koin | Dependency injection framework [gradle/libs.versions.toml24] |
| MCP SDK | Model Context Protocol for AI tool integration [gradle/libs.versions.toml36] |
Sources: [gradle/libs.versions.toml1-53]
To start working with the codebase:
git clone https://github.com/CrossPaste/crosspaste-desktop.git [README.md47]./gradlew app:run (downloads JBR and dependencies on first run) [README.md54]TestDriverFactory for in-memory database testing. [app/src/desktopTest/kotlin/com/crosspaste/mcp/McpToolProviderTest.kt66]Sources: [README.md42-55], [app/src/desktopTest/kotlin/com/crosspaste/mcp/McpToolProviderTest.kt66]
For detailed documentation on specific subsystems:
:core, :shared, and :cli modules.Sources: Wiki Table of Contents (Sections 1.1 - 18)
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.