Rental application OCR is a workflow problem before it is a text-recognition problem. For a small property-management SaaS, the least complex design that holds up is an asynchronous job with an explicit state machine, bounded retries, strict input validation, and an encrypted temporary-file lifecycle. Keep the original scan private, process a copy, and delete both on a documented timer.
Short answer: accept the upload, enqueue a job, return a job ID, and let a worker validate, OCR, verify, and purge the temporary files; synchronous OCR in the request handler is the wrong default for tenant documents.
The choice matrix for a rental document pipeline
| Decision | Lower-complexity choice | Choose the heavier choice when |
|---|---|---|
| Request handling |
202 Accepted plus job status |
The file is tiny and a strict latency budget is more important than isolation |
| Work queue | Durable queue with a visibility timeout | Losing one job is acceptable, which is rare for an application packet |
| Retry policy | Three bounded attempts with backoff | The OCR engine exposes a documented, retryable throttle signal |
| File staging | Encrypted object storage with a short TTL | A regulated workflow requires a managed retention hold |
| Extraction result | Versioned JSON plus confidence metadata | A human review step is mandatory for every page |
The recommendation is the middle column. It protects the web process from slow scans and gives me a useful revenue-per-hour trade: I can ship leasing features weekly while a worker handles the undifferentiated waiting. The catch is operational overhead. A queue, worker, and cleanup task are not suitable when the product has no durable data store or cannot explain who may access a scan. In that case, a local, synchronous prototype is fine, but it should be treated as a prototype.
How should a Node.js service implement asynchronous rental applications?
Validation belongs at the boundary and again in the worker. A browser-provided filename is metadata, not a trust signal. Check the declared and detected media type, byte length, page count, and a cryptographic digest. Reject encrypted PDFs if the worker cannot open them, and reject files whose decompressed content would exceed a memory or disk budget.
I use a small schema for the job envelope. It keeps retries idempotent and makes the audit record useful without copying tenant data into logs.
type OcrJob = {
id: string;
propertyId: string;
applicantId: string;
objectKey: string;
sha256: string;
attempts: number;
createdAt: string;
};
function validateJob(job: OcrJob): void {
if (!/^[a-zA-Z0-9_-]{12,64}$/.test(job.id)) throw new Error("invalid job id");
if (!/^[a-f0-9]{64}$/.test(job.sha256)) throw new Error("invalid digest");
if (job.attempts < 0 || job.attempts > 3) throw new Error("retry budget exceeded");
if (!job.objectKey.startsWith("incoming/")) throw new Error("invalid object key");
}
The API should return a stable identifier, never extracted text. A status endpoint can expose queued, processing, needs_review, completed, or failed, plus a safe error category. It should not expose a filesystem path, bucket credential, OCR prompt, or the applicant's name in a query string.
How do asynchronous jobs, retries, and validation prevent duplicate OCR?
Workers must assume delivery is at least once. A timeout can happen after OCR succeeds but before the acknowledgement reaches the queue. If the next worker starts over, the applicant may receive two records or two charges. Use the upload digest and a workflow version as an idempotency key, and put a unique constraint on that pair in the database.
Retry only failures that can change on their own: a temporary network timeout, a queue visibility timeout, or a documented rate limit. Do not retry a corrupt PDF, a failed schema check, or a confidence result below the review threshold. Those are terminal states. Backoff should include jitter, and the maximum attempt count must be part of the job record, not an environment variable that changes mid-flight.
Here is the shape of a worker loop. The OCR call is an interface so the same tests can run against a local engine or a hosted one.
type OcrResult = { text: string; confidence: number; pages: number };
type OcrEngine = (path: string) => Promise<OcrResult>;
async function processJob(job: OcrJob, engine: OcrEngine): Promise<void> {
validateJob(job);
const existing = await db.findResult(job.sha256, 1);
if (existing) return;
await db.markProcessing(job.id);
try {
const path = await files.materialize(job.objectKey);
const result = await engine(path);
if (result.pages < 1 || result.confidence < 0.82) {
await db.markNeedsReview(job.id, { confidence: result.confidence });
return;
}
await db.saveResult(job.sha256, 1, result);
await db.markCompleted(job.id);
} catch (error) {
if (isRetryable(error) && job.attempts < 3) throw error;
await db.markFailed(job.id, classify(error));
} finally {
await files.purge(job.objectKey);
}
}
That finally block is deliberate. Cleanup must run after success, terminal failure, and a retryable exception. The queue's retry then creates a fresh working copy; it never reuses a half-written file. I once assumed a worker crash would be harmless because the object had a seven-day lifecycle rule. It was not harmless: seven days is a long time for a scanned driver's license to sit around. The application needed hours, not days, and the lifecycle rule was only a backstop. The failure path was easy to reproduce: upload a six-page packet, kill the worker after saveResult but before acknowledgement, then watch the queue deliver the same digest again. Without the unique database constraint, the second worker created a second searchable record. With the constraint, it became a no-op, and the purge event still ran. That small test changed the design more than a throughput benchmark would have.
Keep it boring.
Which temporary-file controls make privacy and retention real?
Treat every scan as sensitive personal data. Encrypt in transit and at rest, use per-service credentials, and keep object keys opaque. A path such as incoming/<job-id>/<random>.pdf is easier to authorize than a path containing an email address or unit number. Logs should record the job ID, event type, attempt number, and digest prefix only.
Retention needs two clocks. The working copy should expire after processing or a short failure window, such as 24 hours. The extracted text should follow the lease application's legal and product policy, which may be longer or shorter. A deletion request must remove the source, derivative images, OCR JSON, search index entry, backups where feasible, and access-log references that contain personal data.
Do not confuse a storage lifecycle rule with deletion proof. Emit a purge event, count objects by state, and alert when an object is older than its allowed window. Keep the audit event longer than the document only if it contains no document content and your policy permits it. Privacy is a behavior you can observe, not a checkbox in a dashboard.
When is a simpler or more exact design the better choice?
The recommended pipeline is a good default for mixed-quality rental packets: phone photos, scanned pay stubs, and occasional multi-page PDFs. It is not suitable for a court filing workflow that needs pixel-perfect archival rendering. For that case, retain an immutable original under a legal hold and add a human verification step; fidelity outranks render cost.
It is also a poor fit for a one-off internal script. A script that writes to a local temporary directory and exits can be the right tool when no applicant data leaves a controlled machine. Once tenants upload through a public service, the durable queue and explicit purge policy earn their keep.
I am not sure a single confidence threshold works across every language, font, and document type. Your mileage may vary. Calibrate it with a labeled set of redacted applications, measure field-level errors (income, date, address), and route uncertain pages to review instead of pretending that one score means “correct.”
The useful metric is not OCR throughput by itself. Track time from upload to a searchable, verified application, review rate, retry rate, and bytes retained past the deadline. Those numbers tell a solo founder whether the system is buying back shipping time or quietly creating a privacy liability.
Top comments (0)