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.

The problem

Studio paper backdrops are never as clean as they look before the shoot. A six-hour session leaves scuff marks, footprints, seam shadows where the paper meets the floor, uneven lighting where the key light rolled off, and the occasional crease from the roll dispenser. Fixing those by hand in Photoshop — with the healing brush, dodge/burn layers, and a feathered mask around the subject — is a real job. For a shoot with two hundred keepers, it is unreasonable.

The commercial tools that automate this are excellent and expensive. clean-backdrop is the free alternative.

How it works

Two complementary techniques, run on GPU:

1. Shadow Lift. Samples a patch of clean wall, then blends cast shadows toward that reference. Preserves the natural wall gradient (studios are not lit perfectly flat and should not be rendered that way). Adjustable 0–100%.
2. Texture Smoothing (Frequency Separation). Splits the image into a low-frequency lighting gradient and a high-frequency detail layer. Smooths the detail layer — where marks, scuffs, and paper texture live — while leaving the gradient untouched. No smudging, no false positives on the subject’s hair.

Both passes run on a BiRefNet-Portrait subject segmentation mask with distance-based feathering, so the boundary between subject and cleaned background has no visible “bar” artifact at any crop size.

Smart edge handling

• Smooth subject masking. Feathering scales with image size, so a 24 MP portrait has the same clean transition as a 45 MP headshot.
• Automatic floor detection. Real floors (wood, tile, concrete) are distinguished from wall shadow/vignetting by a colour-analysis heuristic. Real floors stay; darkening on walls gets cleaned.
• Vertical floor transition. The wall-to-floor boundary uses a row-based ramp so the floor texture and contact shadows around the subject’s feet are never disturbed.

Running it

There are two ways to use it:

# Web UI — drag-and-drop with live sliders
pip install -r requirements.txt
python app.py
# open http://localhost:5000

# Batch — directory in, directory out
python batch.py "D:\Photos\Export\My Shoot" --lift 70 --texture 50

The web UI shows four tabs — Original, Shadows, Texture, Preview — so you can dial shadow lift and texture smoothing independently and watch the separation happen. Outputs are saved next to the original with a _clean suffix, ICC colour profiles and EXIF metadata preserved.

Why open-source

Because the underlying math is not exotic — shadow lift and frequency separation have been in the photo-retouching toolkit for twenty years — and because a high-quality portrait segmentation model exists under a permissive licence. The commercial offerings are polished, but the core workflow does not need to be proprietary. If you shoot regularly against studio paper, clone the repo and stop paying a per-seat fee for a batch operation.

The itch

Every mid-year I rebuild the same Excel spreadsheet: paste in ING transactions, paste in PayPal, paste in the Bankwest credit card, then hand-categorise everything, then try to remember which expense was for which business, then double-count a $200 transaction that appeared on both the credit card and the bank account it was paid from. Then I hand it to my accountant and we do it all over again. Ledger is the version I should have built five years ago.

Sources supported today

Drop a statement into staging/<source>/, run ledger ingest, and the right parser picks it up. PDF parsing is per-bank because every Australian bank has a different statement layout and none of them offer a clean machine-readable export.

What it does

• Multi-source ingestion. The above parsers, with dedup rules to prevent double-counting when a transaction appears on both a bank account and a credit card.
• Auto-categorisation. Regex-based merchant rules assign categories automatically and learn from manual overrides.
• Business splits. A percentage of any expense can be allocated to a business — essential for anyone running a sole-trader side or a company with home-office overlap.
• ATO tax return view. Output structured to match the sections of an Australian individual tax return: salary, rental schedule, business schedule, deductions.
• Financial year view. Outgoing / incoming / rental / work-trip sub-tabs replacing the Excel sheet I had been rebuilding by hand every year.
• Net worth dashboard. Accounts, credit cards, property, vehicles — balances pulled from the same statements.
• Tags. Orthogonal to categories. A transaction can be in category “Travel” and tagged flight, biz-hosting, rental-income for finer reporting without having to invent a deeper category tree.

Why local-first

Because my financial data is mine. No cloud dependency, no third-party aggregator pulling read-only access to my bank accounts, no “we are deprecating the Xero integration” email six months from now. SQLite sits in a folder, the dashboard runs on localhost, and if I want to back it all up I copy a single file.

Quick start

git clone https://github.com/isaacrowntree/ledger.git
cd ledger
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

cp config/accounts.yaml.example config/accounts.yaml
cp config/categories.yaml.example config/categories.yaml
cp config/tax.yaml.example config/tax.yaml

ledger init
mkdir -p staging/ing staging/paypal
# Drop PDFs/CSVs into those folders
ledger ingest
python -m api
# Open http://localhost:5050

Who it is for

Anyone in Australia with more than one bank account, a side business or two, and an accountant who currently gets a hand-assembled spreadsheet every July. Source on GitHub.

Why local

Cloud LLMs are wonderful until you are on a flight, behind a client VPN, editing code with sensitive data, or burning through a monthly token budget faster than is reasonable. The quality gap between the best frontier models and the best local-runnable models has narrowed dramatically — a quantised 9B Qwen model on a modest NVIDIA card is now perfectly capable of the “reformat this function, add a docstring, write a test” type of work that makes up most of a coding assistant’s day.

The benchmarks

Measured on release builds, real completions, real contexts:

*The dense 27B is slower than the 35B-A3B MoE on 36 GB machines — see “Why MoE?” in the repo for the full story.

Why MoE wins on Apple Silicon

Apple’s unified memory is generous but its memory bandwidth is not as high as a discrete NVIDIA card’s. A dense 27B model saturates that bandwidth on every token. A mixture-of-experts model like Qwen3.5-35B-A3B only activates 3B parameters per token, which means each token reads a fraction of the weights — and the model runs faster and smarter than the dense option it replaces. The guide walks through the tradeoff properly.

Test machines

• Windows/WSL2: RTX 4070 Ti (12 GB), Intel Core Ultra 9 285K, 48 GB DDR5
• macOS: M3 MacBook Pro, 36 GB unified memory

Quick start

The guide walks through llama.cpp from source (with -DGGML_CUDA=ON or -DGGML_METAL=ON), the llama-server binary, wiring it into VS Code via the Continue extension, and wiring it into Claude Code as a local endpoint. Ollama + MLX is covered as the one-command alternative for Apple Silicon.

Who it is for

Developers who want a serious coding assistant that runs on their own hardware, without a subscription, without a round-trip to a cloud inference endpoint, and without hand-tuning flags for six hours. Read it on GitHub.

The problem

You have two audio files:

• Original — the studio recording. High fidelity, the version on Spotify, the one you actually want to listen to.
• Performance — a live recording of the same song. Great arrangement, maybe some improvisation, but also crowd noise, ambient PA colouration, and a phone mic’s idea of bass response.

The live arrangement is better — it is the one the band actually performed — but the audio fidelity is worse. What you want is: the live arrangement, with studio fidelity. That is what this tool does.

How it works

1. Band-pass filter to 200–4000 Hz on both tracks. Vocals live in that range, crowd noise and room rumble largely do not. This is what makes matching robust to a noisy live environment.
2. Sliding-window cross-correlation between chunks of the performance and the full studio track. Each chunk’s best match pins down where in the original it came from.
3. Segment detection by grouping matches with consistent time offsets. A 30-second verse played live will produce 30 seconds of chunks that all agree on the same studio offset.
4. FFmpeg concatenation of the identified original segments, in the order the live performance used them, into a clean output file.

Example output

For “Ya Te Olvide” by Los 4 ft Laritza Bacallao (4:40 studio original → 1:56 live performance):

SEGMENT MAP:
  1  0:00-0:19  |  Orig 0:12-0:30  |  18.5s  (intro/verse start)
  2  0:19-1:04  |  Orig 0:50-1:35  |  44.5s  (verse/chorus)
  3  1:04-1:36  |  Orig 2:44-3:15  |  31.5s  (montuno section)
  4  1:36-1:46  |  Orig 4:13-4:23  |   9.5s  (ending)
  5  1:46-1:48  |  Orig 4:33-4:35  |   2.0s  (final tag)

Skipped from original:
  0:00-0:12  (11.8s) - pre-intro
  0:30-0:50  (20.1s) - transition/repeat
  1:35-2:44  (69.1s) - repeated verse section
  3:15-4:13  (57.9s) - extended montuno/breakdown
  4:23-4:33  (10.3s) - outro padding

The segment map reads like a director’s cut list: the band skipped the pre-intro, compressed the long breakdown, and landed on a different ending. Feeding that back into FFmpeg reconstructs the performance from clean studio audio.

Why bother

Latin dance classes like Havana on the Hastings often rehearse to studio recordings but perform to the band’s own arrangement — which means choreographies that work in rehearsal do not always align with the live record they are showcased against. A recut reconciles the two: same arrangement the dancers know, but clean enough to cue on.

Usage

cp original_song.mp3 staging/original.mp3
cp performance_recording.mp3 staging/performance.mp3
python3 analyze.py
# Output: output/ya_te_olvide_recut.mp3

Dependencies are Python 3 with NumPy, plus a working FFmpeg on $PATH. Source on GitHub.