Docs & live demo → isaacrowntree.com/durable-sync · Source → github.com/isaacrowntree/durable-sync (MIT) · npm → durable-sync

Why this exists

If you want offline-first sync in 2026, the credible engines — Zero, Electric, PowerSync — all want Postgres and a long-running container. On an all-Cloudflare stack that’s a second backend to run, forever. They’re genuinely better than this at almost everything; that’s not the point. The point is the tax.

Meanwhile the platform already hands you the hard part for free: a Durable Object is a single-threaded ordering point, per user. That’s the exact thing everyone else reaches for Postgres to get. Give each user their own DO with idFromName(userKey) and write-ordering stops being a distributed-systems problem and becomes a language feature. Once you have that, the rest of “sync” is just an outbox, a cursor, and a great deal of care about what “success” means.

So durable-sync is small on purpose. It’s a primitive, not a database. No conflict resolution — ops are immutable facts appended to a log, and if your writes are events (“this workout happened”) rather than edits, you don’t have a conflict problem. HTTP, not WebSocket — a socket is useless in a basement, and gyms are Faraday cages, so sync happens when the app is open and the network exists. Bring your own IndexedDB.

The four things that are easy to get wrong

Here’s the honest reason this is a package and not a gist. Sync that looks like it works and sync that actually works are separated by a handful of failures that are individually obvious and collectively brutal — because every one of them fails silently. Each of these shipped to production in the app this came from:

• res.ok is not evidence. Behind an auth proxy like Cloudflare Access, an expired session redirects to a same-origin login page — which fetch quietly follows and reports as a 200. Drain your outbox on res.ok and you’ve just deleted writes that never reached the server. durable-sync validates that a reply actually came from the journal before it touches the queue.
• A cursor only means something against the log that issued it. Reset the log and every client is holding a sequence number from a log that no longer exists — usually pointing past the rebuilt one, so seq > cursor matches nothing and the client silently never syncs again. Every pull carries an epoch; a client that sees a new one replays from zero. Apply is idempotent, so replay is cheap.
• Pulling is not always safe. In Rampset, a remote op landing mid-workout rewrote the working weight that the finish logic reads back — and silently dropped a 5×5 to a 3×5. Pushing is always safe; pulling isn’t. A canPull() gate defers the pull while the user is in the middle of something, and eventual consistency makes waiting free.
• The gate has to be the only door. The journal is addressed by a server-side identity while the ops carry whatever the client selected — so writing as the wrong one files data under someone else, permanently, in an append-only log. The engine has a canWrite() gate; the transport that could bypass it simply isn’t exported. There is one way in.

None of these are things you’d think to test for until they’ve bitten you. That scar tissue is the actual product.

What you write

The server is a Durable Object you extend and export. Its methods are native DO RPC — you call them on the stub, typed, with no request-building in between:

// worker.ts
import { SyncJournal } from "durable-sync/server";
export class Journal extends SyncJournal {}

// your route — forward exactly the methods a client should reach
export async function POST(req: Request) {
  const { ops } = await req.json();
  const journal = env.JOURNAL.get(env.JOURNAL.idFromName(userKey));
  return Response.json(await journal.push(ops));
}

Note what you don’t forward: reset(). The DO has it, but a client reaches only the methods you wire to a route — that’s the whole access model, no router second-guessing you. The client is local-first: commit to IndexedDB, queue the op, let the network catch up.

import { createSync, localStorageCursor } from "durable-sync/client";

export const sync = createSync({
  endpoint: "/api/sync",
  outbox: dexieOutbox(db.outbox),          // durable — it may hold the only copy
  cursor: localStorageCursor("myapp.cursor"),
  async apply(op) { /* idempotent: an op can arrive twice */ },
  canPull: async () => !(await somethingInProgress()),
});

There’s a runnable example in the repo — a Worker plus a browser client with a real IndexedDB outbox — and a live demo on the docs site where you can cut the network, watch writes pile up in the outbox with no sequence number, then reconnect and watch them drain. That widget is the library.

When to use something else

Being clear so you don’t adopt it and find out: no conflict resolution, no pagination (a pull returns everything after the cursor in one response — fine for thousands of ops, not millions), no live push, no auth, and nothing runs while the app is closed because Safari has no Background Sync. If you need those, you want a real sync engine and the Postgres that comes with it — there’s an honest comparison against Zero, Electric, PowerSync and Cloudflare’s own partysync on the docs site. If you need two people editing the same record to merge, you want a CRDT — Yjs or Automerge.

The slice where durable-sync is the right answer is narrow: you’re all-Cloudflare, your writes are events, and the app has to keep working on a train. Inside that slice, it’s a few kilobytes and no second backend.

The lesson

Extracting a library from a working app is a good forcing function: it makes you separate the parts that are genuinely reusable from the parts that were only ever about your problem. What surprised me is how little of the value was in the code. The op log is a hundred lines. The outbox is an interface. Anyone could write those in an afternoon — and then spend the next year discovering, one silent data-loss bug at a time, the four things above.

That year is what’s in the package. The code is small; the scar tissue is the product.

Source → github.com/isaacrowntree/sovereign-ibkr-fund (Apache-2.0 OR MIT) · Built on bezant

Why it exists

I had a portfolio problem that a lot of people quietly have: one winner had run so hard it became 40%+ of the book. Great on the way up, a single point of failure on the way down. Fixing that by hand — trimming the concentration, funding a diversified target, doing it without fat-fingering a real order — is exactly the kind of repetitive, high-stakes, easy-to-get-wrong work you should not be doing manually at 11pm.

So the fund isn’t a get-rich bot. It’s a discipline engine: hold a target allocation, notice when reality drifts from it, and make the smallest correct trades to close the gap — with enough guardrails that a bad market-data tick or a logic bug can’t do real damage.

bezant already gave every language typed access to IBKR’s Client Portal API. Sovereign is what happens when you build an actual fund on that foundation and take the “it’s real money” part seriously.

Nine agents, no LLM calls

The agents are plain TypeScript --once processes — deterministic, no model calls in the loop. That’s deliberate: I want a trade decision to be a pure function of the inputs, reproducible and auditable, not a sample from a distribution.

Under the hood there’s a real quant toolbox: Hierarchical Risk Parity, Black-Litterman, risk-parity, Ledoit-Wolf shrinkage covariance, a regime overlay, and vol targeting — all backtestable.

The guardrails are the point

Anyone can write a loop that places market orders. The interesting engineering is everything that stops it from doing something stupid with real money:

• Validation-first execution. Before it will batch a rebalance, the executor proves a live fill on the single smallest order and confirms it against IBKR’s own execution records. No confirmed fill, no batch.
• Executions are authoritative. Fills are reconciled against IBKR’s execution log, and the trade ledger is idempotent — the same fill can never be recorded twice, even if a confirmation arrives by two paths.
• Hard caps. Absolute backstops on per-order notional, per-order % of NAV, and per-run notional — independent of the sizing math. A garbled input can’t size a monster order.
• Data-sanity gates. If NAV or a price tick looks impossible (zeroed, or a 100× move with no cash flow), the strategist refuses to generate orders that cycle rather than trade against garbage.
• Drawdown control. De-risk and hard-stop thresholds that pull exposure down when the book is bleeding.
• State lives outside the checkout. Positions and ledger sit in STATE_DIR, never entangled with the code — so a deploy can never clobber your holdings.

Most of these exist because the honest way to build this is to assume your own code will misbehave and make sure the blast radius is bounded when it does.

Standalone, or under whatever you run

Every agent is just node dist/agents/<name>.js --once. That one contract means Sovereign doesn’t care how it’s scheduled:

• Built-in scheduler — npm start runs the whole fund on a cadence, zero dependencies.
• cron / systemd — point timers at the --once scripts; examples in deploy/.
• Any orchestrator — set ENABLE_SCHEDULER=false and let your platform drive the same scripts.

The core never imports the scheduler, so it genuinely runs both ways.

Your book stays yours

The public repo ships a generic sample portfolio (a diversified ETF template) and runs against paper out of the box. Your real allocation goes in a gitignored src/portfolios/local.ts that takes precedence automatically and never leaves your machine. Everything else — caps, thresholds, cadences, optimizer choice — is environment-driven. Nothing about your positions lives in the source.

Backtesting

There’s a full backtest engine (HRP, risk-parity, Black-Litterman, regime overlay, vol targeting). The historical dataset is gitignored — you generate it yourself from Yahoo Finance with npm run fetch-data, and the backtest suites skip cleanly until it exists, so a fresh clone is green on the first npm test.

Status and licensing

• v0.1 — runs end-to-end against IBKR paper accounts; the API and agent set will evolve.
• Dual-licensed Apache-2.0 OR MIT.
• Requires a running bezant gateway — that’s how it talks to IBKR.
• Not affiliated with Interactive Brokers. This is not financial advice. It places real trades — start on paper, and understand every guardrail before you flip TRADING_MODE=live.

If bezant was about making IBKR programmable, Sovereign is about making a portfolio governable — trading on rules you can read, with brakes you can trust. If you’re running money through IBKR and you’d rather it followed a written policy than your 11pm instincts, clone it and point it at your own bezant. Contributions welcome — especially on the optimizers and the risk engine.

Site & guide → isaacrowntree.github.io/rampset · Source → github.com/isaacrowntree/rampset (MIT)

Why this exists

I was a StrongLifts user from 2015 to 2026 — 1,221 logged workouts, a grandfathered subscription I’d held since 2018, and honestly no complaints for over a decade. It did the one thing a 5×5 app has to do: tell me what to lift today and remember what I lifted yesterday.

Then a sign-in bug locked me out of my own subscription. I did the support dance — reinstalled the app, removed and re-added every Google account on the phone, followed every step of every linked help article, sent screenshots. After a morning of back-and-forth, support resolved it their way: they cancelled my subscription. I hadn’t asked for that. The legacy plan I’d been quietly grandfathered on for years ceased to exist the moment it was cancelled, and the only path back was the shiny new trial at roughly six times my old price.

Well — screw that. I write software for a living, my workout history exports to CSV, and it’s 2026: with Claude Code in the loop, “I’ll just build it myself” is no longer a threat you mutter into an email draft and delete. It’s a Saturday.

Three ways to train

The interesting design constraint wasn’t me — it was that my wife trains too, and her program is nothing like mine. That forced a better architecture than a clone would have had, and it’s why Rampset ships with three shapes on one engine:

• Program mode — classic StrongLifts-style 5×5, A/B, with variants from Lite to Ultra Max. The app prescribes: tap a plate-shaped circle to log a set, warm-ups ramp with per-side plate math, +2.5 kg linear progression, graduated deloads after time off, and the full stall protocol (5×5 → 3×5 → 1×5).
• Madcow mode — weekly ramped 5×5: heavy / light / intensity days, back-off sets, and a Friday PR set that sets next week’s top weight.
• Routine mode — a Strong-style layout: exercise cards with set rows (previous · kg · reps · ✓), everything prefilled from the last session, per-exercise rest timers, timed and bodyweight sets. You prescribe; the app remembers.

Same schema, same logging engine, same charts — the mode is just a flag on the program. Both of our full histories came in through CSV importers for the two incumbent apps’ export formats, auto-detected and idempotent, verified against the real files. And export gives it all back whenever you want — no lock-in is the whole point.

The parts I’m fond of

• Offline-first for real. Gyms are Faraday cages. IndexedDB is the source of truth on-device; the service worker keeps the shell alive; a screen wake-lock holds the display on mid-workout; and a rest timer keeps counting on a wall-clock deadline even when the phone locks, then rings a WebAudio bell it synthesises itself. No signal just means sync happens later.
• Sync without a database server. Each person gets their own SQLite-backed Durable Object — a single-threaded, per-user journal that makes write ordering a non-problem instead of a distributed-systems problem. Finished workouts push as idempotent ops; fresh devices pull. R2 holds dated snapshots underneath as the disaster layer.
• No auth code, no personal data in the repo. Identity is handled entirely by Cloudflare Access (a free zero-trust login) — the app itself contains zero auth code. Lifters are defined by an env var that’s gitignored; the committed code carries only generic program templates. Nothing about you or your training lives in the source.
• TDD the whole way. 240 tests: the progression engine, both CSV dialects, the sync journal, backup round-trips, even “a rest timer survives navigating away mid-countdown.” The engines are pure functions in src/lib/, each with a failing-test-first workflow waiting — because editing them is the point.
• It feels like an app. OLED-black UI, floating dock, haptic ticks on set logging, sheets that close with the Android back gesture, splash screens, home-screen shortcuts. The bar for “doesn’t feel like a website” is a hundred small details, and a multi-agent review fleet is very good at finding all hundred.

Run your own

Rampset is built to be yours. Clone it, point it at your lifters, and either use it locally or deploy your own copy to Cloudflare:

git clone https://github.com/isaacrowntree/rampset
cd rampset
npm install
cp .env.example .env.local     # your lifters, units, starting weights
npm run dev                    # → http://localhost:3000
npm test                       # the engines, importers, store, components

To put it online, npm run deploy ships it to Cloudflare Workers via the OpenNext adapter; then you add a Cloudflare Access application in front of your Worker and allow your lifters’ emails. Workers and Access are free for a household. The one paid gate is R2 for cloud backups — the data sits inside R2’s 10 GB free tier, but Cloudflare wants a card on file to enable it. Don’t want to add one? Drop the BACKUPS binding: the app is fully offline-first on local IndexedDB, and Settings → Export hands you a complete CSV backup whenever you want.

The lesson

There’s a quiet lesson in this for anyone running a subscription product: your most loyal decade-long customers aren’t locked in by your data-export button being hard to find anymore. They’re one bad support interaction away from an export file, a coding agent, and a very productive Saturday afternoon.

And here’s the part that should really keep you up at night. This time they don’t even have to build it. The export importers, the two proven programs, the offline sync, the plate math — it’s all sitting in a public repo under a licence that says make it yours. Take it to the gym. Take it somewhere no subscription can reach you.

This is the story of how a tool I adopted became a tool I help maintain: how I found it, ran it in production, watched it fall over for a reason that wasn’t really its fault, went looking for help from a company that no longer existed, and ended up forking it, fixing it, and extending it.

Why I reached for Sequin

The problem Sequin solves is the boring, load-bearing kind. The POI, review, and translation data lives in Postgres (on Neon). Search runs on Typesense. Several other services — a translation workflow, a delta cache for the mobile app — need to know the instant a row changes. The naive version of this is a spray of application-level hooks and cron jobs that drift out of sync the moment anything fails silently.

CDC inverts that. Postgres already writes every change to its write-ahead log; Sequin reads the log and fans each change out reliably, with retries and backfills, so the index and the database can’t disagree for long. The whole thing is a dozen sinks driven by a single declarative sequin.yaml, version-controlled and applied from CI:

   Postgres (Neon)  →  Sequin  →  Typesense collections (POIs, reviews, translations)
   logical slot        transforms →  Webhooks (translation pipeline, delta sync)

The transforms are the nice part. A small Elixir function denormalises a POI’s feature list into boolean columns, builds language-suffixed fields (description_en, description_mi) from a tall translations table, and filters out non-public rows before they ever reach the public index. It’s the right amount of logic in the right place, and for a good while it just worked.

The night Dragonfly took Sequin with it

Then came outages that made no sense. Sequin would be humming along, and then — with no deploy, no traffic spike, no obvious cause — every consumer would stop at once. The sinks would go cold, the index would fall behind, and the only fix was a restart.

The correlation, once I traced it, was infuriating: it happened whenever Dragonfly — the Redis-compatible store Sequin uses for coordination, running as a managed service on Railway — redeployed itself. A routine maintenance update to a dependency was taking down the whole engine.

The mechanism is a textbook Erlang supervision-tree footgun. Sequin uses a Redis-backed mutex to elect a single leader across nodes — a MutexOwner GenServer that holds a lock and refreshes it before it expires. When Dragonfly restarted, the connection blipped, the mutex refresh failed, and MutexOwner did the most literal possible thing: it crashed. And because it sits under a supervisor with a :one_for_all restart strategy, its death took every sibling down with it — the entire runtime supervisor, all consumers, all sinks. A two-second Redis blip became a total outage that only a human restart would clear.

MutexedSupervisor (:one_for_all)
  └── MutexOwner  ✗  Redis blips → mutex refresh fails → crash
        ⇒ :one_for_all fires ⇒ every consumer & sink is torn down with it

That’s not really Sequin doing something wrong so much as an assumption — “Redis is always there” — that doesn’t hold on a platform where your Redis can redeploy under you at any moment.

Upstream had gone dark

So I did the normal thing: went to fix it upstream, or at least to ask. And found the lights off. The project had moved into maintenance mode, the company behind Sequin had wound down, and there was no one on the other end of the issue tracker to merge a patch or ship a release. A tool at the centre of a data pipeline had, effectively, been orphaned.

This is the quiet risk of building on someone else’s open source: the licence guarantees you the code, but nothing guarantees you a maintainer. When the maintainer disappears, you have exactly two choices — rip the dependency out, or adopt it.

So I adopted it

Ripping out CDC and rebuilding the sink pipeline from scratch would have been weeks of work to end up back where I started. Adoption was the better trade. The project got forked into github.com/triptechtravel/sequin, with its own build and release pipeline, and from then on it was treated as what it now was: code I own.

That meant the unglamorous infrastructure of ownership. A GitHub Actions workflow that builds a patched image and pushes it to GHCR. Deployment to Railway. Fixing the parts of the build that assumed a corporate CI — a missing cmake for a Kafka NIF, a Sentry DSN that was baked in at build time and now had to be optional. None of it is exciting. All of it is the price of being the maintainer instead of a user.

Fixing the crash properly

With the fork in hand, the Dragonfly bug got fixed at the root. MutexOwner no longer treats a Redis error as fatal. While it holds the mutex and Redis becomes unreachable, it now retries indefinitely with exponential backoff (capped at an hour) instead of crashing — Redis going down should degrade Sequin gracefully, never take it out. When Redis comes back, it re-acquires the lock and resumes as if nothing happened. The invalid GenStateMachine stop value that caused the original crash got corrected too, and the LiveView metrics pages were hardened so a Redis blip renders an empty chart instead of a MatchError.

The part I’m most pleased with is the test. It’s easy to write a unit test that mocks a Redis error; it’s much more convincing to simulate the actual failure. The integration test uses iptables to REJECT traffic to Redis mid-run — a real network partition, the same thing a Dragonfly redeploy looks like from the process’s point of view — and asserts that the MutexOwner survives the outage and recovers when the rule is dropped. That’s the difference between “handles a mocked error” and “survives the thing that was actually paging me.”

The outages stopped.

Then it went behind Cloudflare Access

Once you own a fork, you stop just patching it and start shaping it. The most recent addition: real SSO on the admin console.

Out of the box, self-hosted Sequin authenticates users with an email-and-password login sitting in its own Postgres table. For an internal tool that a whole team touches, that’s the wrong model — there’s already Google identity and Cloudflare Zero Trust in front of everything else. So the Sequin console went behind Cloudflare Access, and Sequin learned to trust it.

The mechanics, mirroring the same trusted-header pattern I’ve used for a Payload CMS:

• Cloudflare Access gates the console with a Google-SSO policy. On every request it forwards, it injects a signed JWT in the Cf-Access-Jwt-Assertion header.
• A new Elixir plug verifies that JWT — fetching the Access application’s public keys (JWKS), checking the signature, issuer, audience, and expiry — and then transparently signs the user in. First time through, it provisions the user just-in-time from the verified email, adopting any existing account so nobody lands in an empty instance. You never see Sequin’s own login screen.
• The tricky part is machine traffic. The search config is applied from CI, which authenticates with a token rather than a browser SSO session. Cloudflare Access lets you scope policies so interactive console traffic goes through Google while automated, token-authenticated callers are validated on their own credentials — so the SSO gate never breaks the deploy pipeline.
• Finally, the settings UI now reflects reality: it shows which identity provider you authenticated with and disables the email/password fields for SSO users, rather than presenting a dead form.

The whole thing is feature-flagged, so the upstream password-login behaviour is still the default for anyone else running the code. It ships as a normal patched image through the same GHCR-to-Railway pipeline as every other fix.

Owning a fork you didn’t write

There’s a version of this story that reads as a cautionary tale about depending on startups. I don’t think that’s the lesson. Sequin was — is — a genuinely good piece of engineering, and the fact that it could be adopted, read, fixed, and extended with SSO is entirely because it was open source. A closed SaaS that shut down would have left nothing but a migration deadline.

The real lesson is that “using open source” and “owning open source” are different commitments, and the gap between them can close overnight. When it does, the codebases you can actually take over are the ones written clearly enough to understand under pressure. Sequin was. You read the supervision tree, see why a Redis blip cascaded, and fix it — in someone else’s code that has quietly become yours.

If you’re travelling Australia or New Zealand, the search that lands you at the right campsite is riding on this pipeline. Grab CamperMate on iOS or Android — free, no account required.

Header photo by v2osk on Unsplash.

This is the pipeline I built to ship offline basemaps for CamperMate — the go-to free-camping and campground app across Australia and New Zealand, iOS and Android, 1M+ downloads, made at Triptech Travel. Users are in Fiordland, Kakadu, the Pilbara, the Tasmanian highlands. Cell coverage is a luxury, not a baseline. If the map doesn’t work without bars, the app doesn’t work. The pipeline below is platform-agnostic — the output is a .mbtiles SQLite file that any client can read. I’ll walk through how it ships in a React Native consumer at the end, but the pipeline itself is independent of where the bytes are rendered.

The wrong path: Mapnik with OSM-Carto

The first thing every “offline OSM tiles” guide tells you is to spin up overv/openstreetmap-tile-server — a Docker container with osm2pgsql, PostGIS, and Mapnik rendering the canonical openstreetmap-carto style. That’s what powers openstreetmap.org.

I tried it. The pipeline works, but the output looks like 2013. Olive landuse fills, mustard buildings, brick-coloured motorways, that classic OSM look that every modern map product has moved on from. It’s not what people expect when they tap “offline maps” in 2026.

It’s also a single-stage pipeline that’s deceptively hard to evolve. Want to tweak the aesthetic? You’re editing CartoCSS and re-baking from PostGIS. Want a different style entirely? You’re rebuilding the whole stack. Mapnik is excellent at what it does, but what it does is render in a tradition that no longer matches what mobile users see daily on Apple Maps and Google Maps.

The right path: vector → raster with MapLibre GL Native

The trick is to split rendering from data extraction:

                 (one-time per region)              (per style)
                       ↓                                ↓
   OSM PBF  →  planetiler  →  vector MBTiles  →  tileserver-gl  →  raster MBTiles
                                  (single source of truth)            (re-renderable
                                                                       any time)

Two stages. The vector MBTiles is a neutral intermediate — same data, no styling. The raster MBTiles is what your app loads. You can re-render the raster in any MapLibre GL style — Positron, OSM Bright, Voyager, Dark Matter, a custom one — without touching the data pipeline.

Stage 1 (planetiler) is minutes. Stage 2 (tileserver-gl) is CPU-bound rendering — minutes for a city, hours for a country. Both run from Docker, both are open source, neither requires a third-party API key.

The rendering engine is MapLibre GL Native, the same C++ engine that powers Mapbox GL JS and MapLibre GL JS on the web. That’s why the output looks identical to a modern web map — because it is a modern web map, rendered offline.

The tools

All free. No keys. No bills. The whole stack runs on a MacBook.

The build script

The CamperMate offline-tiles build script is ~200 lines of bash that wires those tools together. Inputs: a region name, a Geofabrik path, a bbox, a max-zoom, a style name. Output: a single .mbtiles file ready to upload.

# NZ South Island, z0–15, rendered in OSM Bright
scripts/build-offline-tiles.sh nz-south \
  australia-oceania/new-zealand \
  '166.4,-47.3,174.5,-40.4' \
  15 \
  osm-bright

The pipeline:

# 1. Cache the source PBF (one-time per Geofabrik region)
curl -fL -o offline-tiles/pbf/nz.osm.pbf \
  https://download.geofabrik.de/australia-oceania/new-zealand-latest.osm.pbf

# 2. Slice by bbox (skipped when Geofabrik already has per-state PBFs)
osmium extract --bbox=166.4,-47.3,174.5,-40.4 --strategy=smart --set-bounds \
  -o offline-tiles/pbf/nz-south-extract.osm.pbf \
  offline-tiles/pbf/nz.osm.pbf

# 3. Generate vector MBTiles with planetiler (OpenMapTiles schema)
docker run --rm -e JAVA_TOOL_OPTIONS="-Xmx4g" -v offline-tiles:/data \
  ghcr.io/onthegomap/planetiler:latest \
    --osm_path=/data/pbf/nz-south-extract.osm.pbf \
    --mbtiles=/data/nz-south-vector.mbtiles \
    --bounds=166.4,-47.3,174.5,-40.4 --maxzoom=15 --download --force

# 4. Render vector → raster via tileserver-gl
docker run -d --name tileserver-gl-nz-south -p 8765:8080 \
  -v offline-tiles:/data \
  maptiler/tileserver-gl:latest \
    -c /data/tileserver-config-nz-south.json

# 5. curl-loop every tile in the bbox; pack into raster MBTiles
python3 render_and_pack.py nz-south '166.4,-47.3,174.5,-40.4' 15

A few non-obvious things that took me a day to learn:

• Planetiler needs Java 21+. If you have Zulu 17 installed for Android dev you’ll see UnsupportedClassVersionError: class file version 65.0. The Docker image avoids the JDK juggle.
• OpenMapTiles styles ship with Maptiler-hosted source URLs. The default Positron style.json points at api.maptiler.com and needs a key. Rewrite sources.openmaptiles.url to mbtiles://{openmaptiles} and let tileserver-gl resolve it from the local MBTiles: jq '.sources.openmaptiles = { type: "vector", url: "mbtiles://{openmaptiles}" }' positron.json > positron.local.json.
• Fonts are not in the openmaptiles/fonts master branch. Master ships only TTF sources. The pre-built PBF glyph ranges are in the v2.0 release asset. Without them tileserver-gl 500s on every tile containing a label, which is everything past z4.
• Planetiler writes bounds and center metadata that breaks MapLibre GL Native. Strip them after planetiler runs: sqlite3 *.mbtiles "DELETE FROM metadata WHERE name IN ('bounds', 'center');".

Shipping it in a React Native app

The pipeline above is platform-agnostic — the output is just an MBTiles file. Web clients can read it via MapLibre GL JS + the mbtiles protocol plugin. Native iOS / Android can read it via their SQLite stack directly. Flutter has flutter_map with MBTiles plugins. The thing that needs care is how the consumer reads tile bytes from the archive.

For CamperMate’s React Native app, the existing map stack is react-native-maps, which wraps Google Maps (Android) and Apple MapKit (iOS). Both expose a <UrlTile> primitive — but it expects an HTTP URL template:

<UrlTile urlTemplate="https://server/{z}/{x}/{y}.png" />

That’s fine for online tile servers. For an offline .mbtiles archive, there are three obvious options, all bad:

1. Pre-extract {z}/{x}/{y}.png files and use <LocalTile>. Loses MBTiles’ single-file storage win and doesn’t work over a CDN.
2. Run a localhost HTTP server inside the app that serves tiles from the archive on demand. Adds startup cost, port management, battery, and JS-bridge contention per tile.
3. Switch to MapLibre RN. Solves the problem natively. But it’s an entire map-view replacement, losing every line of code that touches markers, callouts, gesture handlers, and providers.

The fourth option — and the one I shipped — is a small native patch to react-native-maps that teaches <UrlTile> to read tile bytes directly from an MBTiles SQLite file via a custom mbtiles:// URL scheme. The JSX surface stays identical:

<UrlTile
  urlTemplate="mbtiles:///var/.../offline/nz-north.mbtiles"
  maximumNativeZ={15}
  maximumZ={18}
  shouldReplaceMapContent
/>

The patch is ~750 lines across iOS and Android, applied via patch-package. It teaches MapTileProvider (Android) and AIRMapUrlTile (iOS) to detect the mbtiles:// URL scheme and route to a new SQLite-backed tile reader instead of the HTTP path. The internals — connection caching, TMS y-flip, overzoom via in-memory parent-bitmap reuse — are a separate post. The user-facing surface is exactly the snippet above. I’ll open-source the patch once it’s been in production for a few weeks; issue #5863 tracks it.

Region splits and zoom levels

Two practical decisions shape the file layout. Where to split comes from how Geofabrik ships data: country-level PBFs for NZ (split by bbox into north/south islands with osmium extract), per-state PBFs for AU (no slicing needed). The split should also match how users travel — for a campervan app, per-island and per-state is the right grain because that’s what people fly between.

How deep to render is the other consequential decision. Each zoom level quadruples tile count, and real-world size grows faster than the math suggests because inked tiles compress worse than empty ones. I shipped NZ at native z15 (full Apple-Maps-style detail: trail heads, suburb names, motorway shields, ~420 MB per island after the optimisations below). AU at native z14 with overzoom (the patch stretches the largest available tile up to z18) is a 4× saving across an entire continent — road names still readable, dense urban POI labels the only loss. The asymmetry is deliberate: NZ is small enough that z15 doesn’t blow up storage, AU isn’t.

The dedup schema — 50% savings for free

The MBTiles spec defines two acceptable schemas. The naive one — a single tiles(zoom_level, tile_column, tile_row, tile_data) table — is what most ad-hoc scripts produce. The normalised one trades a tiny bit of read complexity for massive storage savings:

CREATE TABLE images (tile_id TEXT PRIMARY KEY, tile_data BLOB);
CREATE TABLE map (zoom_level, tile_column, tile_row, tile_id);
CREATE UNIQUE INDEX map_index ON map (zoom_level, tile_column, tile_row);
CREATE VIEW tiles AS
  SELECT map.zoom_level, map.tile_column, map.tile_row, images.tile_data
  FROM map JOIN images ON images.tile_id = map.tile_id;

tile_id is sha1(tile_data). Identical tiles — every “pure ocean” tile, every patch of empty desert at mid-zoom, every uniform Southern Alps slope at z15 — collapse to one row in images, with many rows in map pointing at the same tile_id.

The tiles VIEW makes this completely transparent to consumers. Any SELECT tile_data FROM tiles WHERE zoom_level=? AND tile_column=? AND tile_row=? works identically against either schema.

The measured impact on NZ (PNG tiles, before the WebP step below):

• nz-north: 716,859 tiles → 1.9 GB on disk (51% saving over flat schema)
• nz-south: 859,891 tiles → 242,217 unique blobs (71.8% tile dedup rate), 1.8 GB on disk (57% saving)

Why so high? A region the size of New Zealand has enormous repetition at mid-zooms — endless ocean tiles, identical bush-cover tiles in the Fiordland interior, hundreds of identical “purple Southern Alps shading” tiles. Dense urban tiles (Auckland CBD) are all unique and don’t dedup, but they’re a small fraction of any region’s total tile count.

Hashing every tile during pack adds CPU but it’s microseconds per tile — invisible compared to the actual rendering time. Reading via the VIEW adds one indexed JOIN which doesn’t measurably affect tile-fetch latency on mobile.

WebP, not PNG — another ~5× shrink

The next surprise was the format choice. PNG is what tileserver-gl emits and what every MBTiles tutorial uses, but PNG is the wrong codec for inked map tiles. Roads, anti-aliased coastlines, gradient hillshading, transparent green parks — none of it palettises well, which is what PNG’s compression relies on. WebP’s lossy mode is designed for exactly this kind of mixed graphical content.

I sampled 1,000 random unique tiles from the dedup-packed TAS archive and compressed each as PNG (baseline), pngquant --quality 75-95, and WebP at four qualities:

WebP at q80 beats pngquant at every setting tested. The visual difference at street zoom is invisible — labels stay crisp, terrain shading stays smooth. The end-to-end re-render of TAS confirmed it: 376 MB → 61 MB.

The pipeline change is one line: after fetching the rendered PNG from tileserver-gl, pipe it through cwebp -q 80 before hashing and inserting into the images table. Update the MBTiles format metadata from png to webp so the spec stays honest; consumers that ignore that field (like my native patch, which passes raw bytes straight to UIImage / BitmapFactory) don’t notice the change. Both platforms have decoded WebP natively for years — iOS 14+, Android API 14+.

End-to-end size for all 9 ANZ regions, walking through the optimisations:

About 9× smaller than the naive starting point, and within rounding error of the legacy ZIP-tier total CamperMate already shipped — the “5× bigger download” story is gone.

R2 cost: ~$0.04/month storage for the whole tier, and egress to devices is free — the killer feature R2 has over S3. A user who only ever visits Tasmania downloads 61 MB once, free, never pays storage either. The “I’m doing all of NSW” worst case is now 305 MB. The biggest single download in the tier is the North Island at 444 MB.

Style picks

For CamperMate I tested the free OpenMapTiles styles. All open-licensed, all render against the same vector MBTiles:

• Positron — minimal, white, designed as a backdrop for other content. Beautiful but wrong for an “offline map replacement” use case where the map is the content.
• OSM Bright — what I shipped with. Coloured roads, green parks, blue water, motorway shields, full POI labels. Reads like Apple Maps in light mode.
• Dark Matter — dark-mode equivalent of Positron. Future option for a night-mode toggle.

The aesthetic decision changes which file you ship to users; it doesn’t change anything upstream. Vector MBTiles → re-render → upload. Hours, not days.

Wrapping up

If you’re building any kind of outdoor, overland, or regional travel app and your users care about offline coverage, this pipeline is repeatable. The tools are mature, the licensing is permissive (OSM is ODbL, the styles are BSD/MIT, planetiler is Apache-2, tileserver-gl is BSD-2), the storage is cheap, and the aesthetic is finally something you can put in a shipping app without an apology.

If you’re heading to Australia or New Zealand and want to see the pipeline in production, grab CamperMate on iOS or Android — free, no account required, offline maps under the “Downloads” tab. Your offline maps don’t have to look like 2013 anymore.

Header photo by Marek Piwnicki on Unsplash.

Why this exists

I take a lot of product photos for eBay listings — bike parts, electronics, miscellaneous resale. The iPhone in my pocket has a vastly better camera than my MacBook’s built-in webcam, but the friction of “shoot on phone → AirDrop → import to listing tool” was killing the throughput. Existing wireless tether tools either want a subscription, push photos through someone else’s cloud, or are tied to a specific desktop app I don’t use.

Shutterdrop is the smallest possible thing that solves the problem: tap shutter, file shows up. That’s it. The receiver writes straight to a watched folder, so whatever workflow you already have (Finder smart folder, Hazel rule, Lightroom auto-import, eBay listing CLI) just sees new files appear.

What it’s like to use

1. Start the receiver on your Mac. It prints a 6-digit pairing code in the terminal.
2. Open the Shutterdrop app on your phone. It finds your Mac on the wifi automatically and asks for the code.
3. Type the code once. You’re paired forever — your phone remembers your Mac.
4. Frame the shot, tap anywhere on the camera preview, and a moment later the photo appears in ~/Pictures/Shutterdrop/ on your Mac. Drag it straight into your eBay listing, your Lightroom catalogue, or wherever you already work.

If you walk out of wifi range mid-shoot, captures queue up on the phone and flush as soon as you’re back online. Nothing gets lost.

What’s in it

• iPhone app for iOS 17+, with a manual lens picker on Pro phones (0.5× / 1× / 3×) and a built-in torch toggle. Photos are HEIC at full quality.
• Android app for Android 8 and up. JPEG capture, edge-to-edge layout, accessible to TalkBack screen readers.
• A small Mac receiver written in Python. It runs in the background, advertises itself on the local network, and drops every incoming photo into a folder of your choice. Linux works too.
• Pairing is private. A one-time 6-digit code shown on your Mac, with rate limits and a 5-minute window so nobody on the same wifi can guess their way in. The shared key lives in your phone’s secure storage (iOS Keychain or Android EncryptedSharedPreferences).

Status

Working end-to-end on both iPhone and Android, with an automated test suite for the Mac receiver that runs on every push. The wire protocol between phone and Mac is small enough that you could write your own receiver — drop incoming photos into S3, pipe them through pngcrush, auto-import to Lightroom, whatever you want. MIT-licensed, source on GitHub.

Under the hood (for the curious)

Phone (iOS or Android)              Mac (or Linux)
┌───────────────────────┐           ┌────────────────────────┐
│ Camera preview        │  HTTP     │ receiver.py            │   drop
│ Tap-to-capture (HEIC  ├──over────▶│ (Python stdlib +       ├──────▶  ~/Pictures/Shutterdrop/
│  on iOS / JPEG on     │  LAN +    │  zeroconf)             │
│  Android)             │  Bonjour  │ advertises             │
│ Offline outbox        │           │ _shutterdrop._tcp      │
│ Bonjour discovery     │           └────────────────────────┘
└───────────────────────┘

Three endpoints, that’s the whole protocol:

GET  /health  → {"ok":true}                          unauthenticated
POST /pair    → {"code":"123456","peerName":"…"}     returns {"secret","peer"}
POST /submit  → multipart/form-data, "photo" part, Bearer auth required

Build details and architecture notes are in the README.

Why it exists

Interactive Brokers’ Client Portal Web API (CPAPI) is the gateway most retail-adjacent trading tools reach for — it covers accounts, positions, orders, market data, watchlists, scanners, PnL, and more. The surface area is 155 paths, 167 methods, 1030 types. The official docs ship an OpenAPI spec, but the spec has real-world quirks: missing or duplicate operationIds, malformed security[] blocks, integer fields with floating-point example values, and a few other gremlins that break naive code generators.

Bezant vendors that spec, normalises it through a 13-step pipeline, and regenerates every client surface from a single command. When IBKR revises the spec, one ./scripts/codegen.sh re-runs the whole thing and every language/runtime updates together.

Five surfaces, one spec

The MCP surface is the one that surprised us the most. Once it was there, driving IBKR from a conversation — “what are my open positions in my paper account?” — became a single /plugin install away. The same spec drove the typed Rust client, the CLI, and the TypeScript package. Zero duplication.

Rust, because it earns the weight

Rust is new to our open-source lineup. We chose it for bezant specifically because:

• A long-running trading session wants to not crash. Rust’s memory safety and absence of GC pauses feel right for code that holds an authenticated session, streams over a WebSocket, and needs to keepalive a 5-minute-expiring cookie cleanly.
• reqwest + tokio is genuinely pleasant. Strong types end-to-end, async streaming via tokio-tungstenite, and error handling via thiserror — the Rust HTTP/WebSocket story in 2026 is excellent.
• Codegen is unforgiving. When you regenerate a client from a noisy third-party spec, the compiler catches mismatches the moment you rebuild. Dynamic languages find out at runtime.

The ergonomic facade in bezant-core sits on top of the raw generated client so callers don’t have to think about method-naming quirks or type re-wrapping:

use std::time::Duration;

#[tokio::main]
async fn main() -> bezant::Result<()> {
    let client = bezant::Client::new("https://localhost:5000/v1/api")?;
    let _keepalive = client.spawn_keepalive(Duration::from_secs(60));
    client.health().await?;

    let positions = client.all_positions("DU123456").await?;
    let aapl = bezant::SymbolCache::new(client).conid_for("AAPL").await?;
    println!("{} positions; AAPL = conid {aapl}", positions.len());
    Ok(())
}

The spec-normalisation pipeline

The most unexpectedly interesting piece of this project is the 13-step spec-normalisation pipeline. IBKR’s published OpenAPI isn’t wrong — it’s realistic. Real specs have duplicate operation IDs, missing required fields, and security definitions that don’t validate.

Rather than patch-forward into our codegen, bezant normalises the spec before codegen runs. Each step is idempotent and documented:

1. Add missing operationIds deterministically from path + method
2. De-duplicate the operationIds that IBKR repeats
3. Repair malformed security[] blocks
4. Coerce integer fields with float example values
5. Upgrade OAS 3.0 → 3.1 where it matters for our generator
6. …and eight more

The output is a clean, modern OpenAPI 3.1 document that every downstream generator can consume without complaint. The full pipeline is documented at Spec normalisation — if you have your own fights with a gnarly third-party spec, the pattern is worth stealing.

Testing against reality

34 tests across the workspace, all green in CI:

• Unit for the facade and the CLI
• Snapshot tests keyed to real IBKR example payloads — catches upstream spec drift before users feel it
• Integration against wiremock for fault-injection (session expiry, 5xx retries)
• End-to-end through Docker Compose against a mocked Gateway

The Docker Compose quickstart is one command: docker compose up, log in to the IBKR Gateway once in a browser, and the HTTP sidecar is live on http://localhost:8080.

MCP: IBKR as a tool for Claude

One of the weirder, more fun surfaces is bezant-mcp — a Model Context Protocol server that exposes IBKR endpoints as MCP tools. Drop it into Claude Code or Cursor, and you can ask “show me the PnL on my paper account this week” and the model drives the actual CPAPI to answer. The MCP tools are generated from the same spec, so new IBKR endpoints become new MCP tools automatically.

Status and licensing

• Alpha — v0.1. Works end-to-end against IBKR paper accounts; API surface will evolve until v1.0
• Dual-licensed MIT / Apache-2.0 following Rust ecosystem convention
• Not affiliated with Interactive Brokers — the vendored spec is IBKR’s IP, included under fair-use for interoperability
• Docs: isaacrowntree.github.io/bezant
• Source: github.com/isaacrowntree/bezant

If you’re building a trading bot, an analytics tool, an AI-assistant-with-broker-access, or anything that wants typed access to IBKR without the PDF-reading phase — bezant is waiting. Contributions welcome, especially on the spec-normaliser and on new client languages.

What SessionHQ does

SessionHQ replaces the spreadsheets, paper sign-in sheets, and duct-taped Mindbody workarounds that most small studios tolerate because the alternatives are too expensive, too clunky, or too generic. We built it by sitting at the front desk on a Tuesday night and asking, “what actually needs to happen here?”

The answer, it turns out, is:

• Members walk in and check in fast. PIN pad, NFC wristband tap, or QR scan from their phone. No app install required. No “where’s my card.”
• Passes just work. Class packs, casual rates, unlimited passes. Credits deduct automatically on check-in. Cards-on-file auto-renew the moment a pack runs out.
• Payments happen where the student is. Square integration handles card payments inline. PCI-compliant. No raw card numbers ever touch our servers.
• Admins see the truth. Tonight’s attendance, revenue, unpaid check-ins, LTV, retention cohorts — all updating in real time.

No per-member fees. No transaction surcharges on top of Square. One flat monthly subscription.

The technology behind it

SessionHQ is a serious piece of software infrastructure. A quick tour of the stack:

• Next.js 16 & React 19 on the frontend, with Tailwind 4 and a custom 19-primitive design system (not shadcn — we wanted the ownership).
• Cloudflare Workers via OpenNext for the runtime. Global edge deployment, sub-100ms cold starts, one Worker cron handling pass-lifecycle, database backup, prune, and retention sweeps.
• Supabase for auth, Postgres, realtime, and row-level security. Every tenant-owned table enforces auth_tenant_id() at the database layer — a studio cannot see another studio’s data, period.
• Square for payments, with Supabase Vault for token storage and PCI-safe tokenisation.
• Resend for lifecycle email, Sentry for observability, R2 for storage, Playwright and Vitest for 800+ tests across unit, integration, and E2E.

Multi-tenancy, GDPR-readiness (consent capture, data export, right-to-erasure, full audit trail), idempotency, rate limiting, feature flags — all in from day one, not bolted on later.

Why we built it

We have spent 20+ years building software for other people. SessionHQ is different: it is our product. We own the roadmap, the pricing, the customer relationship. We decide which features matter. We eat the bug reports.

It is also a proof point. We believe small businesses deserve software that is as thoughtfully engineered as anything the enterprise market gets — without the enterprise price tag, the 12-month implementation, or the 400-page MSA. SessionHQ is our demonstration that a small, focused team can ship serious SaaS.

Founding partner: Havana on the Hastings

SessionHQ did not launch in a vacuum. It launched with a customer.

Havana on the Hastings is Port Macquarie’s Latin dance community — Cuban salsa, bachata, urban kiz, and rueda (the dance that brought founders Mike and Kellie together). They run on passes, practicas, and real connection, with the warmth of a studio where “everyone starts somewhere” is not just a slogan but a weekly reality.

They were already operating on the pass system that SessionHQ is built around. Partnering with them meant we did not have to guess what studio operators needed — we had one telling us, in real time, what worked and what did not. Every feature in SessionHQ has been stress-tested at their front desk on a Tuesday night.

If you are in Port Macquarie and want to dance, drop in. Absolute beginners are welcome every week.

What’s next

SessionHQ is onboarding new studios now. If you run a dance studio, gym, yoga or pilates studio, martial arts school, or climbing gym — or if you know someone who does — we would love to talk.

• Visit sessionhq.org to see the product.
• Request access on the site, or book a 15-minute demo via info@sessionhq.org.
• Founding-studio pricing is locked in for the studios who sign on before general availability.

This is the start of something we are going to spend years building on. Thanks for being here for the beginning.

The architecture, in ASCII

iPhone (ios-app/)                    Mac (mac-app/)                 Python (tools/)
┌───────────────────┐   HTTP over    ┌───────────────────┐   file   ┌─────────────────┐
│ Capture (HEIC)    ├───LAN+Bonjour─▶│ PhoneIngestServer ├──drop───▶│ sam_worker.py   │
│ MotionGate        │                │ (accepts uploads) │          │ SAM 3 + dedup   │
│ Lens picker       │                └───────────────────┘          │ + white balance │
└───────────────────┘                         │                     └────────┬────────┘
                                              │                              │ writes
                                              ▼                              ▼
                                     ┌────────────────────┐         ┌─────────────────────┐
                                     │ SwiftUI library UI │◀──GRDB──│ library.sqlite      │
                                     │ grid · detail      │         │ (~/Library/App Sup) │
                                     │ rotate · identify  │         └──────────▲──────────┘
                                     │ colnect lookup     │                    │ writes
                                     └────────────────────┘                    │
                                                │ spawns                       │
                                                ▼                              │
                                     ┌────────────────────┐                    │
                                     │ orientation_worker │───── Ollama ───────┤
                                     │   (Qwen3-VL)       │                    │
                                     │ colnect_lookup.py  │───── HTTP ─────────┘
                                     └────────────────────┘

The data flow

1. iPhone captures HEIC. MotionGate waits for the phone to be steady (accelerometer settled) before taking the shot, the lens picker selects the macro-capable camera, and the captured HEIC is uploaded over Bonjour/LAN to the paired Mac.
2. Mac receives it. PhoneIngestServer — a SwiftUI app wrapping a tiny HTTP listener — drops the file into .run/sam_inbox/.
3. SAM 3 segments the stamp. sam_worker.py runs the Segment Anything 3 model to cut the stamp out of the page, perceptual-hashes it to detect duplicates already in the library, warps it square, and white-balances against the untouched corners of the page.
4. SQLite writes. The segmented, deduplicated, white-balanced stamp lands in library.sqlite via a GRDB schema.
5. SwiftUI UI renders. The Mac app exposes a grid, a detail view, rotation tools, and “identify” / “Colnect lookup” buttons.
6. Identification is VLM-driven. Hitting “identify” spawns orientation_worker against a local Ollama-hosted Qwen3-VL instance. Hitting “Colnect lookup” queries the Colnect catalogue API for an official ID match.

Why two devices

Because an iPhone’s macro camera + image signal processor is genuinely excellent at stamp-sized subjects — better than a flatbed scanner at 1200 dpi for small dense subjects, and much faster. A Mac, meanwhile, is the right place for the heavy lifting: SAM 3 wants a GPU, the local VLM wants 20 GB of unified memory, and GRDB + SwiftUI want a real filesystem and a large screen. Splitting capture from processing plays to each device’s strengths.

Why local

A stamp collection is personal. You do not want to upload it to a third-party cataloguing service that might vanish in two years or quietly start charging a subscription. Local models, local SQLite, local UI. The only optional outbound call is the Colnect catalogue API, and that is a lookup against their public IDs — no collection data leaves your Mac.

Status

Working end-to-end for single-subject captures, deduplication, rotation, and VLM-based identification. Full architecture and build instructions in the README. If you have a collection that deserves better than a spreadsheet, this is a solid starting point.

It is not a bike-specific script

The 2013 Fuel EX 5 is the first “recipe” — a self-contained config describing one bike, one rider, and a set of candidate parts. Everything is written so you can drop in a new recipe for your own frame and the same fit-check and spring-rate logic runs against it. That is the whole point of the project: a single, testable model of rear-shock dimensions and fitment rules, with as many recipes layered on top as people are willing to contribute.

Who it is for

• DIY mechanics restoring an old MTB frame and trying to work out whether a modern shock will bolt up.
• Ebike converters putting a mid-drive motor on a non-ebike frame and needing to recalculate spring rates for the extra mass and torque.
• Frame hunters cross-checking a secondhand frame’s shock spec against catalog reality before buying.
• Bike shops who want a reusable, forkable model of rear-shock dimensions — the catalog is just TypeScript, extend it for whatever you stock and rerun the tests to lint your inventory against real frames.
• Anyone who has spent hours in a Trek fitment PDF trying to work out whether a shock advertised as “7.25×2.0 imperial” fits their old DRCV mount. (Spoiler: only via a conversion kit.)

What it does

• Bike model. Eye-to-eye, stroke, mount styles, eyelet widths, bolt sizes, leverage ratio, progression, and the frame clearance envelope — all captured in code.
• Shock catalog. Aftermarket shocks modelled as code, with body dimensions, piggyback status, coil spring rate range, Australian sourcing notes, and verified product URLs.
• Fit check. Frame slot × candidate shock returns each dimensional mismatch separately — eye-to-eye, stroke, upper/lower eyelet width, bolt sizes, mount styles, body length, body diameter, reservoir clearance. No yes/no black boxes.
• Conversion kits. Kits that rewrite a shock’s mounting hardware are modelled as functions that transform a candidate. So you can ask “does this imperial shock fit if I use the Shockcraft Deaktiv kit?” and get a real answer.
• Spring-rate calculator. A practical formula that accounts for rear weight distribution — not the theoretical Fox “quick formula” that overshoots real-world spring picks by 40%.
• Ebike load correction. Weights 40% of battery + motor mass onto the rear shock and adds a high-torque correction for ≥100 Nm motors.
• Progression flag. Warns when a frame’s linkage does not really want a coil — e.g. Trek’s Full Floater is only ~13% progressive and is tuned for a DRCV air spring, so a linear coil will bottom harshly.
• Documented-build flag. If no published build exists for the exact frame generation, every candidate gets an experimental warning.
• Research library. Verified references to conversion kits, manufacturer product pages, global retailers, used-market venues, forum threads, and vendor email contacts — with tests enforcing that every link is HTTPS and every group is populated.
• Pivot hardware model. OEM bearing/bolt spec plus a four-step health check so you can decide whether a full frame rebuild is required alongside the shock swap.

Status today

Primarily a 2013 Trek Fuel EX 5 model. The coil catalog includes Push ElevenSix (the only currently-buildable imperial 7.25×2.0 coil in April 2026), plus Marzocchi Bomber CR, Fox DHX2, DVO Jade X, MRP Hazzard Coil, and Cane Creek DB Coil IL entries marked used-market-only. The air catalog includes Fox Float X2, RockShox Super Deluxe Ultimate, and Marzocchi Bomber Air. Real VALT Progressive sizes are captured with the 45 mm stroke that fits inside a 50 mm shock; Sprindex 55 mm is flagged as not-fitting. The conversion kit catalog covers Offset Bushings, Shockcraft Deaktiv, an unpublished custom-machine path for Huber Bushings, plus a speculative metric-to-Trek kit flagged publishedSku: false so the test suite warns on it.

Why code-as-data

Because every existing shock “compatibility chart” is a PDF, and PDFs cannot be run against a test suite. If you model the data in TypeScript, the test suite can assert things like “no reservoir clash on any frame in the catalog”, “every link in the research library is reachable”, and “every catalog entry has a spring rate range if it is a coil”. That turns a messy research task into something a contributor can submit a pull request against. Source on GitHub.