>_ higan

System Architecture

A Well-Architected Framework Review is one of those processes that takes a lot of time to do properly — going pillar by pillar, mapping each best-practice question to actual evidence in the architecture. I built this tool to compress most of that work without sacrificing the citation quality that makes a WAFR result actionable.

How a review runs

The user uploads a PDF of their solution architecture through a Gradio UI, selects which lenses and pillars to evaluate, and kicks off an analysis. From there a Step Functions state machine takes over.

There are two modes:

Quick mode sends one prompt per pillar to Bedrock — fast, good for directional assessments across all pillars in one pass.

Deep mode evaluates each WAFR question individually and creates an actual workload in the AWS Well-Architected Tool with a baseline milestone, so the output isn't just a report — it's something you can keep working with directly in the AWS console.

Both modes ground their responses against a Bedrock Knowledge Base backed by OpenSearch Serverless, pre-loaded with the official Well-Architected reference documents. This keeps citations accurate and prevents the model from inventing framework details.

Step Functions workflow

prepare_wafr_review          (create Well-Architected Tool workload)
        ↓
extract_document_text        (PyMuPDF → plain text)
        ↓
generate_solution_summary    (250-word Bedrock summary)
        ↓
generate_prompts_for_pillars (KB retrieval → per-question prompts)
        ↓
generate_pillar_question_response ×N   (Map state — parallel)
        ↓
update_review_status         (create baseline milestone → Completed)

The Map state in generate_pillar_question_response runs all questions in parallel — each question is independent, so there's no reason to wait. This cuts total runtime significantly compared to sequential processing. Each Lambda step is independently observable in CloudWatch and individually retryable if Bedrock throttles.

Infrastructure

Fourteen Terraform modules cover the full stack. Key design decisions:

Networking — VPC with private subnets only for Lambda and ECS. Eleven VPC endpoints (Bedrock, SQS, SSM, Lambda, Step Functions, KMS, CloudWatch Logs, X-Ray, ECR, plus S3 and DynamoDB gateway endpoints) so no data plane traffic leaves the VPC
KMS — one CMK per environment with automatic key rotation, applied to S3, DynamoDB, SQS, ECR, OpenSearch, and CloudWatch Logs
ECR — immutable image tags; build_push_ui.sh polls Amazon Inspector scan results after push and fails if any HIGH/CRITICAL finding is detected before the image tag is registered
WAF — rate limiting and AWS managed rules at the CloudFront edge; ALB also has WAF for defence-in-depth
Cognito — admin-created users only (self-registration disabled); MFA available via config

The Makefile is the only supported way to run Terraform in this repo. The backend is a partial configuration — running terraform directly would either fail or apply against the wrong environment. make plan saves the plan file; make apply consumes exactly that file, so what you reviewed is what gets applied.

UI — Gradio on ECS Fargate

The frontend is a Gradio application containerised for linux/amd64 and deployed to ECS Fargate behind CloudFront → ALB. Three tabs:

New WAFR Review — form to configure workload metadata, select lens, choose pillars, upload PDF
Existing WAFR Reviews — pulls all completed workloads from DynamoDB; displays per-pillar findings with citations and risk ratings
WAFR Chat — follow-up questions about any completed assessment, powered by Claude Sonnet 4.6 via Bedrock

Stack

Amazon Bedrock (Claude Sonnet 4.6 + Titan Embed V2) · Bedrock Knowledge Base · OpenSearch Serverless · AWS Step Functions · ECS Fargate · AWS Lambda (Python 3.12) · Amazon S3 · DynamoDB · SQS · Amazon Cognito · CloudFront · WAF · KMS · ECR · Terraform (14 modules)