Claims intake is a storage problem wearing a rendering costume. Short answer: start with an asynchronous PDF endpoint that accepts a bounded input, emits a content-addressed result, and deletes source scans on a documented schedule; reserve pixel-perfect rendering for the pages that actually need it. That shape keeps latency predictable without pretending that every insurer's form is equally simple.
A US/EU SaaS generating invoice PDFs from order data has a related constraint: the PDF is evidence, not a screenshot. For scanned claims, the evidence includes the original bytes, OCR provenance, page order, and a repeatable rendering recipe. If those pieces are mixed into one opaque upload, a later dispute turns into archaeology.
Start with the bill, then decide what to retain
Most teams price the wrong term first. The dominant cost is usually the amount of data retained and reprocessed, not the few milliseconds spent constructing a response object. A 12-page scan at 300 dpi can be tens of megabytes before OCR adds a text layer; storing three retries, two thumbnails, and an unbounded audit trail multiplies that footprint.
Measure four quantities per claim: input bytes, rendered output bytes, CPU seconds, and retention days. Keep a hash of each input and output, plus a small manifest containing page count, renderer version, and timestamps. That lets a worker skip duplicate work while preserving evidence that a particular PDF came from a particular input.
The deliberate sacrifice is raw convenience. I would stop keeping intermediate raster pages after quality checks pass, and I would keep the original scan only for the legal retention window. When an adjuster asks for a re-render after that window, the answer may be “we cannot reproduce it”; that is a policy cost, so document it before launch instead of discovering it during a claim appeal.
| Decision | Keeps | Gives up |
|---|---|---|
| Keep original scan plus final PDF | Strongest evidence chain | Storage and deletion work |
| Keep final PDF plus hash manifest | Lower footprint | Limited future reprocessing |
| Keep every intermediate | Fast forensic replay | High retention exposure and cost |
How should PDF endpoints balance fidelity, latency, privacy, and operational complexity?
Treat endpoints as stages with explicit contracts. An intake endpoint should validate MIME type, byte size, page count, and malware status before a renderer sees the file. A job endpoint should return an idempotency key and a status URL; it should not make a user-facing request wait for a 20-page scan. A retrieval endpoint should stream bytes with a content disposition and an integrity hash, while authorization checks the tenant and claim scope on every request.
For invoice PDFs generated from order data, a deterministic HTML-to-PDF path is often enough: fixed fonts, embedded assets, and a test corpus of awkward addresses and long line items. Scanned claims need a different fidelity budget. Preserve the source page dimensions, avoid lossy recompression, and record OCR confidence per page. “Looks right in a browser” is not a fidelity test.
HTTP 202 is a useful signal here.
Here is a small Python contract for a worker queue. It is intentionally boring: the storage adapter can be local, object storage, or an internal service, as long as it provides conditional writes and server-side encryption.
from dataclasses import dataclass
from hashlib import sha256
@dataclass(frozen=True)
class PdfJob:
tenant_id: str
claim_id: str
source_key: str
renderer_version: str
def output_key(job: PdfJob, source_bytes: bytes) -> str:
digest = sha256(source_bytes).hexdigest()
return f"pdf/{job.tenant_id}/{job.claim_id}/{job.renderer_version}/{digest}.pdf"
def should_render(store, key: str) -> bool:
return not store.exists(key)
The hash makes retries safe, but it does not make data anonymous. A digest of a known claim can still be correlated, so access logs, encryption keys, and deletion jobs matter just as much as the endpoint syntax. I once saw a queue retain failed payloads for 14 days because its dead-letter policy was copied from a generic messaging template. The PDF service was healthy; the retention boundary was wrong.
Failure modes that only appear after launch
Latency spikes when a synchronous route performs OCR, font substitution, and object upload in one transaction. Fidelity failures hide in less obvious places: a missing embedded font changes line breaks, a color profile shifts a signature stamp, or a library upgrade changes pagination. Operational complexity shows up when a timeout causes the client to retry without an idempotency key, creating two legally identical but separately stored documents.
Use percentile latency, not averages. Alert on queue age, render error rate, output-size drift, and deletion lag. For US/EU tenants, keep region selection explicit and make cross-border replication an opt-in policy decision. Privacy reviews should cover temporary files, worker disks, tracing payloads, support exports, and backups; a PDF that is deleted from primary storage can still exist in a trace span.
The ugly case is a retry storm during an insurer's morning batch: a client times out, retries five times, and each worker writes a distinct object because the request had no idempotency key. The pages are identical, but the audit trail now contains five timestamps, five retention clocks, and five deletion tasks. Fixing it means defining the idempotency scope (tenant, claim, and source hash), persisting the decision before rendering, and making the status endpoint return the original job. It takes more design than adding a queue, and it is exactly the design that keeps a queue from becoming a second source of truth. I've learned to review this path with the storage and privacy owners in the same meeting; rendering correctness alone won't catch it.
A practical selection rule
Choose the least complex endpoint family that satisfies the strictest document obligation. Use synchronous generation for small, deterministic invoices where a p95 budget under a few seconds is tested. Use asynchronous jobs for scans, OCR, or any workload whose tail latency can exceed the request timeout. Add a separate evidence manifest when legal or audit teams need reproducibility.
Measure twice.
The catch is that an asynchronous pipeline is not suitable when a caller cannot tolerate eventual availability or when your team cannot operate deletion and key-rotation workflows. Stick with a simpler in-process renderer for low-volume, non-sensitive documents, even if it leaves some throughput on the table. I am not sure a single global retention period can satisfy every US and EU contract; your mileage will vary until counsel maps each tenant's obligations to an actual deletion schedule.
References
- https://developer.mozilla.org/en-US/docs/Web/API/Blob
- https://www.rfc-editor.org/rfc/rfc9110
- https://www.rfc-editor.org/rfc/rfc8785
Top comments (0)