# horserider2146/paperclip architecture

> Architecture diagram of the GitHub repository horserider2146/paperclip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/horserider2146/paperclip
- Repository: https://github.com/horserider2146/paperclip

## Overview

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: [`app/src/main/java/com/example/paperclip/NetworkManager.kt`](https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/NetworkManager.kt) (Network core), [`PaperclipServer/TcpServer.cs`](https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/TcpServer.cs) (TCP server), [`app/src/main/java/com/example/paperclip/MainActivity.kt`](https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/MainActivity.kt) (Main screen), [`PaperclipServer/MainForm.cs`](https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/MainForm.cs) (Tray UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_windows["Windows host"]
  node_program["Program<br/>desktop entry<br/>[Program.cs]"]
  node_mainform["Tray UI<br/>desktop shell<br/>[MainForm.cs]"]
  node_settings_manager["Settings<br/>config store<br/>[SettingsManager.cs]"]
  node_tcp_server["TCP server<br/>network endpoint<br/>[TcpServer.cs]"]
  node_clipboard_watcher{{"Clipboard watch<br/>clipboard monitor"}}
  node_clipboard_writer{{"Clipboard write<br/>clipboard sink<br/>[ClipboardWriter.cs]"}}
end

subgraph group_android["Android client"]
  node_main_activity["Main screen<br/>mobile ui<br/>[MainActivity.kt]"]
  node_settings_store["Prefs<br/>local settings<br/>[SettingsStore.kt]"]
  node_clip_sync_service["Sync service<br/>foreground service<br/>[ClipSyncService.kt]"]
  node_clipboard_accessibility_service{{"Access watch<br/>accessibility service"}}
  node_network_manager["Network core<br/>socket client<br/>[NetworkManager.kt]"]
end

subgraph group_protocol["Sync protocol"]
  node_json_protocol["JSON messages<br/>ndjson protocol"]
  node_clipboard_change(("Local change<br/>event source"))
  node_remote_clip(("Remote clip<br/>sync payload"))
end

node_program -->|"starts"| node_mainform
node_mainform -->|"reads/writes"| node_settings_manager
node_mainform -->|"controls"| node_tcp_server
node_clipboard_watcher -->|"sends"| node_tcp_server
node_tcp_server -->|"delivers"| node_clipboard_writer
node_tcp_server -->|"encodes/decodes"| node_json_protocol
node_clipboard_watcher -->|"emits"| node_clipboard_change
node_clipboard_change -->|"serializes"| node_json_protocol
node_json_protocol -->|"carries"| node_remote_clip
node_remote_clip -->|"writes"| node_clipboard_writer
node_main_activity -->|"persists"| node_settings_store
node_main_activity -->|"starts"| node_clip_sync_service
node_clip_sync_service -->|"hosts"| node_network_manager
node_clipboard_accessibility_service -->|"feeds"| node_network_manager
node_network_manager -->|"encodes/decodes"| node_json_protocol
node_network_manager -->|"receives"| node_remote_clip
node_network_manager -->|"emits"| node_clipboard_change
node_main_activity -->|"connects"| node_network_manager

click node_program "https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/Program.cs"
click node_mainform "https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/MainForm.cs"
click node_settings_manager "https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/SettingsManager.cs"
click node_tcp_server "https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/TcpServer.cs"
click node_clipboard_watcher "https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/ClipboardWatcher.cs"
click node_clipboard_writer "https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/ClipboardWriter.cs"
click node_main_activity "https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/MainActivity.kt"
click node_settings_store "https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/SettingsStore.kt"
click node_clip_sync_service "https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/ClipSyncService.kt"
click node_clipboard_accessibility_service "https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/ClipboardAccessibilityService.kt"
click node_network_manager "https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/NetworkManager.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_program,node_mainform,node_settings_manager,node_tcp_server,node_clipboard_watcher,node_clipboard_writer toneBlue
class node_main_activity,node_settings_store,node_clip_sync_service,node_clipboard_accessibility_service,node_network_manager toneAmber
class node_json_protocol,node_clipboard_change,node_remote_clip toneMint
```

## Components

### Windows host

Desktop server-side clipboard sync runtime.

- [Program](https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/Program.cs): desktop entry · Starts the Windows process and bootstraps the server UI/runtime. · `PaperclipServer/Program.cs`
- [Tray UI](https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/MainForm.cs): desktop shell · System tray interface for controlling server lifecycle and status. · `PaperclipServer/MainForm.cs`
- [Settings](https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/SettingsManager.cs): config store · Loads and saves Windows server configuration such as port and auth token. · `PaperclipServer/SettingsManager.cs`
- [TCP server](https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/TcpServer.cs): network endpoint · Listens for Android clients, manages connections, and exchanges sync messages. · `PaperclipServer/TcpServer.cs`
- [Clipboard watch](https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/ClipboardWatcher.cs): clipboard monitor · Observes Windows clipboard changes and emits local clip events. · `PaperclipServer/ClipboardWatcher.cs`
- [Clipboard write](https://github.com/horserider2146/paperclip/blob/main/PaperclipServer/ClipboardWriter.cs): clipboard sink · Writes received clip payloads into the Windows clipboard. · `PaperclipServer/ClipboardWriter.cs`

### Android client

Mobile client-side clipboard sync runtime.

- [Main screen](https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/MainActivity.kt): mobile ui · Android UI for server settings, connection control, and manual send. · `app/src/main/java/com/example/paperclip/MainActivity.kt`
- [Prefs](https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/SettingsStore.kt): local settings · Persists Android connection settings on-device for reconnects. · `app/src/main/java/com/example/paperclip/SettingsStore.kt`
- [Sync service](https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/ClipSyncService.kt): foreground service · Keeps the Android connection alive in the background. · `app/src/main/java/com/example/paperclip/ClipSyncService.kt`
- [Access watch](https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/ClipboardAccessibilityService.kt): accessibility service · Background clipboard monitoring path that must be enabled manually. · `app/src/main/java/com/example/paperclip/ClipboardAccessibilityService.kt`
- [Network core](https://github.com/horserider2146/paperclip/blob/main/app/src/main/java/com/example/paperclip/NetworkManager.kt): socket client · 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**: ndjson protocol · Newline-delimited TCP message contract with clip, ping, pong, and auth types.
- **Local change**: event source · Represents a clipboard update originating on either platform.
- **Remote clip**: sync payload · A received clip that is written into the target system clipboard.

## Connections

- 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.
