Short answer: choose a hosted PDF API when receipt rendering is a small, bursty dependency and your team can tolerate a network hop; keep local PDF libraries when latency, data residency, or offline operation is a hard invariant. The deciding constraint is not the first successful render. It is the failure boundary you are willing to operate when expense reports arrive in a burst and every request carries sensitive line items.
This is an architecture decision record for a media company that OCRs scanned documents into searchable text, then emits a receipt packet for an expense report. The OCR result is not the PDF itself, but it determines whether a human can audit the final packet. Template ownership matters: a team that owns the template and its rendering tests can change engines without changing the OCR pipeline; a team that outsources both may gain speed and inherit a contract it cannot inspect.
The invariants before the implementation
I write the invariants down before comparing libraries or APIs. A receipt packet must preserve page order, expose a stable document identifier, and retain the original scan separately from the generated artifact. The generated PDF is disposable; the evidence is not. A retry must not create a second expense report attachment, so the idempotency key belongs to the job record, not to a browser request.
Latency needs a budget with a shape, not a single average. Set a deadline for queue wait, rendering, upload, and response serialization independently. A hosted call adds DNS, TLS, transit, and a provider queue. A local call removes the network leg but can contend with OCR workers for CPU and memory. Under load, either design can fail if those resources share an unbounded pool.
There is a quiet requirement that teams often skip: deterministic output. Fonts, image decoders, locale rules, and metadata should be pinned. If the same input produces a different byte stream after a dependency update, byte equality is a poor test; compare extracted text, page count, dimensions, and a visual sample instead.
How should hosted PDF APIs and local PDF libraries handle receipts and expense reports under load?
The useful comparison is a set of failure domains. A hosted API concentrates rendering capacity outside your process, but it makes availability and tail latency partly someone else's service-level concern. A local library gives direct control over the critical path, while your deployment owns native dependencies, patching, and noisy-neighbor isolation.
| Concern | Hosted PDF API | Local PDF library |
|---|---|---|
| Latency | Network and provider queue add variable tail; use deadlines and a bounded queue | Predictable when isolated; CPU, memory, and font loading can stretch p95 |
| Capacity | Scale by provider quota and concurrency contract | Scale by your workers and instance budget |
| Template ownership | Often a remote template or vendor-specific contract; export and test it | Template files and renderer version live with your code |
| Data boundary | Scans and OCR text cross a service boundary; document retention and deletion need verification | Data stays in your account boundary, but logs and temp files are your responsibility |
| Failure handling | Classify timeout, rate limit, and validation responses separately; retry only safe classes | Catch process crashes and malformed input; supervise workers and recycle them |
| Operations | Less native packaging; more dependency on network and provider changes | More packaging and security work; fewer external moving parts |
The table does not produce a universal winner. It exposes which unknowns deserve a proof test. Ask for the provider's concurrency semantics and maximum payload before promising a p99. For a local engine, measure with the largest scan, the longest OCR text, and the font set used in production. A five-page, text-only fixture is a toy. I don't trust a green dashboard that hides queue age: a renderer can report a fast internal duration while requests spend minutes waiting for a permit, and a hosted service can return quickly for small files while its larger payload lane is saturated. Break the timing into named spans, preserve the request mode and template version as attributes, and sample enough bursts to see a cold-start cluster. Then compare the same acceptance checks after a worker restart, because font caches and image libraries often make warm and cold paths behave differently. That evidence tells you whether a timeout is a capacity problem, a network boundary, or a malformed document; those require different fixes and different owners.
A bounded critical path
The application should enqueue rendering rather than hold an HTTP request open. The worker below is intentionally boring: it records an idempotency key, applies a deadline, and writes the result only after validation. render_local and render_hosted are adapters around standards-compliant implementations; neither adapter is allowed to change the document schema.
from dataclasses import dataclass
from time import monotonic
@dataclass
class RenderJob:
key: str
source_uri: str
template_version: str
mode: str # "local" or "hosted"
def render_packet(job: RenderJob, deadline_seconds: float) -> str:
started = monotonic()
existing = idempotency_store.get(job.key)
if existing:
return existing
if job.mode == "local":
pdf_bytes = render_local(job.source_uri, job.template_version)
elif job.mode == "hosted":
pdf_bytes = render_hosted(
source_uri=job.source_uri,
template_version=job.template_version,
timeout_seconds=deadline_seconds,
)
else:
raise ValueError("unknown render mode")
if monotonic() - started > deadline_seconds:
raise TimeoutError("render deadline exceeded")
validate_pdf(pdf_bytes, expected_template=job.template_version)
uri = object_store.put(pdf_bytes, content_type="application/pdf")
idempotency_store.put(job.key, uri)
return uri
The ordering is deliberate. Validation precedes the durable pointer, and the pointer is written once. If the process dies after upload but before the idempotency record, a content hash or a deterministic object key lets a repair job find the orphan rather than silently attach a second copy. The repair path should be observable and rate-limited; it should not replay every historical job at startup.
Use a separate semaphore for hosted calls and local renders. A single global worker pool turns a provider slowdown into starvation for local work, or a large scan into a denial of service for the API. Record queue age, render duration, payload bytes, retry count, and the reason a job was rejected. Percentiles are useful only when the sample is tagged with mode, template version, and document size.
Three words: protect the tail.
No averages.
Template ownership is the real switching cost
A rendering engine is replaceable only when the template contract is explicit. Store templates as versioned source, define supported fonts and image formats, and keep a corpus of redacted receipts with expected page geometry. The OCR service should emit a normalized model such as merchant, date, currency, tax lines, and confidence; it should not emit renderer-specific markup.
Ownership also changes incident response. With local code, a bad font package can be bisected and rolled back in the same deployment. With a hosted API, you need a change notice, a version pin if offered, and a way to reproduce a response without sending customer data. If that evidence cannot be obtained, the hosted option is unsuitable for regulated audit trails even when its median latency looks attractive.
The catch is operational concentration. A hosted dependency can be a sensible choice for occasional packets, prototypes, and teams without native build expertise. It is not suitable when the system must render during a disconnected field workflow, when a contractual boundary forbids sending OCR text elsewhere, or when a provider's concurrency policy cannot meet your burst envelope. Stick with a local library when those constraints are hard; accept the packaging work as the price of control.
Conversely, local is not automatically safer. A process that decodes untrusted images in the same container as the web tier expands the blast radius of a parser vulnerability. Run rendering in a restricted worker, cap input dimensions, drop temporary files promptly, and keep the original scan in immutable storage with an explicit retention policy.
Test the decision with production-shaped evidence
Start with a replay set, not a benchmark number. Include skewed scans, rotated pages, missing currency symbols, right-to-left text if the business receives it, and reports containing dozens of receipts. Mix cold and warm workers. Drive a burst that matches the arrival pattern of a payroll close, then repeat it after a renderer restart.
For each mode, capture p50, p95, and p99 end-to-end latency, but also capture queue delay and the percentage of work that exceeded its deadline. A hosted API that has a good median and a bad p99 may still be acceptable if the product shows a pending state and the queue is durable. A local engine with a good p99 may still be rejected if patching it requires an unavailable specialist.
I am not sure a single synthetic test can predict your provider's busiest hour; your mileage may vary. That uncertainty is a reason to negotiate an explicit concurrency limit, run a canary with representative redacted documents, and retain a local fallback only if its templates are kept current. A fallback that has not rendered this month's template is a false safety net.
The decision record should end with a trigger, not a slogan: move from hosted to local when residency or offline requirements become binding, or move from local to hosted when native maintenance consumes more engineering capacity than the measured latency control is worth. Re-run the replay set after every template, font, OCR schema, or renderer change.
Top comments (0)