← Kushal Kusram projects ReaderFlow GitHub
ReaderFlow logo

ReaderFlow: building a local-first podcast prototype

Kushal Kusram · November 14, 2026 · source on GitHub

ReaderFlow was an attempt to turn the articles I save in Raindrop into short, two-host podcast episodes, generated entirely on my own computer and copied to my phone over Wi-Fi. No cloud model, no API keys, no server. This is the write-up of the finished prototype: what I built, what I verified, and what I found along the way.

Outcome: a finished prototype. The Mac app generates episodes fully locally, the Raindrop sign-in works end to end, and the encrypted, resumable phone transfer is built and tested. The phone side was verified in the iOS Simulator rather than on a physical phone, and the OAuth relay is a design rather than a deployment. That is the scope this prototype was built to, and it is complete.

The idea

A normal Raindrop user should be able to install a desktop app, connect Raindrop in the browser, let a local model write a conversational script from a saved article, hear it narrated by two distinct voices, and later listen offline on a phone. The product rules I wrote on day one were strict: nothing leaves the machine except the OAuth handshake and the original article fetch; no user ever pastes an API key; syncing to the phone is explicit, encrypted and resumable.

I split the unknowns into three feasibility questions: local generation quality, nearby sync reliability, and Raindrop OAuth. The prototype answers each of them at the scope described below.

What I built

A native macOS app in SwiftUI. It extracts readable text from a public URL, asks a local Qwen3 model (via MLX) for a two-host script with a revision pass, then renders it with Kokoro voices into an episode library with resume, seek, speed control and per-episode script view. It was iterated through real use:

It is packaged as an ad-hoc-signed build (v0.4.0, attached to the GitHub release; macOS will ask you to approve it on first launch). 26 unit tests cover the text rules and the episode library.

What I verified

QuestionResult
Local generation (Mac)Works. End to end on a laptop. CPU rendering beat the GPU (MPS) path on real dialogue, so CPU is the default. An earlier Piper-based plan was superseded. Mac only; Windows was not part of the prototype.
Raindrop OAuthWorks for a single owner. Browser authorization, token exchange, Keychain storage, collection listing and persistence across relaunch all ran against a real registered app. Token refresh after expiry (about two weeks) was not exercised.
Nearby SyncWorks in the Simulator. Pairing, encryption, resume and revoke verified between the Mac and an iPhone receiver in the iOS 27.2 Simulator. Physical devices, Android and Windows were not part of the prototype.

The OAuth surprise

I had assumed a desktop app could do OAuth with a public client. Raindrop's token endpoint requires a client_secret for both the code exchange and the refresh, and documents no PKCE alternative. A secret inside a distributed app is not a secret, so the honest design needs a small relay that holds it. I wrote one (about 70 lines, a Cloudflare Worker that proxies only those two calls and stores nothing) as the design for distributed builds; it is not deployed. For my own use I added a personal mode that keeps my own secret in the Keychain, and that is what signed in.

Testing sync without a second computer

I had one Mac and one iPhone, and the phone-side receiver didn't exist yet. So I built it, then tested it in the iOS 27.2 Simulator against the Mac, with a small proxy in the path to throttle the link and cut it at chosen points. The protocol: a QR code that expires in two minutes, a key agreed from both devices and approved on both, every chunk (1 MiB, so 250 for a 250 MiB file) encrypted and verified before it is written, a ledger saved after each chunk, and a whole-file SHA-256 check before the file becomes visible.

Approval screen showing the sender address the QR points at
The phone shows exactly where the QR points and waits for an explicit approval. The Mac asks for its own approval in the terminal.
Scanner screen after camera access was denied, asking to paste the QR text
No camera in the Simulator: the app falls back to pasting the QR text instead of failing.

What happened under stress

Receive screen showing 61 of 250 chunks saved after the first outage
After outage one: 61 of 250 chunks saved.
Receive screen showing 161 of 250 chunks saved after the second outage
After outage two: 161 of 250. It resumed from 61, not from zero.
Receive screen showing 57 of 250 chunks saved after relaunching the app
After a force-quit and relaunch: still 57 of 250, with an option to discard the partial.
Receive screen showing a file that passed SHA-256 verification
A finished transfer passes verification before it is listed.
Sync screen after revoking the Mac, showing no sender but the received files kept
After revoke: no sender is listed, received files remain.

This is simulator evidence, and it is labeled that way throughout. A Simulator shares the Mac's network, so it cannot show iOS's Local Network permission prompt, Wi-Fi client isolation, sleep behavior or real radio loss. It is not a physical-device result.

Things that cost more time than the idea

Scope

The prototype covers the Mac generation pipeline, a Raindrop sign-in in single-user mode, and the encrypted, resumable transfer protocol with an iPhone receiver. Its boundaries: Mac only, sync verified in the Simulator, a relay design rather than a deployment, personal distribution, and no usage study. The experiment tooling, written results and technical notes in the repository back every claim on this page.

If you want to build on it