AWS Builder Center

Builder Center

From a BOQ PDF to an Auditable Material Decision: Building ReSpec on AWS

From a BOQ PDF to an Auditable Material Decision: Building ReSpec on AWS

ReSpec turns construction BOQs into reviewable recycled-material recommendations and evidence-backed procurement states. Here is how our team built and deployed its serverless pipeline using AWS Lambda, Step Functions, API Gateway, DynamoDB, S3, and a cost-aware PDF extraction fallback.

A procurement engineer does not need another sustainability dashboard.
They need answers to four practical questions:
  1. Which items in this construction BOQ could use recycled material?
  1. Why is each item eligible?
  1. How close is the project to its compliance target?
  1. Was the recommended material actually delivered with evidence?
That is the workflow our team set out to build during Environmental Hacks 2026, part of the Bharat Builds Tour organised by WeMakeDevs in collaboration with AWS.
Our solution is called ReSpec.
ReSpec reads a construction Bill of Quantities, identifies possible applications for recycled construction and demolition material, highlights uncertain cases for human review, and tracks procurement until delivery evidence is recorded.
I was responsible for building its AWS backend, serverless infrastructure, and document-processing pipeline.

The gap between a regulation and an action

Construction projects already produce detailed BOQs containing descriptions, units, and quantities for every material.
However, a BOQ does not directly tell a project team:
  • Which lines may be suitable for recycled material.
  • Which rule supports a recommendation.
  • Whether human approval is required.
  • How many tonnes have been planned or ordered.
  • Whether a claimed delivery has supporting evidence.
This often leaves sustainability requirements disconnected from the procurement workflow.
ReSpec tries to connect those two sides.
Instead of displaying another environmental metric, it converts an existing project document into decisions a procurement or sustainability team can review and act upon.

What changes for the user?

Before ReSpec
With ReSpec
Manually inspect BOQ lines
Upload a PDF or submit structured rows
Interpret inconsistent descriptions and units
Normalize items into a common structure
Search applicable material rules separately
Receive a category and classification reason
Track recommendations in spreadsheets
Store every job and line in DynamoDB
Treat all extracted data as correct
Route uncertain items to human review
Claim sustainable procurement manually
Track Eligible → Planned → Ordered → Verified
Store evidence separately
Connect delivery records with evidence objects
ReSpec does not automatically approve structural decisions. Its purpose is to organise the information, apply deterministic rules, and make human review easier and more traceable.

One BOQ line through the working system

During one of our live structured-row tests, we submitted the following item:
Plain text
Item: 1
Description: Paver blocks
Unit: m²
Quantity: 100
The API created a job and returned a unique job ID.
The processing request then started an AWS Step Functions execution. The workflow normalized the row, classified the description, persisted the result, and moved the job to  NEEDS_REVIEW .
The resulting line included:
Plain text
Category: PAVERS
Classification reason: KEYWORD_MATCH:PAVERS
Classification confidence: 0.82
Category confidence: 0.90
Review status: CLASSIFIED
In this particular test, the Step Functions execution completed in approximately two seconds.
This was important because it demonstrated an actual end-to-end workflow rather than a static interface or mocked architecture.

The AWS architecture

ReSpec uses a serverless, event-oriented architecture:
Plain text
User or frontend
        |
        v
Amazon API Gateway
        |
        v
AWS Lambda API handlers
        |
        +------> Amazon S3
        |          BOQ uploads and evidence
        |
        +------> Amazon DynamoDB
        |          Jobs and normalized lines
        |
        v
AWS Step Functions
        |
        +------> Extract document
        |
        +------> Normalize rows
        |
        +------> Classify materials
        |
        +------> Persist results
        |
        +------> Mark errors
The infrastructure is defined using AWS SAM and deployed through AWS CloudFormation in the  ap-south-1  Region.
The backend uses:
  • Amazon API Gateway for HTTP endpoints.
  • AWS Lambda for API and processing functions.
  • AWS Step Functions for workflow orchestration.
  • Amazon DynamoDB for jobs and processed BOQ lines.
  • Amazon S3 for PDF uploads and delivery evidence.
  • Amazon Textract as an optional OCR mode.
  • Amazon CloudWatch and AWS X-Ray for logging and tracing.
  • AWS SAM for infrastructure-as-code and deployment.

Creating a job

ReSpec supports two input paths.

Structured rows

A client can submit already structured BOQ rows:
Plain text
{
  "source": "ROWS",
  "rows": [
    {
      "itemNumber": "1",
      "description": "Paver blocks",
      "unit": "m2",
      "quantity": 100
    }
  ]
}
The API stores the job in DynamoDB and returns a job ID with the initial status.

PDF documents

For a PDF job, the API creates a unique S3 object key and returns a short-lived presigned upload URL.
The client uploads the PDF directly to S3 using that URL. The document does not have to pass through the main API Lambda, reducing unnecessary payload handling.
After the upload, the processing endpoint starts the Step Functions workflow.

Why Step Functions?

The pipeline contains several stages that can succeed or fail independently.
A document may upload correctly but fail during extraction. Extraction may succeed while normalization encounters an unexpected structure. A later function may fail while writing the final output.
Putting every step inside one Lambda would make failures harder to locate and recover from.
Step Functions gave us:
  • A visible execution history.
  • Clear input and output for every stage.
  • Separate handling for rows and PDFs.
  • Explicit error routing.
  • A foundation for retries and recovery.
  • A unique execution ARN for every processing job.
The workflow chooses the correct route based on the input source.
Structured rows skip document extraction and go directly to normalization. PDF jobs use either the local extraction Lambda or Amazon Textract before joining the same normalize, classify, and persist stages.

Working within cloud-cost constraints

One of our biggest challenges was PDF extraction.
Amazon Textract is useful for scanned and image-based documents, but making the entire demonstration depend on OCR would introduce additional account-access and cost considerations.
We therefore implemented two extraction modes.

Local extraction mode

A Python Lambda extracts text from PDFs that already contain selectable text.
This became the default mode and allowed us to demonstrate the complete PDF workflow without requiring paid OCR for every run.

Amazon Textract mode

Textract remains available as an optional mode for scanned documents that require OCR.
The extraction mode is controlled through an infrastructure parameter, so the workflow does not need to be redesigned when switching between them.
We also tested the complete local PDF path:
  1. Create a PDF job.
  1. Receive a presigned S3 upload URL.
  1. Upload the PDF.
  1. Start the processing pipeline.
  1. Extract its rows.
  1. Normalize and classify them.
  1. Persist the final result.
The test PDF produced five extracted BOQ rows and reached the review stage successfully.
This taught me that cloud engineering is not about using the largest possible number of services. It is about choosing the right service while respecting cost, reliability, and access constraints.

A monorepo packaging challenge

Our team worked independently on the frontend, domain engine, shared contracts, and backend before combining everything into one canonical repository.
The final repository contains:
Plain text
/web        Frontend application
/api        Lambda handlers and PDF extraction
/core       Pure domain and ledger logic
/contracts  Shared types and validation schemas
/infra      AWS SAM infrastructure
/data       Rules and reference data
/docs       Documentation
The API depends on the private workspace packages  @respec/contracts  and  @respec/core .
During SAM packaging, the default Node.js builder initially tried to download these private packages from the public npm registry. They were local monorepo packages, so the registry correctly returned a not-found error.
We solved this structurally by introducing local esbuild bundling through a custom Makefile. Every Node.js Lambda is bundled from the monorepo’s locally installed dependencies before SAM packages it.
This preserved the existing Lambda logic while allowing the backend to reference shared types, schemas, and the ledger reducer.
The Python extraction Lambda was also moved under  /api , and its SAM  CodeUri  was updated accordingly.

Keeping uncertain decisions human-reviewed

ReSpec deliberately avoids presenting every classification as certain.
The pipeline attaches confidence information and classification reasons to processed lines. Unknown descriptions and safety-sensitive construction items can be marked for manual review.
The procurement ledger follows four states:
Plain text
ELIGIBLE → PLANNED → ORDERED → VERIFIED
A recommendation cannot simply jump to  VERIFIED .
Verification requires a delivery record and supporting evidence. Duplicate slips, invalid transitions, and deliveries without confirmed evidence are handled explicitly by the shared ledger logic.
This boundary is important: AWS automates the workflow, but it does not replace engineering judgement.

Security decisions for the prototype

Although ReSpec is a hackathon prototype, we implemented several basic security and operational controls:
  • S3 public access is blocked.
  • Uploaded objects use server-side encryption.
  • Presigned upload URLs expire after five minutes.
  • IAM permissions are scoped per Lambda function.
  • DynamoDB point-in-time recovery is enabled.
  • CloudFormation hides the demo passcode using  NoEcho .
  • Secrets and deployment credentials are excluded from Git.
  • CloudWatch logs include job-related context.
  • AWS X-Ray tracing is enabled.
  • An optional monthly AWS Budget alert can be configured.
The shared demo passcode is only a temporary hackathon control. It is not presented as production authentication.

Verifying the backend

Before integrating and pushing the backend branch, we verified:
Check
Result
API TypeScript build
Passed
API type-check
Passed
Backend unit tests
4 passed
Domain and ledger tests
43 passed
Frontend tests
15 passed
Python PDF extraction tests
3 passed
SAM template validation
Passed
Lambda bundle generation
Passed
Live structured-row workflow
Succeeded
Live PDF workflow
Succeeded
We also checked that no AWS credentials, deployment passcodes, generated dependencies, or local build caches were committed.

Team collaboration

ReSpec was built by a four-member team:
  • Divyansh: technical leadership, contracts, compliance-gap calculator, ledger and integration.
  • Bhavya: AWS backend, serverless infrastructure and processing pipeline.
  • Riya: domain rules, conversions, classification and evaluation.
  • Aarvi: frontend screens, documentation and demo experience.
Shared contracts allowed each workstream to progress independently.
The frontend could build against agreed response shapes, the domain engine could remain pure and testable, and the API could connect those components to AWS without duplicating their logic.
One of my biggest lessons was that integration cannot be left until the final hour. Stable schemas, folder ownership, feature branches, and testable interfaces are just as important as individual features.

Responsible use of AI tools

We used AI coding assistants during development, including Google Antigravity and OpenAI Codex.
They assisted with code generation, architecture review, tests, documentation structure, deployment guidance, and monorepo wiring.
However:
  • The team reviewed the generated code.
  • AI did not decide whether a material was eligible.
  • Regulatory content was checked against the team’s cited sources.
  • The rules engine remains deterministic.
  • Amazon Bedrock is disabled by default.
  • No AI model automatically approves a recommendation.
  • The team remains responsible for every technical and compliance claim.

Current limitations

ReSpec is a working hackathon prototype, not a production certification platform.
Its current limitations include:
  • Local PDF extraction requires selectable text.
  • Scanned PDFs require an OCR service such as Amazon Textract.
  • Material quantities may depend on explicitly labelled assumptions.
  • Recommendations are limited to the rules currently encoded.
  • Facility availability must be independently confirmed.
  • The shared demo passcode must be replaced with proper authentication before production use.
  • Engineers and relevant authorities must review safety-critical decisions.
Stating these limitations is important because environmental impact should not be based on unsupported claims.

What I learned

Building ReSpec taught me how to:
  • Design a multi-stage serverless workflow.
  • Deploy infrastructure using AWS SAM and CloudFormation.
  • Generate S3 presigned upload URLs.
  • Model job and line data in DynamoDB.
  • Orchestrate Lambda functions using Step Functions.
  • Build cost-aware fallbacks for managed services.
  • Debug cloud deployments and workflow executions.
  • Protect secrets and deployment parameters.
  • Connect private packages inside a JavaScript monorepo.
  • Integrate independently developed components without rewriting their logic.
The most satisfying moment was not creating the infrastructure diagram. It was watching a real request pass through the deployed API, complete its Step Functions execution, and return classified BOQ data ready for human review.

Final thoughts

Many environmental tools stop after visualising a problem.
ReSpec attempts to go one step further by helping a project team decide what to review, what to procure, and what evidence is still missing.
It connects an existing construction document to a traceable workflow:
Plain text
BOQ → Recommendation → Human review → Procurement → Evidence
Our prototype does not claim to solve construction waste by itself.
What it demonstrates is a practical way to convert sustainability requirements into actions that can be reviewed, tested, and verified using AWS.
Explore the project:
 ReSpec on GitHub 
Learn more about the event:
 Environmental Hacks — WeMakeDevs × AWS 
# serverless# aws-lambda# aws-step-functions# amazon-dynamodb# sustainability
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article