DEV Community: Rohit Tirmanwar

Designing an OCR document pipeline on serverless AWS

Rohit Tirmanwar — Tue, 20 Oct 2026 00:16:42 +0000

Document OCR is easy to demo and hard to run. The demo takes a PDF, calls an OCR service, and prints the fields. The production version has to handle a ten-page scan uploaded from a phone, a form filled in by hand, a field read with 61 percent confidence, and a user who needs to know whether their document was accepted. I have built this on serverless AWS for a platform used by a large number of students, and this is the shape that held up.

The pipeline, end to end

Upload straight to S3. The browser gets a pre-signed URL from an API and uploads the file directly. Nothing passes through a Lambda, so a 25 MB scan does not hit a payload limit, and the API only records that an upload was requested.
S3 event to EventBridge to Step Functions. The object-created event starts a Step Functions execution per document. The state machine is the only place that knows the order of steps, which is what makes the pipeline readable six months later.
Validate before OCR. A short Lambda checks the file type, size and page count, and rejects what the OCR service would reject anyway. This step saves money and gives the user a fast, specific error.
Asynchronous OCR. Amazon Textract's synchronous calls have page and size limits, so anything that can be multi-page goes through the asynchronous API: StartDocumentAnalysis with an SNS notification channel, and the state machine waits on a task token until the completion message arrives. GetDocumentAnalysis is paginated, so the collector loops on NextToken until it has the whole result.
Extract and normalise. Raw OCR output is blocks and geometry. A Lambda maps it to the fields the product cares about, normalises dates and amounts, and records a confidence score per field, not per document.
Decide: accept, review, or reject. Per-field thresholds, set from measured data, route each document. Everything above the threshold is accepted automatically. Anything below goes to a human review queue with the page image and the proposed value side by side. Anything unreadable goes back to the user with a reason.
Store and notify. Results land in DynamoDB keyed by document ID, the state machine emits a completion event, and the application notifies the user.

Confidence thresholds are measured, not guessed

The single most important number in the system is the per-field threshold, and the mistake is to pick one number for every field. A date of birth read wrong is a different kind of error from a middle initial read wrong.

We built a golden set: a few hundred documents labelled by hand, run through the pipeline, with the OCR value and confidence recorded for each field. From that you can plot, for each field, accuracy against confidence, and pick the threshold where accuracy reaches the level the business accepts. Some fields needed; some could never be trusted automatically and always went to review.

The golden set then becomes a regression test. Every change to the extractor, every change to a prompt or a model version, runs against it before deploy.

The human review loop is part of the architecture

A pipeline that cannot route to a person is a pipeline that will silently accept wrong data. The review queue is not an exception path; it is a first-class step with its own metrics: queue depth, time to review, and the share of reviewed values that the reviewer changed. That last number is the feedback that tunes the thresholds. If reviewers accept 99 percent of what they see for a field, the threshold for that field is too conservative.

Reviewer corrections are written back to the same DynamoDB record with who changed what and when. Nothing is overwritten.

Sensitive data decides half the design

Documents of this kind carry personal data, so the pipeline is built around not leaking it:

The upload bucket and every downstream bucket are encrypted with KMS and block public access.
S3 lifecycle rules delete the raw uploads after a fixed window. Keep the extracted fields, not the scans, unless there is a legal reason to keep the scans.
Lambdas log document IDs and confidence scores, never field values. A single log line with a value in it is a data leak that lives for the retention period.
Reviewers see pages through short-lived pre-signed URLs, and the review application never stores the image.

Failure modes that were not in the diagram

Duplicate uploads. Users re-upload when the first upload is slow. The document ID is derived from the user and a content hash, so the second upload short-circuits instead of running OCR twice.
OCR service throttling. Textract has account-level concurrency limits. The state machine uses a retry with backoff on the start call, and a concurrency limit on the step keeps a bulk upload from starving everyone else.
Stuck executions. A completion notification that never arrives leaves the execution waiting on its task token. Every wait state has a heartbeat timeout, and a timed-out execution goes to the review queue with a "needs re-run" flag instead of hanging forever.
Partial results. A twelve-page document where page nine failed is still useful. Page-level status is stored, and the decision step treats a missing required page as "review," not "reject."

What I would keep and what I would change

I would keep Step Functions as the backbone. The visual execution history alone has saved hours of debugging, and the task-token pattern makes the asynchronous OCR call look synchronous in the state machine. I would keep the golden set; it is the only reason we could change the extractor with confidence.

I would move the confidence thresholds into configuration from the start rather than code, because they change more often than anything else. And I would build the review metrics on day one, because the pipeline is only as good as the feedback loop that tunes it.

AWS CDK patterns that survive a team

Rohit Tirmanwar — Tue, 20 Oct 2026 00:12:11 +0000

AWS CDK in TypeScript is the best way I have found to define serverless infrastructure, and the easiest way I have found for eight engineers to create eight different conventions. The CDK gives you a real programming language, so every engineer brings their own idea of how to structure it. After a few years of leading teams that own CDK codebases, these are the patterns I now set on day one.

One construct per repeated shape

The first thing to notice in any CDK codebase is repetition: a queue, its dead-letter queue, the Lambda that consumes it, the alarm on the DLQ, the log retention, the IAM grants. Written inline, that is forty lines, and the fifth copy will be missing the alarm.

Turn each repeated shape into a construct with a small interface:

export interface QueueWorkerProps {
  handler: string;
  entry: string;
  visibilityTimeout?: Duration;
  alarmTopic: ITopic;
}

export class QueueWorker extends Construct {
  readonly queue: Queue;
  readonly fn: NodejsFunction;

  constructor(scope: Construct, id: string, props: QueueWorkerProps) {
    super(scope, id);
    const dlq = new Queue(this, "Dlq", { retentionPeriod: Duration.days(14) });
    this.queue = new Queue(this, "Queue", {
      visibilityTimeout: props.visibilityTimeout ?? Duration.seconds(60),
      deadLetterQueue: { queue: dlq, maxReceiveCount: 3 },
    });
    this.fn = new NodejsFunction(this, "Fn", {
      entry: props.entry,
      handler: props.handler,
      logRetention: RetentionDays.ONE_MONTH,
    });
    this.fn.addEventSource(new SqsEventSource(this.queue));
    new Alarm(this, "DlqAlarm", {
      metric: dlq.metricApproximateNumberOfMessagesVisible(),
      threshold: 1,
      evaluationPeriods: 1,
    }).addAlarmAction(new SnsAction(props.alarmTopic));
  }
}

Now the fifth copy cannot miss the alarm. The construct is where the team's operational standards live, and a code review of a new worker is a review of ten lines instead of forty.

Let the CDK name things

Hard-coded resource names feel tidy and cause two real problems. They collide when you deploy a second copy of the stack, and they block CloudFormation from replacing a resource when a change requires it, which turns a small change into a failed deploy.

Omit functionName, tableName, queueName unless something outside the stack needs the name. When something does, export it through an SSM parameter or a stack output rather than by agreeing on a string in two places.

Stages, not copied stacks

Development, staging and production are the same stacks with different parameters, not three directories. A CDK Stage holds the set of stacks, and the app instantiates it once per environment:

const app = new App();
new PlatformStage(app, "Dev", { env: dev, config: configs.dev });
new PlatformStage(app, "Prod", { env: prod, config: configs.prod });

Everything that varies by environment lives in one typed config object. If a value is not in that object, it is the same everywhere, and that is a feature.

`cdk diff` in every pull request

The most useful line in our pipeline is the one that runs cdk diff against the target environment and posts the output on the pull request. Reviewers see the CloudFormation changes, not just the TypeScript. A one-character change that replaces a DynamoDB table shows up as a replacement before it is merged, not after.

Assertions tests for the things that must never regress

Unit tests on infrastructure sound excessive until the first time someone removes a removal policy from a production table. The CDK assertions module makes those tests cheap:

const template = Template.fromStack(stack);
template.hasResource("AWS::DynamoDB::Table", {
  DeletionPolicy: "Retain",
});
template.resourceCountIs("AWS::SQS::Queue", 2); // worker queue plus its DLQ

We do not test everything. We test retention policies, encryption settings, DLQ presence, and that no Lambda has an unlimited log retention. Those tests take seconds and have caught real mistakes.

Keep cross-stack references few and deliberate

CDK makes it one line to reference a resource from another stack, and CloudFormation turns that into an export that locks the two stacks together. Deleting or changing the exporting side then fails until the importing side is updated, and in the wrong order.

The rule that works: resources that change together live in the same stack. Cross-stack references are for a small number of stable, shared things, such as a VPC or an alarm topic. For everything else, pass values through SSM parameters, which decouple the deployment order.

Pipelines deploy, people do not

The last pattern is organisational. Nobody runs cdk deploy to production from a laptop. A pipeline does, from a merged commit, with an OIDC role rather than long-lived keys. Development environments can be deployed from laptops, with per-engineer stage names so two people do not fight over one stack.

Why this matters for a team

Each pattern on its own is small. Together they are what lets a team of six to eight engineers, some of them new to AWS, change production infrastructure every week without a dedicated platform team. The constructs encode the standards, the diff shows the blast radius, the tests hold the floor, and the pipeline removes the human from the deploy. That is the whole point of putting infrastructure in a real language: you get to treat it like the rest of the code.

What keeps a serverless system healthy after launch

Rohit Tirmanwar — Tue, 20 Oct 2026 00:11:06 +0000

Most serverless articles end at the architecture diagram. API Gateway in front, Lambda in the middle, DynamoDB at the back, a queue or two, and the system is "done." I have spent the last five years running systems like that for products used by millions of students, and the diagram was never the hard part. The hard part is everything that happens after launch, when retries, cold starts, throttles and bills show up at the same time.

These are the six decisions I now make before a serverless system ships, because each one was painful to make afterwards.

1. Every asynchronous handler is idempotent

Lambda invoked from SQS, EventBridge, SNS or a DynamoDB stream is at-least-once. The same event will arrive twice. Not often, but at the worst time, and usually when a downstream service is slow and your function timed out after doing half its work.

The fix is boring and it has to be everywhere: an idempotency key per event, stored before the side effect happens. For DynamoDB that is a conditional write on the key. For anything else it is a small table of processed keys with a TTL. AWS Lambda Powertools has an idempotency utility that does exactly this, and it is worth adopting on day one rather than retrofitting it into forty functions later.

If a handler cannot be made idempotent, it needs to be the only consumer of a FIFO queue with a deduplication ID. That is a design constraint, so decide it early.

2. A dead-letter queue on every asynchronous path, with an alarm

An asynchronous Lambda without a dead-letter queue drops failed events on the floor after its retries are exhausted. You will not know. The event is simply gone.

Every SQS queue gets a redrive policy to a DLQ. Every asynchronous Lambda invocation gets an on-failure destination. Every DLQ gets a CloudWatch alarm on ApproximateNumberOfMessagesVisible greater than zero, routed to the on-call channel. The alarm matters as much as the queue. A DLQ nobody watches is a slower way of losing data.

3. Concurrency limits protect the things that cannot scale

Lambda scales faster than almost everything it talks to. A traffic spike that Lambda absorbs happily becomes a connection storm against a relational database, a throttled third-party API, or a downstream service owned by another team.

Reserved concurrency on the function that talks to the fragile thing is the simplest brake. It turns a downstream outage into a queue backlog, which is recoverable, instead of a cascade, which is not. For the small number of functions on the synchronous request path where cold starts are visible to users, provisioned concurrency is worth its cost. For everything else, it is not.

4. Observability is a correlation ID and four alarms

Logs from a hundred functions are useless without a way to follow one request through them. Every function logs structured JSON with a correlation ID that comes in on the request or event and goes out on everything it emits. Powertools does this too. Without it, debugging a production issue is grep across a hundred log groups.

Then four alarms per function, no more to start with: error rate, p95 duration against the timeout, throttles, and for stream or queue consumers, iterator age or oldest message age. Those four catch almost everything. Dashboards are for understanding; alarms are for waking up, and they should be rare enough that every one is acted on.

5. The bill is decided by three settings

Serverless is cheap by default and expensive by accident. The three settings that decide most of the bill:

Log retention. CloudWatch log groups default to never expire. Set a retention period on every group, in infrastructure code, from the start.
Memory size. Lambda bills memory multiplied by duration, and more memory often means a shorter duration and a lower cost. Run AWS Lambda Power Tuning once per function and pick the cheapest setting that meets the latency target, instead of guessing 1024 MB.
DynamoDB capacity mode. On-demand for spiky or unknown traffic, provisioned with auto scaling for steady traffic. Switching later is allowed, so start with on-demand and look at the numbers after a month.

6. A runbook exists before the first alarm fires

Every alarm links to a runbook that says what the alarm means, what to check first, and what the safe actions are. It does not need to be long. "DLQ depth above zero: open the queue, read one message, check the function's error logs by correlation ID, fix or redrive" is enough.

The runbook is also where the team's knowledge stops living in one person's head. On a team of six to eight engineers with a mix of junior and senior people, the runbook is what lets a junior engineer handle a Tuesday night alarm without paging me.

What I would tell my past self

None of this is clever. All of it is the difference between a serverless system that is quiet in production and one that generates a steady stream of mysteries. If you are about to ship one, do these six things in the infrastructure code before the first deploy, because adding them later means touching every function and relearning every lesson at 2 a.m.