Case study / offline-first Android

Handwritten notes, anchored to the page.

Marginalia is an offline-first Android tablet app for writing beside lecture slides, papers, and textbooks, then remembering what you wrote with flashcards and spaced review.

The Attention Is All You Need paper with a highlighted passage in the abstract, beside handwritten margin notes on the Transformer

Scope

Independent Android projectProduct design, offline data model, PDF import, handwritten ink, spaced review, search, self-updates, and automated checks.

Constraint

Keep handwritten context attached to the source page.Notes are page-aware, while stylus input and touch navigation remain separate.

Public artifacts

Source, signed releases, and CIRepository ↗ · releases ↗ · workflows ↗

01 / write beside

Every PDF page gets its own margin canvas.

Notes sit alongside the source rather than obscuring it.

02 / stay anchored

Strokes belong to the page where they were written.

Page context is part of the data model, not just the interface.

03 / no mode switch

The stylus writes. Fingers move the page.

Ink and navigation are separated by input, not a button.

Updates without a store

Small, verified updates straight from GitHub Releases.

Marginalia is sideloaded, so it carries its own updater. Every release publishes a small manifest beside the APK: version, checksum, signing certificate, release notes, and any patches. The app reads that file instead of calling the GitHub API. Code hot-patching was ruled out early; a small signed update gets a fix out just as fast and keeps Android's normal install checks.

  1. Two channels. Stable follows tagged releases, and Nightly rebuilds on every push to main. Switching to Nightly takes a backup snapshot first. Switching back never downgrades: the next stable release replaces the nightly build.
  2. Patches, not full downloads. CI diffs each new APK against the last two stable releases with zstd, then decodes every patch and compares the result byte for byte before publishing it. While the updater was being designed, a patch between two near-identical builds measured 1.05 MB against a 60.5 MB APK.
  3. Rebuilt on the tablet. The app rebuilds the new APK from the one already installed and checks its SHA-256. If anything goes wrong, it falls back to the full download.
  4. Checked before install. The checksum must match, the package name must be Marginalia's, the version must be newer, and the signing certificate must match both the pinned release key and the installed app.
  5. Installed on a tap. Checks run in the background on Wi-Fi by default, but the install waits for the user and takes a database snapshot first, so the app never restarts in the middle of a note.
  6. Switches that ship with the release. A remote config file can turn off AI, auto-sort or handwriting search, and can force an update away from a known-bad version. A file that fails to parse leaves the last good config in place.

Built with

Kotlin, Jetpack Compose, Hilt, Room, pdfium, and androidx.ink.

Release and automated checks

Release Please ships signed APKs, and every pull request runs the emulator suite.

Tests exercise database migrations, lecture CRUD, PDF import, zoom, links, search, and ink editing. Handwriting recognition runs on the device. The app needs no account and no cloud; the AI features are opt-in and send nothing unless asked.