build.allanninal.dev

Part 2 of 7 · Receipt organizer series ~4 min read

How a receipt gets captured

The organizer can only organize what it receives. So the first job is making it dead simple to send a receipt the moment you have it — not at the end of the week, not at tax time, but right there at the counter or the petrol pump. There are three ways a receipt gets in: forward it by email, snap a photo on a phone, or upload a file on a web page. All three exist because in real life people pay in different ways, and the one that needs the most steps is the one that never happens.

Key takeaways

  • Three capture lanes feed one queue: email forward, mobile snap, and web upload.
  • Email forwards arrive through Amazon SES; the image or PDF is pulled out of the message.
  • The phone lane is a saved home-screen shortcut that opens the camera and uploads in one tap.
  • The web lane is a single drag-and-drop page behind a private link.
  • Every lane stores the original, gives it an id, and drops it on the queue — no receipt is lost.

Three lanes into one queue

Three capture lanes funnel into one queue A diagram with three vertical lane columns at the top and a single unified row at the bottom. Lane one, Email forward: somebody forwards a receipt to a dedicated address, receipts-at-your-company; SES writes the raw message to S3; a capture Lambda pulls the image or PDF attachment out of the message, stores it, and drops it on the queue. Lane two, Mobile snap: a saved home-screen shortcut on a staff phone opens the camera; the photo uploads straight to a private upload link, a Lambda Function URL that writes the image to S3 and drops it on the queue. Lane three, Web upload: a single drag-and-drop page behind a private link lets someone drop an image or PDF from a laptop; the same Function URL stores it and drops it on the queue. All three lanes converge on the same intake queue, an SQS queue that holds each captured receipt until the reader is ready. A note at the bottom: every lane stores the original first — nothing is read in line, so a lunch-hour rush of receipts just waits its turn. Lane 1 · email Email forward • Forward to the receipts-address • SES writes message to S3 • Lambda pulls out the image or PDF • Stored and queued Lane 2 · phone shortcut Mobile snap • Home-screen shortcut opens camera • Photo uploads to a private link • Function URL writes the image to S3 • Dropped on the queue Lane 3 · drag and drop Web upload • Open the private upload page • Drop an image or PDF from a laptop • Same Function URL stores it • Dropped on the queue Intake queue (one place for every receipt) receipt id · source · submitter · stored image · arrival time an SQS queue holds each one until the reader picks it up to reader, one at a time Every lane stores the original first — nothing is read in line, so a lunch-hour rush just waits its turn.
Fig 2. Three lanes converge on one intake queue. Email, phone, and web all store the original image first, then drop it on the queue. The reader picks receipts off the queue one at a time, so a sudden batch never overwhelms anything or gets lost.

Lane 1: email forward

The lane most receipts arrive on, because so many receipts are already emails. Set up a dedicated inbound address — something like receipts@your-company.com — through Amazon SES. Anyone on the team forwards a receipt to that address and the organizer takes it from there. SES writes the raw message to s3://ro-raw-mime/. The S3 write triggers a capture Lambda. The Lambda walks the message to find the attachment — an image (JPEG, PNG, HEIC) or a PDF — or, if the receipt is in the email body itself, screenshots the rendered HTML. It stores the original in s3://ro-receipts/ under a fresh receipt id, records who forwarded it (from the original sender line), and drops a message on the intake queue.

This lane covers online purchases, supplier invoices that come by email, and anything a staff member can forward from their phone’s mail app in two taps. It’s the path that needs no app and no new habit beyond “forward it.”

Lane 2: mobile snap (the lane for paper)

Paper receipts — the petrol station, the hardware store, the taxi — need a camera. Rather than ask staff to install and log into an app, the mobile lane is a saved home-screen shortcut. You set it up once on each phone: open a private link, tap “Add to Home Screen,” and now there’s an icon that opens straight to the camera. Snap the receipt, and the photo uploads in one tap to a Lambda Function URL — a private web address that accepts the file directly, with no API Gateway in front of it.

The Function URL is protected by a long, unguessable token baked into each person’s shortcut, so only your team can post to it. The Lambda writes the photo to s3://ro-receipts/, tags it with the submitter, and drops it on the queue — the same queue the email lane feeds. From the reader’s point of view, a photo from a phone and a forwarded PDF look identical.

Lane 3: web upload

Sometimes a batch of receipts is already on a laptop — downloaded PDFs, scans, a folder of images from a trip. Forcing those onto a phone to re-photograph them is a fight you don’t need. Lane 3 is a single page behind a private link: drag a file (or several) onto it and they upload. It hits the same Function URL as the phone lane, stores each file in s3://ro-receipts/, and drops each one on the queue.

The web lane is the most occasional of the three — most days nobody uses it — but it’s the right tool for the catch-up session where somebody clears a backlog in one go.

Why everything funnels through one queue

Three lanes in, but only one queue the reader watches. That’s deliberate. If each lane read its own receipts in its own way, a bug in the phone path wouldn’t show up the same as a bug in the email path, and a busy afternoon could have three lanes all trying to call Textract at once. Funneling everything through one queue means the reader processes receipts at a steady pace, retries cleanly if Textract is briefly busy, and never loses one — a receipt sits safely on the queue until it’s been read and filed. Anything that fails repeatedly lands in a side queue (a dead-letter queue) for a human to look at, instead of silently vanishing.

Next post: how the reader actually reads a receipt — pulling the vendor, date, total, and tax off the image, and how it decides when it’s sure enough to file on its own.

All posts