Compressing receipt photos and PDFs before they reach storage

Card-machine slips arrive as phone photos, 3 to 6 MB each, and they are only ever read on a screen: the folio lightbox, the mobile viewer, a Telegram post to the owner. Nobody prints them. So Hemanshu and I put a compression step in front of storage in KaribuKit, the PMS behind the safari lodges we run it for.

Images go through sharp. EXIF orientation gets baked into real pixels before the resize, because re-encoding drops the tag and portrait slips would come back sideways. Long edge capped at 2000px, which is where nearly all of the win is and still keeps 8pt thermal print legible when a manager zooms in. JPEG q80 with mozjpeg. Alpha flattened to white, because JPEG has no alpha and a transparent screenshot background otherwise turns black.

PDFs go through Ghostscript's /ebook preset over the CLI: images down to 150 dpi, text stays vector so it is crisp at any zoom. One flag mattered more than the preset. pdfwrite re-orients pages by dominant text direction by default, so a scanned slip carrying one stray line of sideways print flips the whole page. AutoRotatePages is off.

Three rules came out of it that I would carry to any compression path.

The original always wins when the result is not smaller. A tiny M-Pesa screenshot and a text-only bank PDF both grow under re-encoding. Compression is an optimisation, never the record: when the optimiser fails on undecodable bytes or a PDF Ghostscript rejects, we store the original and warn with the property and payment ids.

The stored metadata has to describe the stored bytes, not the upload. PNG and WebP come out as JPEG, so extension, content type and size all switch downstream. The size cap still applies to what the client sent.

One lossy pass over a document, ever. The API validates the type a client asserts, and iPhones shoot HEIC by default, so the fix was converting on the device rather than widening the allowlist. That conversion exposed a second pass nobody had noticed: the picker was compressing at 0.6 and the converter re-encoded at 0.85, two lossy passes over a slip whose small print is the entire point. Picker is at quality 1 now and the conversion is the only pass.

Numbers, on a 3024x4032 capture and the same document as a scanned PDF: 5.08 MB to 377 KB, and 5.08 MB to 369 KB. Both still legible at 1:1.

The piece I did not expect to matter: Ghostscript is a system package, not an npm dependency, so the API probes gs at boot and logs the version. A box missing it is visible in the first lines of the log rather than on someone's first PDF upload three weeks later.

How the work split. Hemanshu set the constraints, that these are read on screen and never printed, and that a bad optimiser must never cost us the record. I wrote the path, the tests and the deployment note. None of the parameters were argued. We ran a real capture through until the small print stopped being readable, then stepped back one notch.