Short answer: a US/EU SaaS should use separate PDF endpoints for scanned claims upload, OCR extraction, and template-owned rendering; put OCR behind a bounded queue, keep the original scan immutable, and choose concurrency from measured latency under load rather than average response time.
That split gives a US/EU SaaS control over the two things that age badly when they are hidden inside one endpoint: claim-field fidelity and latency under load. It also keeps the outbound e-commerce invoice template in your repository, where a tax label or order-line layout can change without rewriting the intake pipeline.
The hard part isn't turning bytes into text. It is deciding who owns the document contract, then making every slow stage visible.
How should a US/EU SaaS balance PDF fidelity and latency under load?
Treat fidelity, latency, and operational complexity as three budgets, not one score. Fidelity means more than a PDF that opens. For scanned claims intake, it means retaining the original artifact, recording which pages were processed, and keeping extracted fields tied to evidence that a reviewer can inspect. For invoice generation from order data, it means that your application owns the template version and can reproduce the document created for a particular order.
Latency needs two clocks. The first ends when upload is accepted and a durable job identifier exists. The second ends when extraction is ready for review. A single synchronous timer hides queue wait, which is often the part that changes most dramatically as traffic rises. Measure queue wait and processing time separately, then report percentiles for both. An average can look calm while a small but important group of claims waits far longer.
Operational complexity is the cost of owning those boundaries: object retention, retries, worker capacity, template releases, and telemetry. More components create more work. Fewer components can create an opaque dependency whose queue behavior and document semantics you cannot control. There is no universal winner — the right boundary follows the team's ability to operate it and the consequence of a bad extraction.
A useful decision rule is crisp. Keep templates in application-owned, versioned source when invoices are contractual output or change with product releases. Let a document service own templates only when non-engineers must edit them independently and the service's versioning, review, and rollback model matches your release controls. For scanned claims, preserve the source PDF regardless of who performs OCR.
Replace the one-call mental model
Before: a request uploads a scan, waits for OCR, maps fields, generates a PDF, and returns the finished result. One box. One timeout. Under light traffic it feels wonderfully direct; under burst traffic, every caller competes for the same finite processing slots while nobody can tell whether time was spent transferring bytes, waiting, extracting, or rendering.
After: picture five boxes connected left to right. The API accepts a Blob and stores the untouched bytes. A queue records work. An OCR worker produces candidate fields plus page references. A validation step applies business rules and routes uncertain fields to review. A renderer combines approved data with a versioned invoice template. Each arrow carries an identifier, and each box emits duration and outcome telemetry.
That is the whole diagram.
This separation also makes retries safer. Retrying an accepted upload should not create a second claim; retrying OCR should not mutate the original; retrying invoice rendering should use the same order snapshot and template version. An idempotency key and stable content digest belong at the acceptance boundary. Downstream jobs should name their input version explicitly rather than silently reading whatever data happens to be current.
For observability, start with four events: document.accepted, ocr.started, ocr.completed, and document.rendered. Attach a correlation ID, document ID, region, page count, template version where relevant, queue-wait milliseconds, processing milliseconds, and outcome. Do not attach extracted names, addresses, claim narratives, or raw document bytes to logs. This event shape lets an operator answer the urgent question — "is work slow, or merely waiting?" — without turning telemetry into a second document store.
The alert should follow user impact. Page on sustained growth in oldest-job age or a breached end-to-end latency objective, not on one slow OCR call. A short processing spike can clear itself. A queue whose arrival rate stays above completion rate cannot.
A copyable Node.js boundary
The following TypeScript keeps transport and vendors outside the business workflow. It uses the web Blob type for binary input and leaves the concrete storage, OCR, queue, and rendering implementations behind interfaces. That is deliberate: endpoint paths and response schemas must come from the service contract you actually select, not from a generic article.
type DocumentId = string;
type JobId = string;
type AcceptedDocument = {
documentId: DocumentId;
jobId: JobId;
sha256: string;
acceptedAt: string;
};
type ClaimFields = {
claimNumber?: string;
policyNumber?: string;
lossDate?: string;
evidencePages: number[];
};
interface OriginalStore {
put(input: Blob, metadata: { region: "us" | "eu" }): Promise<{
documentId: DocumentId;
sha256: string;
}>;
}
interface WorkQueue {
enqueue(task: {
documentId: DocumentId;
kind: "extract-claim";
idempotencyKey: string;
}): Promise<JobId>;
}
interface OcrAdapter {
extract(documentId: DocumentId): Promise<ClaimFields>;
}
interface InvoiceRenderer {
render(input: {
orderSnapshotId: string;
templateVersion: string;
}): Promise<Blob>;
}
async function acceptClaim(
pdf: Blob,
region: "us" | "eu",
idempotencyKey: string,
store: OriginalStore,
queue: WorkQueue,
): Promise<AcceptedDocument> {
if (pdf.type !== "application/pdf") {
throw new Error("Expected an application/pdf Blob");
}
const stored = await store.put(pdf, { region });
const jobId = await queue.enqueue({
documentId: stored.documentId,
kind: "extract-claim",
idempotencyKey,
});
return {
...stored,
jobId,
acceptedAt: new Date().toISOString(),
};
}
The acceptance function is intentionally boring. Good. It verifies the media type, persists the source in the chosen region, schedules work once, and returns quickly. The worker can then time queue delay and extraction independently. An invoice renderer uses a different contract because outbound generation has a different ownership model; forcing both through a vague processPdf() abstraction would erase that distinction. Test this boundary with documents, not just JSON fixtures. Keep a small, reviewed corpus containing rotated pages, low-contrast scans, multi-page claims, blank pages, and representative invoice line items. Store expected fields and evidence-page links beside each fixture. On a template change, compare rendered output against an approved baseline and inspect deliberate differences. On an OCR adapter change, report field-level misses rather than one pass/fail score, because a wrong loss date and a missed optional note do not carry the same operational consequence. Load testing needs the queue too. Drive a burst with the same page-count distribution expected in production, record enqueue rate and completion rate, and watch oldest-job age after input stops. If the backlog does not return toward zero, concurrency is below the tested arrival rate or a downstream limit is constraining it. I'm not sure what worker count your documents require; page complexity, service quotas, and review rules decide that. A staged test with representative, non-production documents resolves the uncertainty.
Template ownership changes the failure surface
Application-owned templates make releases reproducible. An invoice can carry templateVersion: "invoice-v12", and the order snapshot can be rendered again against that exact version. Engineers also gain normal code review and automated tests. The catch is that every copy or layout change now waits for the application delivery path, and the team owns font packaging, pagination behavior, and regression review.
Service-owned templates move editing and rendering operations together. That can suit a team where finance or operations changes invoice wording frequently without an application deployment. It is not suitable when the service cannot provide the immutable versions, approvals, regional controls, or reproducibility your document policy requires. In that case, keep the template with the application or choose a boundary that exposes those controls.
The scanned-claim side has a parallel choice. A hosted OCR adapter can reduce the machinery your team runs, but it adds a remote latency and data-handling boundary. A self-operated extractor gives more control over placement and scheduling, while asking the team to own model deployment, capacity, and updates. Stick with the hosted boundary when its processing terms, region options, and measured tail behavior meet the requirement. Choose self-operation only when that added ownership solves a documented constraint; it shouldn't be a reflex.
Evaluate candidates with the same worksheet. Record accepted input constraints, output evidence such as page references, regional processing choices, retry semantics, concurrency limits, and the ability to export or replay results. Then run the same fixture corpus and load shape through each adapter. This is less glamorous than comparing feature grids. It is much more useful.
Two objections worth answering
"Why not keep the request synchronous if most documents finish quickly?" Because "most" is not a capacity plan. A synchronous fast path still needs a timeout decision, duplicate-submit behavior, and somewhere for work to go when all processing slots are occupied. An accepted job makes that state explicit. For an interactive UI, poll a status resource or consume an application event; do not hold the upload connection open for the entire extraction lifecycle.
"Doesn't splitting OCR and rendering create too many moving parts?" Yes, it creates a queue, durable state, and correlation work. That cost is real. For a low-volume internal tool with small documents and no burst pattern, one synchronous component may be easier to own. Keep it until measurements show user-visible queueing or until audit and replay requirements demand separation. For a multi-region SaaS handling claims and contractual invoices, the explicit stages usually earn their keep because they isolate scaling, retries, data placement, and template releases.
The final selection should fit on one page: who owns the template, where original bytes live, what evidence an extraction returns, what latency objective users experience, and how backlog recovery is tested. Pick the simplest design that can answer all five without hand-waving. Then instrument it before traffic arrives.
Top comments (0)