kindle-sync

The problem

I draft in Obsidian and like to revise on paper-like hardware, so the loop I wanted was: write markdown, read and annotate it on a Kindle Scribe, and get the marked-up text back into the vault.

Key design decisions

Mail as the transport. Amazon’s Send to Kindle accepts documents by email from approved senders, so the pipeline needs no device protocol: a file watcher picks up vault changes, a converter renders a PDF, and SMTP delivers it. A USB path exists for copying files back and forth directly. The other direction runs an annotated PDF through text extraction and OCR, then into markdown.

Config-driven behaviour. Vault paths, the Kindle address, approved senders, patterns and conversion options live in a YAML config, with an example file in the repo.

Tests and deployment tooling. The repo has 21 test files with 278 test functions (I counted them statically and did not run them for this write-up), plus Docker and deployment scripts and CI.

Stack

Python 3.11+, watchdog, ReportLab and WeasyPrint, pytesseract, PyYAML, and optional async and database layers.

Outcome and what I would change

The history is 76 commits in about nine days (2025-10-10 to 2025-10-19), and that shows. The core idea is small (watch, convert, send), but the repo grew modules for async processing, a database, tracing, caching, rate limiting and business metrics, plus design documents describing four phases of work. Those layers are far bigger than the problem. An in-repo test report from that period records only a partial success, which it attributes to network problems in the test environment. I would keep a single synchronous pipeline, delete the speculative layers, and write the tests for the Markdown to PDF path first. It stays public as an honest example of over-building.