Canadian Hospital Chain PDF OCR Parser (AWS Lambda Deployable)

Overview

This project is a lightweight, serverless-ready OCR processing microservice developed for a major hospital chain in Canada to digitize and structure patient lists and appointment reports from PDF documents.

It is designed for serverless environments (specifically deployed via AWS Lambda), providing a FastAPI endpoint to upload PDFs, store them temporarily in Amazon S3, and invoke asynchronous Amazon Textract Document Text Detection jobs. The application then parses the complex multi-column Textract JSON blocks into a structured, clean JSON format.

Key Features

• FastAPI Web Interface: Single endpoint (/detect) that accepts PDF uploads.
• AWS Integration: Interacts seamlessly with S3 for document storage and AWS Textract for OCR.
• Asynchronous PDF Processing: Utilizes Textract's async document text detection (start_document_text_detection) to handle multi-page patient lists.
• Intelligent Layout Parsing: Reconstructs reading order by matching line coordinates (geometry bounding boxes) and regex patterns to build structured metadata.
• Production-Ready Security: Credentials and S3 bucket details are securely configured using environment variables instead of being hardcoded.

---

Architecture & Flow

System Execution Flow

The microservice processes documents according to the following pipeline:

graph TD
    A[Client/Web App] -->|Uploads PDF| B[FastAPI Endpoint /detect]
    B -->|Generates UUID & Validates PDF| C[AWS S3 Bucket]
    C -->|Stores Temp PDF File| D[S3 Storage]
    B -->|Invokes Asynchronous OCR Job| E[AWS Textract]
    E -->|Start Text Detection| F{Job Status Pool}
    F -->|IN_PROGRESS| F
    F -->|SUCCEEDED| G[Get Document Results]
    G -->|Raw Text Blocks JSON| H[TRP Parser & Custom Geometry Logic]
    H -->|Coordinates Matching & Parsing| I[Clean Parsed JSON Response]
    I -->|Returns Patient Metadata & List| A

Loading

Module Breakdown

• app.py: The entry point for the FastAPI application. Sets up S3 integration, handles PDF file validation via magic MIME detection, coordinates S3 uploads, initiates Textract jobs, and contains the geometric text parsing logic to reconstruct patient tabular records.
• main.py: A CLI-based script used for local test execution, simulating the core AWS Textract invocation and parsing loop.
• data.json: Local cache of a raw Amazon Textract response, enabling offline testing of parsing logic.

---

Folder Structure

.
├── .env.example       # Template for environment configuration
├── .gitignore         # Git ignore file for security and cleanliness
├── app.py             # FastAPI entrypoint and core geometry parser
├── main.py            # CLI-based local test client
├── requirements.txt   # Application package dependencies
└── readme.md          # Project documentation

---

Technologies

• Core Framework: FastAPI (Web routing and documentation)
• SDK: Boto3 (AWS SDK for Python)
• MIME Detection: python-magic (Secure file type verification)
• Textract Helper: amazon-textract-response-parser (trp library for parsing Textract geometry)
• Web Server: Uvicorn (ASGI server)

---

Installation & Configuration

Prerequisites

• Python 3.8 or higher.
• Active AWS Account with S3 and Textract permissions.

Local Setup

1. Clone the repository:

   git clone <repository-url>
   cd <repository-directory>

2. Create a virtual environment:

   python -m venv env

3. Activate the virtual environment:

   • Windows:

     .\env\Scripts\activate

   • macOS/Linux:

     source env/bin/activate

4. Install dependencies:

   pip install -r requirements.txt

Configuration

1. Copy the environment template:

   cp env.example .env

2. Configure .env with your AWS details:

   AWS_BUCKET="your-s3-bucket-name"
   KEY="AKIAXXXXXXXXXXXXXXXX"
   SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
   REGION="us-east-1"

---

Usage

Run FastAPI Locally

To launch the FastAPI server locally:

uvicorn app:app --reload --host 0.0.0.0 --port 8000

Open your browser and navigate to http://localhost:8000/docs to interact with the OpenAPI/Swagger interactive documentation.

API Endpoint: /detect (POST)

• Description: Upload a PDF patient list to extract and structure data.

• Request Format: multipart/form-data containing a file field.

• Example cURL:

  curl -X 'POST' \
    'http://localhost:8000/detect' \
    -H 'accept: application/json' \
    -H 'Content-Type: multipart/form-data' \
    -F 'file=@patient_list.pdf;type=application/pdf'

• Example Response JSON:

  {
    "meta_data": {
      "appointment_date": "Monday Aug 03 2026",
      "name": "Dr. Smith Clinic"
    },
    "list": [
      {
        "time": "09:00 AM",
        "dob": "1980-01-01",
        "referred_by": "Dr. Doe",
        "fam_by": "Dr. Family",
        "ohip": "1234567890",
        "code": "XX",
        "f_name": "Jane",
        "l_name": "Doe",
        "phone": "(555) 019-2834",
        "type": "Consultation"
      }
    ]
  }

---

Deployment to AWS Lambda

This project is optimized for deployment as a serverless container or package on AWS Lambda integrated with Amazon API Gateway (using libraries like mangum or by creating a Lambda Web Adapter).

Steps for Deployment

1. Build a Docker image using a base AWS Lambda Python image.
2. Package the requirements.txt dependencies.
3. Configure Environment Variables in the AWS Lambda Console matching the keys in .env.example.
4. Ensure the execution role assigned to the Lambda function has permissions:
   • s3:PutObject on the target S3 bucket.
   • textract:StartDocumentTextDetection and textract:GetDocumentTextDetection.

---

Troubleshooting

magic MIME type issues on Windows

If you encounter errors related to python-magic, ensure that python-magic-bin is installed (it is included in requirements.txt for Windows support). On Linux, you may need to install the system library:

sudo apt-get install libmagic1

AWS Credentials Error

Ensure that your AWS keys are correctly loaded into the .env file or exported in your shell. The client will fallback to dummy parameters if they are not detected, resulting in NoCredentialsError.

---

GitHub Metadata Recommendation

• Suggested Repository Name: canada-hospital-ocr-parser
• Description: A FastAPI and AWS Textract-based PDF parser deployed on AWS Lambda for automating patient list extraction for a major Canadian hospital chain.
• Topics: aws-lambda, aws-textract, fastapi, ocr-parser, pdf-parser, serverless, boto3, canada-healthcare