AWS Builder Center
Weekend Showcase Challenge: Doc Expiry Watchdog

Weekend Showcase Challenge: Doc Expiry Watchdog

A serverless AWS app that OCRs your passports, licences, visas, and insurance docs with Textract, then emails you at 90/30/7/1 days before they expire because expiry dates are the one thing nobody remembers to check.

My passport expired eleven days before a trip I'd already paid for. Nobody warned me — there's no notification, no dashboard, no reminder for any of it. Passports, driving licences, visas, insurance policies, professional certifications: they all expire quietly, and the only place that date lives is printed on a document nobody looks at until it's too late. That's the whole premise of Doc Expiry Watchdog.


What it does

The flow is deliberately short:
  1. Sign in with email and password (Cognito, SRP auth, no hosted UI).
  1. Upload a photo or PDF of a document.
  1. Amazon Textract OCRs it, and a parser extracts document type, holder name, document number, and expiry date, each with a confidence score.
  1. I confirm or correct the extracted fields before anything gets saved — the app never trusts OCR blindly.
  1. A background agent runs once a day and emails me at 90, 30, 7, and 1 days before expiry, plus once on the day it actually lapses.
  1. A dashboard sorts everything by urgency, with a validity ring per document and safe/warning/critical/expired states.
That's it. No social features, no premium tier, no dashboard-as-a-service ambitions. Just: tell me before it's too late.

Architecture

It's one AWS CDK stack, TypeScript, deployed to us-east-1 with a single deploy command. Here's what each piece does:

  • CloudFront + private S3 bucket — serves the React frontend; the bucket uses Origin Access Control and is never public.
  • Cognito User Pool + App Client — SRP auth straight from the browser, no client secret.
  • API Gateway HTTP API — JWT authorizer, CORS locked to the CloudFront origin, throttled at 20 rps / burst 40.
  • 11 Lambda functions (Node.js 22.x, arm64) — one per route, plus the daily agent.
  • DynamoDB, single-table design, on-demand billing, point-in-time recovery.
  • A second private S3 bucket for the documents themselves — SSE-S3, TLS enforced, reachable only through presigned URLs that expire in 5 minutes.
  • Amazon Textract (DetectDocumentText) for OCR.
  • Amazon Bedrock (Claude) as a pluggable alternative extractor — more on this below.
  • EventBridge Scheduler,  cron(0 8 * * ? *)  UTC, triggers the daily agent.
  • Amazon SES v2 for the alert emails.
  • CloudWatch Logs, structured JSON, correlation ID per request, PII redacted.
The DynamoDB key design is the part worth explaining, because it's doing real work, not just following a template. A document is stored as  PK = USER#<cognitoSub> ,  SK = DOC#<ulid> , with a GSI on  GSI1PK = "EXPIRY" ,  GSI1SK = <expiryDate> . The daily agent's entire job is to answer "what expires in the next 90 days, across every user?" Without the GSI, that's a table scan. With it, it's one range query. That single index is the difference between an agent that costs pennies and one that gets slower and more expensive as the user base grows.

How I built it, and what broke

A few of these cost me real time, and they're the part I'd actually want to read if I were you.
My tests lied to me. I hand-wrote fixtures for the field extractor and they passed 8/8. Then I ran the real Textract pipeline and it scored 0/8 on document numbers. Turns out real documents print the label in small capitals and the value underneath, and OCR returns those as separate lines — a run of labels followed by a matching run of values:
DATE OF ISSUE
DATE OF EXPIRY
18 AUG 2016
14 AUG 2026

My fixtures had label and value on the same line, because that's how I'd imagined it in my head, not how it actually comes back. I rewrote the extractor to queue labels and bind them to values in order, then threw out every fixture and replaced it with real Textract output captured from the sample documents. Final result: 24/24 fields correct across 8 documents. The lesson generalizes past OCR: test against reality, not against your mental model of reality.
My own watermark was corrupting the OCR. I generated specimen PDFs with a diagonal "SPECIMEN" watermark for testing. Textract started returning garbage fragments — "1 CT 2027", "DATI", "E", "EXP" — wherever the watermark glyphs overlapped a field row. I had to move the watermark into verified-empty bands of each page. When OCR misbehaves, suspect the input before you suspect the parser.
An SES  AccessDeniedException  that the IAM policy simulator swore was allowed. My least-privilege sending role had permission on the identity, and the simulator said that was enough, but the send still failed while my admin user worked fine. It turned out my sender identity carried a default configuration set left over from an unrelated project, and SES authorizes against that resource too, whether or not the caller names it. My role had no permission on that configuration set's ARN. It got worse before it got better: my mailer was logging only the exception name, which hid AWS's own explanation for three separate invocations. Fixed it two ways — log the message, not just the name, and have the deploy script discover the configuration set and grant that exact ARN.
Refusing to guess. The parser rejects ambiguous numeric dates like  03/04/2027  — is that 3 April or 4 March, depending on where the document was printed? It returns null and asks me instead of guessing, because reading the wrong date is worse than reading no date: it silently schedules the alert for the wrong day, and you find out when it's too late. Same principle applies to labels — a "date of birth" or "date of issue" field can never become the expiry date, no matter how close the numbers look.
Abandoned uploads leaked forever. A presigned upload lands in S3 before I confirm the extracted fields, so every rejected file, closed tab, or failed OCR left an orphan object nothing pointed at. I found 17 stranded objects against 9 real documents I'd actually kept. The daily agent now sweeps unclaimed objects older than a 24-hour grace period. The grace period is what makes the sweep safe — anything still in flight, or sitting on the review screen, is untouched.
Alerts that can't double-fire. Each document carries a  notifiedThresholds  list. Add a document with 5 days left on it, and it's already crossed the 90- and 30-day marks — it should get exactly one "7 days left" email, not three emails at once out of context, and all three thresholds get marked handled so none of them fire again later.
Least privilege, written by hand.  grantReadWriteData()  would have been one line, but it hands Scan and BatchWrite to routes that only ever need GetItem. Every one of the 11 functions got an explicit action list instead. There's no  Action: "*"  anywhere in the stack, and S3 permissions are scoped to the  uploads/*  prefix.
A couple of honest limitations while I'm being honest about everything else: Bedrock is wired in as a pluggable extractor behind an  EXTRACTOR  environment variable, but it's currently disabled in my deployment because model access wasn't enabled on the account — the live extraction path is the label-based heuristic, not Claude. I think the pluggable-port design is the better story anyway; pretending the model is running when it isn't would be worse. Separately, Textract's synchronous API only reads single-page PDFs and images, so multi-page PDFs currently fail outright, and the account is still in the SES sandbox, so delivery is limited to verified addresses.

What I learned across the summer

The fixture story is the sharpest lesson of the summer: testing against my mental model of the data instead of the actual data gave me false confidence right up until it met reality. Close behind it — errors need to carry the upstream system's own explanation, because swallowing it costs hours you didn't need to spend. Least privilege isn't just a compliance checkbox; it surfaced a real bug the SES sandbox setup was hiding. And a genuinely unattended daily agent forces a kind of idempotent thinking that request/response code never demands of you — you have to design for "what if this runs twice" and "what if this document was added mid-cycle," not just "what if this request succeeds."
If there's one thread through all of it, it's that designing for the failure case — refusing to guess a date, a grace period before deleting anything, one email instead of four — is most of what separates a demo from something a person could actually rely on to warn them before their passport expires.

Numbers, for the record

11 Lambda functions, one CDK stack, one deploy command. 105 unit tests passing. 24/24 extraction fields correct on the live pipeline. Zero wildcard IAM actions. Alert emails delivered end to end through SES, verified in my own inbox. Only the last 4 characters of a document number are ever stored. It runs inside the AWS Free Tier — Textract and Bedrock are the only meters that move, and only when a document gets uploaded.

A look at it running

The dashboard sorts by whatever needs attention soonest, with a validity ring per document:

Uploading a document is a two-pane screen — drop the file on the left, review the extracted fields on the right before anything is saved:

Each document has its own detail view, with the original file rendered alongside the extracted metadata so you can check the OCR against the source:


Scrolling further shows the alert timeline for that document — which thresholds have already fired and which are still pending:

And here's what actually lands in the inbox — a 1-day warning and a 45-day warning for the same policy, sent for real through SES:


Settings let you choose which of the five thresholds you actually want to be notified at:

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article