How horserider2146/paperclip works
1. Repo shape
- This is a two-client system: a Windows desktop server in PaperclipServer/ and an Android app in app/.
- The architectural boundary is the LAN/Wi‑Fi network link between them; there is no cloud backend or internet dependency.
2. Overall data flow
- Clipboard updates originate on either platform.
- Each side detects local clipboard changes, serializes them into a small JSON message, and sends them over a persistent TCP socket.
- The remote side receives the message and writes the payload into its own system clipboard.
3. Windows side: host/server role
- TcpServer.cs is the network endpoint that listens for Android clients, manages connections, and exchanges JSON messages.
- ClipboardWatcher.cs monitors Windows clipboard changes, likely via Win32 clipboard listener APIs as described in the README.
- ClipboardWriter.cs is the write path back into the Windows clipboard when Android sends a new clip.
- MainForm.cs provides the system tray UI and start/stop control for the server.
- SettingsManager.cs holds server configuration such as port and optional auth token.
- Program.cs is the desktop app entry point and bootstraps the Windows process.
4. Android side: client role
- NetworkManager.kt is the networking core: it connects to the Windows host, maintains the socket, and sends/receives protocol messages.
- ClipSyncService.kt is the long-running foreground service that keeps the connection alive in the background.
- ClipboardAccessibilityService.kt is the background clipboard monitoring path; the README says it must be enabled manually for automatic sync.
- MainActivity.kt is the UI for entering server IP/port/token and initiating connection or manual send.
- SettingsStore.kt persists the connection settings on-device.
5. Protocol boundary
- The two apps communicate with a shared, simple protocol: newline-delimited JSON over TCP.
- Message types in the README include clip, ping, pong, and auth.
- This protocol is the main integration contract between the platforms; UI and clipboard logic on each side are separate from transport details.
6. State and configuration
- Both sides are configuration-driven rather than discovery-driven.
- Windows exposes a configurable listening port and optional auth token.
- Android stores the PC IP, port, and token locally so the user can reconnect without re-entering values.
- The auth token is an optional trust boundary for limiting who can connect on the local network.
7. Lifecycle model
- Windows runs as a user-launched desktop app with tray controls, so server lifetime is tied to the GUI process.
- Android uses a foreground service for connection persistence, which is important because the clipboard sync must survive normal app backgrounding.
- Clipboard monitoring on Android relies on an accessibility-service-based background component, which is a separate lifecycle and permission surface from the main activity.
8. Concurrency and bidirectional sync
- This is a bidirectional sync system, not a one-way push.
- A local clipboard change triggers an outbound network send; an inbound network clip triggers a local clipboard write.
- That means both sides need loop-prevention or source-tracking behavior somewhere in the implementation, because writing a received clip can itself look like a new local clipboard event.
9. Infrastructure and environment
- The only required infrastructure is a shared LAN/Wi‑Fi network and a reachable Windows host.
- Windows may require firewall permission for the TCP port.
- Android requires accessibility-service enablement for background monitoring and a foreground service for persistent networking.
10. Repo-level packaging
- The repository is a cross-platform mono-repo with separate build systems: .NET for Windows and Gradle/Kotlin for Android.
- Shared behavior is conceptual rather than code-shared; the interoperability point is the JSON/TCP protocol and the agreed clipboard semantics.
- Tests exist on the Android side (src/test, src/androidTest), while the Windows app appears focused on the runtime components and UI shell.
Main entry points: NetworkManager.kt Network core · TcpServer.cs TCP server · MainActivity.kt Main screen · MainForm.cs Tray UI
Components 14
Windows host
Desktop server-side clipboard sync runtime.
- Program · Starts the Windows process and bootstraps the server UI/runtime.
PaperclipServer/Program.cs - Tray UI · System tray interface for controlling server lifecycle and status.
PaperclipServer/MainForm.cs - Settings · Loads and saves Windows server configuration such as port and auth token.
PaperclipServer/SettingsManager.cs - TCP server · Listens for Android clients, manages connections, and exchanges sync messages.
PaperclipServer/TcpServer.cs - Clipboard watch · Observes Windows clipboard changes and emits local clip events.
PaperclipServer/ClipboardWatcher.cs - Clipboard write · Writes received clip payloads into the Windows clipboard.
PaperclipServer/ClipboardWriter.cs
Android client
Mobile client-side clipboard sync runtime.
- Main screen · Android UI for server settings, connection control, and manual send.
app/src/main/java/com/example/paperclip/MainActivity.kt - Prefs · Persists Android connection settings on-device for reconnects.
app/src/main/java/com/example/paperclip/SettingsStore.kt - Sync service · Keeps the Android connection alive in the background.
app/src/main/java/com/example/paperclip/ClipSyncService.kt - Access watch · Background clipboard monitoring path that must be enabled manually.
app/src/main/java/com/example/paperclip/ClipboardAccessibilityService.kt - Network core · Connects to the Windows host, maintains the socket, and sends/receives protocol messages.
app/src/main/java/com/example/paperclip/NetworkManager.kt
Sync protocol
Shared TCP/JSON contract between the two runtimes.
- JSON messages · Newline-delimited TCP message contract with clip, ping, pong, and auth types.
- Local change · Represents a clipboard update originating on either platform.
- Remote clip · A received clip that is written into the target system clipboard.
Connections 18
- Program → Tray UI: starts · Bootstraps the desktop shell and server process.
- Tray UI → Settings: reads/writes · Uses persisted server configuration.
- Tray UI → TCP server: controls · Starts and stops the listening server.
- Clipboard watch → TCP server: sends · Forwards local clipboard updates for network sync.
- TCP server → Clipboard write: delivers · Applies inbound clips to the Windows clipboard.
- TCP server → JSON messages: encodes/decodes · Uses the shared JSON-over-TCP message contract.
- Clipboard watch → Local change: emits · Detects a local clipboard change.
- Local change → JSON messages: serializes · Turns local changes into protocol messages.
- JSON messages → Remote clip: carries · Transports clip payloads between peers.
- Remote clip → Clipboard write: writes · Applies received content to the local clipboard.
- Main screen → Prefs: persists · Stores host address, port, and token.
- Main screen → Sync service: starts · Launches or binds the persistent sync runtime.
- Sync service → Network core: hosts · Keeps networking alive in the foreground service.
- Access watch → Network core: feeds · Sends detected clipboard events into the sync core.
- Network core → JSON messages: encodes/decodes · Implements the TCP message contract.
- Network core → Remote clip: receives · Consumes inbound remote clipboard payloads.
- Network core → Local change: emits · Publishes locally observed clipboard changes for sync.
- Main screen → Network core: connects · Initiates manual connection and send actions.