DEV Community: wright-benjamin-1701

Building a Software KVM in Python with Clean Architecture and AI

wright-benjamin-1701 — Sat, 31 Oct 2026 14:21:51 +0000

What is mouse-share?

mouse-share is a software KVM — it lets you share a single keyboard and mouse across multiple computers on your LAN. Move your cursor off the edge of one screen and it appears on the next machine, exactly like a multi-monitor setup but across separate PCs.

If you've used Barrier or Synergy, you know the concept. I built mouse-share because the existing options are either abandoned, commercial, or carry decades of C++ complexity. I wanted something lightweight, strongly typed, and written in modern Python — with gaming-grade latency to boot.

The result is a ~3,500-line Python project with clean architecture, protocol-based dependency injection, platform-specific backends for Linux and Windows, a binary UDP event protocol, and a 310-line ops runbook. This article walks through the architecture and how AI accelerated the build.

Architecture Overview

The project follows a layered architecture that keeps platform-specific code isolated from business logic:

src/mouse_share/
├── event/                 # Domain — platform-agnostic events & codec
│   ├── types.py           #   Frozen InputEvent dataclasses
│   ├── codec.py           #   Binary UDP wire format
│   ├── held.py            #   Tracked key/button state
│   └── scancode.py        #   HID ↔ platform scancode maps
│
├── edge/                  # Domain — screen geometry & crossing
│   ├── detector.py        #   Cursor tracking state machine
│   └── layout.py          #   Multi-screen adjacency graph
│
├── capture/               # Infrastructure — OS input capture
│   ├── base.py            #   CaptureBackend protocol
│   ├── linux_x11.py       #   X11 XRecord
│   └── windows.py         #   Win32 low-level hooks
│
├── emulate/               # Infrastructure — OS input injection
│   ├── base.py            #   EmulateBackend protocol
│   ├── linux_x11.py       #   X11 XTest
│   └── windows.py         #   Win32 SendInput
│
├── net/                   # Infrastructure — networking
│   ├── protocol.py        #   Message framing & constants
│   ├── control.py         #   TCP control channel
│   ├── transport.py       #   UDP event transport + batching
│   ├── link_selector.py   #   Fastest-NIC latency probing
│   └── sockopt.py         #   Low-latency socket tuning
│
├── clipboard/             # Infrastructure — clipboard sync
│   ├── base.py            #   ClipboardBackend protocol
│   └── qt.py              #   Qt-based implementation
│
├── platform.py            # Factory — platform detection & DI
├── app.py                 # Application — orchestrator & state machine
├── config.py              # Application — config persistence
├── hotkey.py              # Application — escape combo detector
└── screen.py              # Application — multi-monitor detection

At the centre is a state machine that drives the entire application:

IDLE → CONNECTING → ACTIVE_LOCAL → ACTIVE_REMOTE
                                 ↘ CONTROLLED

When you're using your local machine, you're in ACTIVE_LOCAL. Move the cursor off-screen and focus switches to the remote peer (ACTIVE_REMOTE). The remote peer enters CONTROLLED, injecting your input. Push the cursor back across the edge and focus returns.

Domain Layer — Platform-Agnostic Events

Every input event in mouse-share is a frozen dataclass using USB HID scancodes as the universal keycode space. This means the domain layer has zero platform dependencies:

# src/mouse_share/event/types.py

@dataclass(frozen=True, slots=True)
class MouseMove:
    dx: int
    dy: int
    event_type: EventType = EventType.MOUSE_MOVE

@dataclass(frozen=True, slots=True)
class KeyPress:
    scancode: int
    event_type: EventType = EventType.KEY_PRESS

@dataclass(frozen=True, slots=True)
class KeyRelease:
    scancode: int
    event_type: EventType = EventType.KEY_RELEASE

InputEvent = MouseMove | MouseButton | MouseScroll | KeyPress | KeyRelease

The InputEvent union type gives exhaustive pattern matching everywhere events are consumed. Frozen dataclasses make events hashable and safe to pass between threads. Slots keep memory tight — these objects are created at up to 1,000 Hz on a busy mouse.

HID scancodes were the right choice for the canonical keycode space. Every platform captures in its native codes (Win32 virtual keys, X11 keysyms) and the capture backend translates to HID at the boundary. The emulation backend translates back on the receiving end. This keeps all the cross-platform mapping logic in exactly two places per platform.

Protocol-Based Dependency Injection

Instead of ABC inheritance, mouse-share uses Python's @runtime_checkable Protocols for all platform contracts. Here's the capture backend interface:

# src/mouse_share/capture/base.py

@runtime_checkable
class CaptureBackend(Protocol):
    def start(self, on_event: Callable[[InputEvent], None]) -> None: ...
    def stop(self) -> None: ...
    def set_suppressing(self, suppressing: bool) -> None: ...
    def set_escape_callback(self, callback: Callable[[], None]) -> None: ...
    def cursor_position(self) -> tuple[int, int] | None: ...

And the emulation backend:

# src/mouse_share/emulate/base.py

@runtime_checkable
class EmulateBackend(Protocol):
    def start(self) -> None: ...
    def stop(self) -> None: ...
    def inject(self, event: InputEvent) -> None: ...
    def warp(self, x: int, y: int) -> None: ...
    def cursor_position(self) -> tuple[int, int] | None: ...

Why Protocols over ABCs? Three reasons:

Structural typing. A class satisfies the protocol by having the right methods — no inheritance required. Platform backends don't need to import or subclass anything from the core.
Runtime checking. @runtime_checkable lets you do isinstance(obj, CaptureBackend) for defensive assertions without paying the ABC tax.
Test doubles for free. Any object with the right shape works, which makes mock creation trivial in the 20-module test suite.

Platform Factory — Targeting Linux and Windows

Platform-specific modules are lazily imported through factory functions. This avoids import errors on the wrong OS — you can develop the Windows backend on a Linux machine without import failures:

# src/mouse_share/platform.py

def create_capture_backend() -> CaptureBackend:
    if sys.platform == "win32":
        from mouse_share.capture.windows import WindowsCapture
        return WindowsCapture()

    if sys.platform == "linux":
        session_type = os.environ.get("XDG_SESSION_TYPE", "").lower()
        if session_type == "wayland":
            raise RuntimeError(
                "Wayland capture is not yet supported. "
                "Run under X11 or Xwayland (XDG_SESSION_TYPE=x11)."
            )
        from mouse_share.capture.linux_x11 import X11Capture
        return X11Capture()

    if sys.platform == "darwin":
        raise RuntimeError("macOS capture is not yet implemented.")

    raise RuntimeError(f"Unsupported platform: {sys.platform}")

The pyproject.toml uses environment markers to keep platform dependencies separate:

Linux: evdev >= 1.7 + python-xlib >= 0.33 (X11 XRecord/XTest)
Windows: pure ctypes — zero extra dependencies
macOS: stubs ready for pyobjc-framework-Quartz + pyobjc-framework-Cocoa

Each platform implementation is radically different under the hood. The Windows capture backend runs a Win32 message pump with SetWindowsHookEx for WH_MOUSE_LL and WH_KEYBOARD_LL in a dedicated thread. The Linux backend uses XRecord to tap the X11 event stream. But from the orchestrator's perspective, they're identical — just a CaptureBackend that calls on_event.

Networking for Low Latency

A software KVM lives or dies by its latency. mouse-share uses a dual-channel architecture:

TCP (port 24800): Control channel — length-prefixed JSON messages for handshake, screen config, clipboard sync, and focus switching.
UDP (port 24801): Event transport — binary-encoded input events batched and flushed at 125 Hz.

The binary codec keeps events tiny:

Header (4 bytes): version:u8 | flags:u8 | count:u16 LE

MouseMove:    0x01 | dx:i16 | dy:i16        → 5 bytes
MouseButton:  0x03 | button:u8 | pressed:u8 → 3 bytes
KeyPress:     0x10 | scancode:u16           → 3 bytes
KeyRelease:   0x11 | scancode:u16           → 3 bytes

Pre-compiled struct.Struct objects eliminate per-call overhead in the codec. A typical batch of 8 mouse moves fits in a single 44-byte UDP datagram — well under the MTU.

Mouse move coalescing is critical. At 1,000 Hz polling, the mouse generates far more events than we need to send. Consecutive MouseMove events are collapsed into a single event with accumulated deltas before each flush. This cuts traffic dramatically without adding any perceptible latency.

On the socket side, every knob is tuned for LAN latency:

DSCP/TOS marking (0xB8 — Expedited Forwarding) so managed switches prioritise our traffic
TCP_NODELAY to disable Nagle's algorithm on the control channel
SO_BUSY_POLL (Linux) — kernel spins for 50μs instead of sleeping, shaving ~45μs off receive latency
SO_PRIORITY (Linux) — elevated kernel packet priority
SO_BINDTODEVICE — NIC pinning when multiple interfaces are present

For multi-NIC setups, a link selector probes all local×remote IP pairs with timed UDP round-trips and picks the path with the lowest median RTT. This means if you have both Wi-Fi and a direct ethernet cable to your other machine, mouse-share automatically uses the cable.

Edge Detection & Focus Switching

The edge detector tracks the cursor position in layout coordinates. When the cursor reaches the edge of a screen and the next delta pushes it outward, a crossing event fires. The orchestrator then:

Records held keys and buttons via HeldInput
Sends synthetic release events for all held inputs on the source machine (preventing stuck keys)
Switches focus to the target peer via a SWITCH_FOCUS control message
Warps the cursor to the entry point on the target screen (proportionally mapped along the shared edge)

If things go wrong — say the remote machine crashes — pressing Ctrl+Alt+Escape immediately breaks out of remote mode and returns control to the local machine. The hotkey detector runs inside the capture backend itself, so it works even when events are being suppressed.

How AI Accelerated Development

I used Claude Code throughout this project as a pair-programming partner. Here's where AI made the biggest difference:

Scaffolding the architecture. The Protocol-based DI pattern emerged from an early conversation about how to keep platform code isolated. I described the constraints (multiple OS backends, no framework dependencies, easy to test) and the AI suggested @runtime_checkable Protocols with factory functions — a pattern I hadn't used at this scale before. It was the right call.

Platform-specific low-level code. Writing X11 XRecord capture code or Win32 SetWindowsHookEx message pumps is not something most Python developers do daily. The documentation for these APIs is sparse, scattered across man pages and decades-old MSDN articles. AI was invaluable here — it could synthesize working ctypes bindings and XRecord setup code that would have taken hours of documentation archaeology to piece together manually.

Comprehensive test suite. The project has 20 unit test modules covering everything from the binary codec to platform-specific capture and emulation backends. AI generated the initial test scaffolding and helped ensure edge cases were covered — things like truncated datagrams, scancode boundary values, and multi-monitor geometry.

The runbook. The 310-line operations guide covering installation, firewall rules, auto-start configuration (systemd, launchd, Task Scheduler), and troubleshooting was drafted collaboratively. AI knew the exact ufw commands, launchd plist format, and PowerShell Register-ScheduledTask invocations, saving significant research time.

What AI didn't do: replace understanding. Every suggestion was reviewed, tested, and often adapted. The architecture decisions were mine. The AI accelerated the implementation — especially in domains where documentation is sparse — but it didn't write the project for me. It's a research accelerator, not a code generator you trust blindly.

Lessons Learned

Clean architecture pays off for multi-platform projects. The upfront cost of defining protocols and factories is trivial compared to the cost of entangling platform code with business logic. When I added Windows support, I didn't touch a single line in the domain or application layers.

Protocols + factory functions = lightweight DI without frameworks. No dependency injection container, no decorators, no magic. Just interfaces defined as Protocols and a factory function that returns the right implementation. It's simple enough to fit in your head and powerful enough to support multiple platforms and a full test suite.

AI is best used as a research accelerator for obscure APIs. The places where AI saved the most time weren't the high-level architecture (that requires human judgement about trade-offs) but the low-level platform glue: ctypes struct definitions, X11 extension setup, Win32 message pump boilerplate. For these tasks, AI is dramatically faster than reading sparse documentation.

Try It Out

mouse-share is open source and available on GitHub: github.com/wright-benjamin-1701/mouse-share

The project ships with a comprehensive runbook covering installation, firewall setup, and auto-start configuration for all supported platforms.

Contributions welcome — especially macOS support (the protocol stubs are ready) and Wayland capture via the input-capture portal.

Scrape Wikipedia in 4m♭ (four minutes flat)

wright-benjamin-1701 — Sat, 31 Oct 2026 14:08:07 +0000

I Process All of English Wikipedia in Under 4 Minutes

After a one-time 25 GB download, every subsequent extraction — jazz musicians, sci-fi novels, literary authors, whatever you want — runs against all 25.8 million Wikipedia pages in about three and a half minutes. Here's how I got there.

The goal

Transform a corpus of semi-structured Wikipedia data into searchable, structured database tables as fast as possible.

Background

Previously, I've done data visualization projects with data scraped from Wikipedia pages. I used asynchronous, depth-first page crawling that extracted key data related to jazz music from artist, album, and genre pages.

After fetching a page, a top-level switch classified each one as a jazz artist, jazz album, or jazz-related genre. This determined which shape of Beautiful Soup-based extractor to run on that page, each one suited to target a specific table in the extracted database (artist, album, or genre). To turn a Wikipedia page into a database row, the extractor had to identify the relevant data for each column on that page. In my original architecture, this just meant writing a function to query the DOM for each data element I wanted — such as "name", "instruments", or "years active".

For each data element, I just had to inspect the DOM, write one Beautiful Soup query to grab its value, and cast/map it to the right column. Even accounting for the messiness of real-world wiki page data (DOM structure may not always be the same, or time ranges may look like "1967-2000", "1999-present", or "'62-'89"), this worked fairly well. The vast majority of pages identified at the top level as jazz-related processed without skipping due to parsing errors.

What didn't work

Every time I wanted to change the extract functions or schema to accommodate messier data or new fields, the web crawl could take hours to re-populate the extract database due to network speed and rate limiting.

Even if I could reload already-fetched pages from disk instead of the web, what if I wanted to run extracts on science fiction books instead of jazz music? Caching wouldn't help scale extracts to new subjects.

What could I do to speed things up? Parallelize? Yet, depth-first search is notoriously difficult to parallelize — especially considering the strong coupling of my web-crawling, extraction, and database writing operations.

And yet, most of my system was idling throughout the extract process. That meant there was room to rearchitect and improve. I had proved that I could generate structured data and insights from Wikipedia articles, but how could I design the system to be:

Extendable to new topics without re-downloading anything
Scalable horizontally, to make full use of my hardware
Fast enough that development iterations don't take hours

How I redesigned it

The biggest inspiration came when I noticed my extract jobs were roughly deterministic — I was downloading the same data from the same pages over and over again. This was acceptable for exploratory data analysis, but when it turned into a bottleneck for both the program and my development iterations, I asked: what are the tradeoffs for simply downloading a full dump of wiki data ahead of time?

That question evolved into the architecture below.

The pipeline

graph LR
    F["Dev<br/>writes a job class<br/>(or asks an LLM)"]
    G["Dev<br/>queries the DB<br/>SELECT ..."]
    A["Wikipedia<br/>~25 GB dump"] --> B["Download<br/>(async, one-time)"]
    B --> C["Preprocess:<br/>decompress once<br/>~109 GB raw"]
    C --> D["N workers<br/>parse + match"]
    D --> E["Extracted DB<br/>jazz.db<br/>scifi.db<br/>..."]
    F -.->|"defines tables &<br/>page-to-row mapping"| D
    E -.->|"SQL / pandas"| G

Data from Wikipedia is downloaded from dumps.wikimedia.org, decompressed, and preprocessed as a one-time job. The download takes a couple of hours, but you only repeat it as often as you need fresh wiki data. (Whether or not jazz is dead, I don't need real-time streaming data on the latest album releases.)

Why multiprocessing, not async

The old architecture was I/O-bound — waiting on network requests. The new architecture is CPU-bound — parsing megabytes of wikitext per second. Python's GIL means threading won't help for CPU-bound work, so I use ProcessPoolExecutor to fan out across all available cores.

The key enabler is Wikipedia's multistream dump format. Instead of one monolithic bz2 archive, the dump is split into ~258,000 independently-addressable compressed blocks of ~100 pages each. After a one-time decompression to a raw file, each worker can seek to any block and parse it independently — no coordination, no shared state, no locks.

Jobs are just Python files

Adding a new extraction topic means dropping a single .py file into the jobs/ directory. Each job implements a simple protocol:

class JazzJob:
    name = "jazz"
    default_db_url = "sqlite:///data/databases/jazz.db"

    def matches(self, page: WikiPage) -> bool:
        """Does this Wikipedia page belong to my topic?"""
        ...

    def extract(self, page: WikiPage) -> None:
        """Parse the page and buffer a database row."""
        ...

    def flush(self) -> None:
        """Write buffered rows to the database."""
        ...

    def setup_schema(self) -> None:
        """Create tables from ORM models."""
        ...

No registration, no config files. The CLI auto-discovers every job in the directory:

$ wiki extract list
┌─────────────────┬─────────────────────────────────────────────┐
│ Name            │ Description                                 │
├─────────────────┼─────────────────────────────────────────────┤
│ jazz            │ Jazz artists, albums, and genres             │
│ scifi           │ Sci-fi novels, films, and authors            │
│ literature      │ Literary novels, authors/poets, and poetry   │
│ classical_music │ Classical composers, compositions, and operas│
│ philosophy      │ Philosophers, works, and traditions          │
│ ...             │ (10 jobs total)                              │
└─────────────────┴─────────────────────────────────────────────┘

The results

Here's what actually happens when you run extractions against the full English Wikipedia dump (August 2026, 25.8 million pages) on a Ryzen 9 5950X (16 cores / 32 threads) with 64 GB DDR4 RAM and AIO liquid cooling. With thermal headroom to spare, all 32 threads push to 99–100% utilization for the entire duration of an extract — this is a genuinely CPU-saturated workload:

Extraction timing

Job	Pages Scanned	Matched	Wall Clock	Throughput
jazz	25,792,184	12,441	3m 23s	~196K pages/s
scifi	25,792,184	13,021	3m 22s	~197K pages/s
literature	25,792,184	149,812	5m 04s	~111K pages/s

For lightweight jobs (jazz, scifi), the system sustains roughly 195,000 pages per second across 32 workers. Literature is slower because it matches 12x more pages — 150K vs 12–13K — so the wikitext parsing and database flush overhead dominates.

What you get

Jazz — 10,967 artists, 1,408 albums, 66 genres:

Column	Artists	Albums	Genres
title	100%	100%	100%
name / artist	73.5%	97.0%	—
birth / release year	66.0%	93.0%	—
genres	67.1%	93.8%	—
instruments	53.4%	—	—
labels	35.9%	95.6%	—
personnel	—	80.3%	—
description	—	—	100%

Sci-Fi — 3,233 authors, 6,372 novels, 3,416 films:

Column	Authors	Novels	Films
title	100%	100%	100%
name / author	80.3%	79.3%	—
birth / pub / release year	68.4%	78.0%	82.1%
genres	41.6%	74.5%	—
director	—	—	78.3%
description	—	100%	100%

Literature — 81,514 authors, 66,168 novels, 2,130 poetry collections.

The fill rates reflect the reality of Wikipedia: well-known albums almost always have a label and release year, but many jazz musicians' pages lack a structured infobox for instruments or active years. That's useful signal in itself — it tells you where the data is rich and where you might want to augment it from other sources.

Before and after

graph TB
    subgraph before ["Before: Web Crawling"]
        direction TB
        B1["Fetch page (network)"] --> B2["Parse HTML (Beautiful Soup)"]
        B2 --> B3["Write row to DB"]
        B3 --> B1
        B4["Hours per run"]
        B5["Single topic"]
        B6["Sequential"]
    end

    subgraph after ["After: Dump Processing"]
        direction TB
        A1["Download dump (one-time)"] --> A2["Preprocess (one-time)"]
        A2 --> A3["N workers parse in parallel"]
        A3 --> A4["Per-topic DBs"]
        A5["~3 min per run"]
        A6["Any topic"]
        A7["32 cores"]
    end

	Web Crawling	Dump Processing
Time per run	Hours	~3 minutes
Bottleneck	Network I/O	CPU (wikitext parsing)
New topic	New crawler + hours of fetching	One Python file + 3 min extract
Parallelism	Difficult (coupled I/O + parsing)	Trivial (independent blocks)
Data freshness	Real-time	Monthly/bi-monthly snapshots

The tradeoff is data freshness: dumps are snapshots, not live data. For my use case — historical jazz discographies, literary canons, sci-fi filmographies — monthly snapshots are more than sufficient.

What's next

This architecture is modular enough to support several natural extensions:

Incremental updates: after a full extract, monitor a targeted subset of pages for changes between dumps rather than re-processing everything
Richer extraction: use NLP or entity linking to fill in the gaps that simple infobox parsing misses (those red cells in the fill-rate tables)
More topics: the same dump already supports 10 extraction jobs; adding more is a single file drop-in

Try it yourself

Clone the repo, download a dump, and you'll have a queryable database in minutes:

git clone https://github.com/wright-benjamin-1701/wiki-crawler
cd wiki-crawler
uv sync
uv run wiki dump download --lang en
uv run wiki dump preprocess
uv run wiki extract run jazz       # ~3 min on modern hardware

Then query it however you like — SQL, pandas, whatever. The data is yours.

See the full code on GitHub.