Well-Architected IaC Analyzer: a sample Bedrock app that reviews your infrastructure code

What the Well-Architected IaC Analyzer actually is

The problem it addresses is narrow and real. A team has Terraform or CloudFormation in a repository and wants a first pass against AWS Well-Architected guidance before a human review, ideally without reading every question in the framework by hand. This project takes uploaded infrastructure code, or a picture of an architecture diagram, and returns an assessment of how the code aligns with or deviates from best practices, with suggestions attached.

The audience is therefore AWS practitioners who already understand the framework and want a starting point, plus builders who want to see how a Bedrock knowledge base is wired into a real application. The README is explicit that this is a sample for non-production usage and that security and legal teams should be involved before deployment. That sentence should be read as the project's own scope statement, not as boilerplate.

What it is not: a continuous integration gate, a scanner that runs on every pull request, or a replacement for the AWS Well-Architected Tool. The analysis runs through a web application where a user uploads files, which is a different shape of tool from a linter or a CI job.

How the Bedrock knowledge base and the analysis pipeline fit together

The architecture visible in the README is a React front end using the AWS Cloudscape Design System, a backend deployed through AWS CDK, and Amazon Bedrock doing the reasoning. The Well-Architected best practices are not hardcoded into prompts. They are sourced from AWS Well-Architected whitepapers and synchronized with an Amazon Bedrock knowledge base, so the model retrieves the relevant guidance at analysis time.

That retrieval step is what makes the output traceable to a best practice rather than to the model's memory of AWS documentation. It also means the knowledge base is a moving part: if the synchronization is stale, the analysis is stale.

The default vector store for that knowledge base is Amazon S3 Vectors, with OpenSearch Serverless available as an option at deployment. The README claims up to 80 percent cost reduction compared with OpenSearch Serverless while maintaining sub-second query performance. Treat those as vendor figures from the project's own documentation, not as an independent measurement.

Questions are processed in parallel in configurable batches, and the README states a full framework review can be up to 80 percent faster than per-question sequential processing. The default batch size is adjustable between 1 and 12, and the README frames that range as a balance between speed and API throttling risk. That is the honest description of the trade-off: raise the batch size and you push harder against Bedrock quotas.

Deploying it and running a first analysis

The repository ships deployment scripts at the top level: deploy-wa-analyzer.sh and destroy-wa-analyzer.sh, alongside cdk.json and requirements.txt. The Python dependencies pin aws-cdk-lib==2.253.0, constructs, cdklabs.generative_ai_cdk_constructs==0.1.312 and cdk-nag. The README does not print the full deployment sequence, so install the pinned requirements before invoking the deploy script, and read the script itself for the parameters it expects.

pip install -r requirements.txt
./deploy-wa-analyzer.sh

For local development, package.json exposes four scripts that wrap dev.sh. The Docker variants are the default path:

npm run dev:up
npm run dev:down

If you use Finch instead of Docker, the same wrapper takes a different container backend:

npm run dev:up:finch
npm run dev:down:finch

Once the application is running, the first real use is an upload. Open the web interface and provide either a single CloudFormation YAML or JSON template, a Terraform .tf file, a CDK template in any supported language, several files at once, or a ZIP archive of a complete project. Architecture diagrams are accepted as PNG or JPEG. Supporting documents can be attached as PDF, TXT, PNG or JPEG, and PDFs are limited to five files at 4.5MB each.

What you should see is an analysis against the selected lens. Output language can be set from the Output Language menu in Optional Settings, with English, Japanese, Korean, Brazilian Portuguese, Spanish and French available. The README states the selection affects analysis results, recommendations and explanations consistently across file types.

The prioritization matrix and the Analyzer Assistant

Two features go beyond a plain pass or fail report. The first is a prioritization framework built on the Eisenhower Matrix. Every best practice marked Not Applied is scored on Criticality, taken from the knowledge base risk level, on Complexity, meaning remediation effort, and on Priority, which resolves to Immediate, Short-term or Long-term. A dedicated Priorities tab plots those items across four quadrants the README names as Quick wins, Major initiatives, Delegate and Reconsider, with risk criticality on one axis and implementation effort on the other.

Clicking a point opens a panel with the status reason, the recommendation, and the reasons behind the Criticality, Complexity and Priority values. Those reasons matter more than the score itself, because a priority label without an explanation is just an opinion with a color. The analysis can also be filtered by Criticality, Complexity or Priority, and the fields export to CSV, which is the practical route into a remediation backlog.

The second feature is the Analyzer Assistant, a chatbot that answers questions about a specific analysis and about Well-Architected best practices generally. It keeps conversation history with markdown support, and each analysis has its own history that can be downloaded or deleted. There is also a one-click handoff from a matrix point into the assistant, which is a sensible pairing: the chart tells you where to look, the assistant explains why.

Where this sample stops being the right tool

The clearest limitation is stated by the project itself: it is a sample for non-production usage. That is not modesty. A sample carries no operational guarantees, and the README directs you to your security and legal teams before deployment rather than offering a hardening guide.

The second limitation is the deployment surface. This is not a CLI you install and point at a directory. It deploys a web application with a Bedrock knowledge base, a vector store and a container-based local development path, which means ongoing AWS cost and ongoing operational attention. If your need is a fast local check of a Terraform file, this is the wrong shape of tool.

Third, the analysis depends on a knowledge base synchronized from AWS whitepapers. Anything it tells you is bounded by what was synchronized and by the lens you selected. The README lists a wide set of official lenses, from the core framework through Financial Services, Healthcare, Government, Mergers and Acquisitions, Generative AI, Serverless, Machine Learning, IoT, SaaS, Data Analytics, Container Build, DevOps, Migration, Connected Mobility and SAP. A question that is not in the selected lens is not being asked.

Fourth, the parallel processing is a quota negotiation. Batch size runs from 1 to 12 and the README ties the upper end to API throttling risk. On a constrained Bedrock account, a large batch is a way to generate throttling errors, not a way to finish faster.

Finally, the README does not document rollback. There is a destroy-wa-analyzer.sh script in the repository, but the README does not describe what it removes or what state it leaves behind.

How it differs from the AWS Well-Architected Tool

The obvious comparison is the AWS Well-Architected Tool, which the README lists as an integration point rather than a competitor. The difference in approach is the input. The Well-Architected Tool is a questionnaire-driven review: a human answers questions about a workload, and the tool records the answers against pillars and lenses. Its output reflects what the team knows and is willing to write down.

The IaC Analyzer starts from artifacts instead. You hand it templates or a diagram, and the model infers alignment from what the code shows. That catches things a questionnaire misses, such as a security group rule nobody remembered, and misses things code cannot express, such as whether an operational process exists. It also means the quality of the answer is bounded by the quality of the uploaded material, which is why the project accepts supporting documents as additional context.

A second, less obvious alternative is reading the framework yourself. It is slower and it does not scale, but it produces no hallucination risk and no AWS bill. The Analyzer is best understood as a way to prioritize which parts of the framework to read first, which is roughly what the Eisenhower matrix tab is for.

Licence, maintenance and what an upgrade costs

The repository is licensed MIT-0, which is a permissive licence that does not require attribution. The package.json declares "license": "MIT", which is inconsistent with the LICENSE file and the repository metadata. That discrepancy is worth resolving internally before you redistribute anything, though it is not a legal opinion and you should get one if it matters.

The last push to the default branch was on 2026-09-10, and the repository is not archived, so the codebase is recent. The dependency set is the real upgrade cost. aws-cdk-lib is pinned to 2.253.0 and cdklabs.generative_ai_cdk_constructs to 0.1.312, a pre-1.0 construct library, which is the kind of dependency that changes shape between releases. cdk-nag is unpinned, so a fresh install can pull a newer version with stricter checks than the code was written against. Expect to spend time on the CDK layer before you spend time on the analysis features.

The README also names specific Anthropic models, including Claude Fable 5, Claude Opus 4.8 and Claude Sonnet 5, and describes Adaptive Thinking and a 1M token context window for them. Model availability on Bedrock changes independently of this repository, so verify that your chosen model is enabled in your region before assuming the analysis will run.

Editorial conclusion

Adopt it if you want a working reference for wiring Bedrock, a knowledge base and a React review UI together, and you accept the README's non-production warning. Do not adopt it as a compliance gate or as a substitute for an AWS Well-Architected Tool review. Before deploying, check the batch size setting against your Bedrock quotas and confirm which vector store you intend to pay for.

Frequently asked questions

Official sources

1. aws-samples/well-architected-iac-analyzer on GitHub
2. Issues
3. License: MIT-0
4. README