DEV Community

Sanjay Patoliya
Sanjay Patoliya

Posted on • Originally published at sanjaypatoliya.com

Building an AI Resume Scorer with AWS Textract and Claude

#ai #python #fastapi #aws

What I Built

A full-stack AI application that scores how well a resume matches a job description — giving candidates a score from 0–100 across 5 categories with specific improvement suggestions.

User flow:

  1. Upload a resume PDF
  2. Paste a job description
  3. Get an AI-powered match score with detailed feedback
  4. View history of past analyses

The entire backend pipeline runs on AWS: Textract extracts the resume text, Claude AI does the intelligent scoring, and results are saved to DynamoDB.

Architecture 

Browser
  │
  ▼
CloudFront (HTTPS)
  ├── /* ──────────────► S3 (React static files)
  └── /api/v1/* ───────► ALB
                           │
                           ▼
                      ECS Fargate (FastAPI)
                           │
                      S3 — fetch uploaded PDF
                           │
                      Textract — extract text (OCR)
                           │
                      Claude AI — score + suggestions
                           │
                      DynamoDB — save result
Enter fullscreen mode Exit fullscreen mode

The key architectural decision was routing /api/v1/* through CloudFront to the ALB. This means the frontend uses a single HTTPS endpoint for both static files and API calls — no mixed content issues, no CORS problems.

Tech Stack

Layer Technology
Frontend React 18 + TypeScript + Vite + TailwindCSS
Backend FastAPI (Python 3.12)
AI Anthropic Claude (claude-sonnet-4-6)
OCR AWS Textract
Storage Amazon S3 + DynamoDB
Hosting ECS Fargate + ALB + CloudFront
IaC AWS CDK (Python)

AWS Services Used

Service Purpose
ECS Fargate Serverless container hosting for FastAPI
Application Load Balancer Routes traffic to ECS tasks
CloudFront CDN + HTTPS termination
S3 Resume PDF storage + React static hosting
DynamoDB Analysis results and history
Textract Extract text from resume PDFs
SSM Parameter Store Secure Anthropic API key storage
ECR Docker image registry
VPC + NAT Gateway Private network with internet access for Claude API
AWS CDK (Python) Infrastructure as Code

The Analysis Pipeline

When a user submits a resume and job description, this is what happens:

Step 1 — PDF Upload via Presigned URL

The frontend requests a presigned S3 URL from the backend, then uploads the PDF directly to S3 from the browser. This avoids routing the binary file through the FastAPI server.

# POST /api/v1/upload
def get_presigned_url(file_name: str, content_type: str) -> dict:
    s3_key = f"uploads/{uuid4()}/{file_name}"
    upload_url = s3_client.generate_presigned_url(
        "put_object",
        Params={"Bucket": S3_BUCKET, "Key": s3_key, "ContentType": content_type},
        ExpiresIn=300,
    )
    return {"upload_url": upload_url, "s3_key": s3_key}
Enter fullscreen mode Exit fullscreen mode

Step 2 — Text Extraction with AWS Textract

Once the PDF is in S3, Textract extracts all the text. Textract handles complex PDF layouts — multi-column resumes, tables, headers — much better than simple PDF parsers.

# textract_service.py
def extract_text_from_s3(s3_key: str) -> str:
    response = textract_client.detect_document_text(
        Document={"S3Object": {"Bucket": S3_BUCKET, "Name": s3_key}}
    )
    blocks = [b["Text"] for b in response["Blocks"] if b["BlockType"] == "LINE"]
    return "\n".join(blocks)
Enter fullscreen mode Exit fullscreen mode

Note: detect_document_text is synchronous and works well for standard resumes. If you need to support 10+ page documents, switch to start_document_analysis (asynchronous) — it handles larger files without timing out.

Step 3 — AI Scoring with Claude

The extracted resume text and job description are sent to Claude with a structured prompt that asks for scores across 5 categories and improvement suggestions.

The 5 scoring categories:

  1. Skills Match — how well technical skills align
  2. Experience Level — years and seniority match
  3. Education — degree and field relevance
  4. Keywords — ATS-critical keyword presence
  5. ATS Formatting — resume structure and formatting

Claude returns a structured JSON response. To ensure the LLM's non-deterministic output doesn't break the frontend, I used Pydantic in the FastAPI layer to validate the JSON structure before saving to DynamoDB — if Claude returns an unexpected format, the request fails fast with a clear error rather than silently corrupting data.

{
  "overall_score": 78,
  "categories": [
    { "name": "Skills Match", "score": 85, "rationale": "Strong Python and AWS skills" },
    { "name": "Experience Level", "score": 70, "rationale": "5 years matches requirement" },
    { "name": "Education", "score": 90, "rationale": "Relevant CS degree" },
    { "name": "Keywords", "score": 75, "rationale": "Most keywords present" },
    { "name": "ATS Formatting", "score": 65, "rationale": "Some formatting improvements needed" }
  ],
  "suggestions": [
    "Add quantifiable achievements to your experience section",
    "Include AWS certification names explicitly"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Step 4 — Save to DynamoDB

Results are saved with a UUID as the partition key. DynamoDB PAY_PER_REQUEST billing means no capacity planning and costs nothing when idle.

# dynamodb_service.py
def save_result(result: AnalysisResult) -> None:
    table.put_item(Item={
        "id": result.id,
        "overall_score": result.overall_score,
        "categories": result.categories,
        "suggestions": result.suggestions,
        "created_at": result.created_at.isoformat(),
        "file_name": result.file_name,
    })
Enter fullscreen mode Exit fullscreen mode

API Endpoints

Method Endpoint Description
GET /health Health check
POST /api/v1/upload Get presigned S3 URL
POST /api/v1/analyze Analyze resume vs job description
GET /api/v1/history List past analyses
GET /api/v1/history/{id} Get single result
DELETE /api/v1/history/{id} Delete a result

Infrastructure with AWS CDK

All AWS resources are defined as code using CDK Python, split into 4 stacks:

StorageStack

S3 bucket with server-side encryption and 30-day lifecycle expiry for uploaded PDFs.

DatabaseStack

DynamoDB table with PAY_PER_REQUEST billing — no capacity planning needed.

BackendStack

The most complex stack. VPC with 2 AZs, 1 NAT Gateway (ECS tasks need outbound internet to reach the Anthropic API), ECS Fargate service, and Application Load Balancer.

Key decision: ECS Fargate instead of Lambda for the backend. The Claude AI response can take 10–30 seconds for detailed analysis. Lambda has a 15-minute limit but cold starts and the complexity of streaming responses made Fargate a cleaner choice for this workload. Fargate's stability during long-running LLM inferences over Lambda's potential timeout and cold-start issues was a deliberate choice for reliability.

# backend_stack.py (simplified)
fargate_service = ecs_patterns.ApplicationLoadBalancedFargateService(
    self, "BackendService",
    cluster=cluster,
    cpu=256,
    memory_limit_mib=512,
    task_image_options=ecs_patterns.ApplicationLoadBalancedTaskImageOptions(
        image=ecs.ContainerImage.from_ecr_repository(ecr_repo),
        environment={"APP_ENV": "production"},
        secrets={"ANTHROPIC_API_KEY": ecs.Secret.from_ssm_parameter(api_key_param)},
    ),
)
# ALB timeout extended for Claude response time
fargate_service.load_balancer.set_attribute("idle_timeout.timeout_seconds", "120")
Enter fullscreen mode Exit fullscreen mode

FrontendStack

CloudFront with OAC (Origin Access Control) for S3, SPA routing (404 → index.html), and a /api/v1/* behaviour that proxies to the ALB. Cache invalidation runs automatically on each deploy. This pattern — CloudFront + ALB + S3 — is my go-to for production SPAs. It eliminates the CORS dance entirely and centralises SSL termination at the edge.

Deploy Pipeline

A single make deploy command runs everything:

make deploy
# 1. Runs backend tests (pytest)
# 2. Runs frontend tests (vitest)
# 3. Builds React app (npm run build)
# 4. CDK deploys all 4 stacks
Enter fullscreen mode Exit fullscreen mode

Deployment stops if any test fails — no broken code reaches AWS.

Testing Strategy

Backend — pytest with moto to mock all AWS services. No real AWS credentials needed for tests.

cd backend
pytest                    # all tests with coverage
pytest tests/services/    # service layer only
pytest tests/routers/     # API endpoints only
Enter fullscreen mode Exit fullscreen mode

Frontend — Vitest + Testing Library.

cd frontend
npm test                  # all tests
npm run test:coverage     # with coverage report
Enter fullscreen mode Exit fullscreen mode

Lessons Learned

1. Use presigned URLs for file uploads
Routing PDFs through FastAPI adds unnecessary load and latency. Direct S3 upload from the browser via presigned URL is faster and cheaper.

2. ECS Fargate over Lambda for long AI calls
Lambda works for fast operations but AI scoring takes 10–30 seconds. Fargate containers are always warm and handle this naturally.

3. NAT Gateway is required for private ECS tasks
ECS tasks in a private subnet need a NAT Gateway to reach the Anthropic API. I initially tried without it and the AI calls silently timed out.

4. Extend ALB idle timeout for AI workloads
The default ALB idle timeout is 60 seconds. Claude can take longer for detailed analysis. Setting it to 120s prevents connection resets mid-response.

5. CloudFront routing solves CORS completely
Proxying /api/v1/* through CloudFront to the ALB means the frontend and API share the same domain. Zero CORS configuration needed.

6. SSM Parameter Store for secrets
Never put API keys in environment variables or Docker images. SSM SecureString is injected at container startup — keys never appear in logs or CDK output.

7. Auth is intentionally deferred to v2
The current version has no user authentication. Auth with AWS Cognito is planned for v2: user login, private history per user, and Cognito-authorizer on the API Gateway. Deferring auth kept v1 scope small and shippable.

GitHub

The full source code is available on GitHub:

👉 github.com/sanjaypatoliya/ai-resume-analyzer

About the Author

I'm Sanjay Patoliya — AWS Certified engineer with 7 AWS certifications building production-ready AI systems on AWS.

Originally published at sanjaypatoliya.com

Top comments (0)