Well-Architected IaC Analyzer: A CDK-Deployed Bedrock Sample for Grading CloudFormation, Terraform and Diagrams
Sample Generative AI tool for evaluating Infrastructure as Code and architecture diagrams against AWS Well-Architected best practices.
At a glance
- What is it?
- AWS publishes this TypeScript sample as a non-production demonstration of generative AI review against Well-Architected best practices. It is a useful reference architecture for teams building their own review pipeline, not a drop-in compliance gate.
- Who is it for?
- Adopt this if you want a working reference for wiring Amazon Bedrock, a synchronized Well-Architected knowledge base and a React front end into an IaC review workflow, and you have the AWS and Bedrock model access to stand it up. Do not adopt it if you need a production compliance gate, because the README states plainly that it is a sample for non-production usage and that security and legal review must happen before deployment.
- Can I use it commercially?
- Yes. MIT-0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The review gap this sample is aimed at
Well-Architected reviews are usually a conversation. Someone reads a design document, asks questions, and writes findings into the AWS Well-Architected Tool. That works for a handful of workloads and falls apart when the same team is shipping dozens of CloudFormation stacks or Terraform modules a quarter. The code is already in the repository, but nobody is reading it against the framework before it lands.
This project targets that gap. According to the README, it is a sample that demonstrates how generative AI can evaluate infrastructure code for alignment with best practices. The intended input is not a prose design document but the artifacts themselves: CloudFormation YAML or JSON, Terraform .tf files, CDK templates in any supported language, zip archives of multi-file projects, PNG and JPEG architecture diagrams, and PDF architectural documentation of up to five files at 4.5MB each.
The audience is narrower than the feature list suggests. This is for platform or cloud engineering teams who already run AWS CDK deployments and want to see how a Bedrock-backed analysis pipeline is assembled. It is not aimed at an auditor who wants a verdict, and it is not a hosted service. You deploy it into your own account.
How the analysis pipeline is put together
The mechanism described in the README is retrieval-augmented generation over a curated corpus. Well-Architected best practices are sourced from AWS Well-Architected whitepapers and synchronized with an Amazon Bedrock knowledge base. When you submit code or a diagram, the application sends it to Bedrock, which analyzes the infrastructure against those best practices and returns findings describing how the code aligns with or deviates from them.
Two details in the README are worth separating from the marketing around them. First, the vector store. S3 Vectors is the default backing store for the Bedrock knowledge base, with OpenSearch Serverless still available as a deployment option. That is a real architectural decision, not a footnote: it changes what infrastructure you operate and what you pay for. The README claims up to 80% cost reduction compared to OpenSearch Serverless with sub-second query performance, but those figures are the project's own and I have not reproduced them.
Second, parallelism. The tool processes Well-Architected or lens questions in configurable batches, with a default batch size adjustable between 1 and 12. The README claims a full framework review can complete up to 80% faster than per-question sequential processing. The upper bound of 12 exists for a reason: each parallel question is a Bedrock call, and pushing the batch size up raises throttling risk. That tension between wall-clock time and API limits is the main operational knob in the system.
The analysis output is structured rather than free text. Each Not Applied best practice gets a Criticality score derived from the knowledge base risk level, a Complexity score for remediation effort, and a Priority of Immediate, Short-term or Long-term derived through an Eisenhower Matrix. A Priorities tab plots these on a risk-versus-effort grid across four quadrants the README names Quick wins, Major initiatives, Delegate and Reconsider. That is the most opinionated part of the design, and it is what separates the output from a raw list of findings.
Deploying it: CDK, Bedrock model access and the batch size key
The repository is TypeScript and the topics list includes cdk, so deployment runs through AWS CDK. The README does not reproduce the exact bootstrap and deploy commands in the material available here, so treat the CDK app in the repository as the source of truth for the stack names and context values rather than any command I could quote.
What the README does specify are the choices you make along the way. The vector store is selected at deployment time: S3 Vectors by default, OpenSearch Serverless as an alternative. Batch size is a configuration value with a range of 1 to 12 and a default inside that range. Output language is selected in the application's Optional Settings menu under Output Language, with English, Japanese, Korean, Brazilian Portuguese, Spanish and French supported, and the selection applies to analysis results, recommendations and explanations across all file types.
Model access is the prerequisite that trips people up. The README lists support for Claude Fable 5, Claude Opus 4.8 and Claude Sonnet 5, and states that these support a 1M token context window, which is what makes single-pass analysis of larger IaC projects plausible. Those model names do not correspond to anything I can verify independently from this material, and Bedrock model availability is regional. Confirm what is actually enabled in your account before assuming the deployment will work.
The README also carries an explicit warning: this is a sample project for non-production usage, and you should work with your security and legal teams to meet organizational security, regulatory and compliance requirements before deployment. That is the project telling you it has not done that work for you.
The chatbot, custom lenses and the knowledge base dependency
The Analyzer Assistant is a chatbot layered on top of analysis results. The README describes it as enabling users to ask questions, seek clarification and receive guidance about results and Well-Architected best practices, with conversation history rendered in markdown and downloadable or deletable per analysis. Clicking a point on the Priorities matrix can hand that best practice to the assistant in one click, which is a sensible way to connect a finding to an explanation without making the user retype context.
Custom lenses are the extension point that matters for anyone with internal standards. The README describes defining custom pillars, questions and best practices specific to security policies, compliance requirements or internal standards, and integrating custom lens documentation in PDF form with the Bedrock knowledge base. A separate Custom Lenses Guide in the repository is referenced for step-by-step instructions. That guide is where the real work lives: the quality of your custom lens analysis depends on how well you author the lens documentation that gets ingested.
This is also where the architecture's limits show. Everything the analyzer knows about best practices comes from the synchronized knowledge base. If a practice is not represented in the whitepapers or your custom lens PDFs, the model has no grounding for it, and the finding you get back is whatever the model infers from the code alone. The README does not describe a mechanism for detecting that condition or flagging low-confidence findings, so a plausible-sounding recommendation and a well-grounded one look the same in the output.
Where this is the wrong tool
The most important limitation is stated by the project itself: it is a sample for non-production usage. That is not boilerplate. A sample deployed into an account inherits whatever IAM roles, network exposure and data handling the sample author chose, and the README explicitly defers security, regulatory and compliance review to your own teams. If your requirement is a control that blocks a non-compliant stack from deploying, this is the wrong shape of tool entirely. It produces findings and recommendations for a human to read.
The second limitation is determinism. A Bedrock-backed analysis of the same Terraform file is not guaranteed to return identical findings on two runs, and the README offers no discussion of reproducibility, evaluation or accuracy measurement. For a team deciding whether to remediate a finding, that matters. You cannot treat the Criticality and Priority scores as authoritative thresholds, because they are derived from a knowledge base risk level and a model-assessed complexity, not from a fixed rule set.
Third, the feature list is broad in a way that invites over-reading. Diagram-to-IaC generation, PDF analysis with chart and image interpretation, multi-lens support across a long list of industry and technology lenses, and localization into six languages are all described. Each of those is a distinct capability with its own failure modes, and the README does not describe accuracy characteristics for any of them. A team that deploys this expecting reliable diagram-to-template conversion is likely to be disappointed, and the README gives no basis for calibrating that expectation.
Finally, there are no releases retrieved for this repository. Upgrades mean tracking the main branch, which is a meaningful maintenance consideration for anyone planning to run it long term.
What you would use instead, and how the approaches differ
The obvious alternative is the AWS Well-Architected Tool itself. The difference is the input and the unit of work. The Well-Architected Tool is a structured questionnaire that a human answers about a workload, producing a review record tied to an AWS account. It is deterministic, it is a first-party service with a support path, and it does not require you to deploy anything. What it does not do is read your Terraform. The analyzer inverts that: it reads the artifacts directly and infers the answers, which scales to more workloads but trades away determinism and the formal review record. The README notes integration with the AWS Well-Architected Tool, so the two are not mutually exclusive, though the material does not describe what that integration actually does.
The other realistic alternative is a static analysis tool such as cfn-lint or Checkov. Those are rule-based: a finding fires because a pattern matched, and the same input always produces the same output. The analyzer's findings come from a model reasoning over retrieved best practice text, which means it can surface issues no rule was written for, and it can also surface issues that are not there. The trade is coverage and flexibility against reproducibility. A rule-based scanner is the right tool for a CI gate; this sample is the right tool for a second pass that a human reviews.
Where the analyzer has no equivalent among those alternatives is the architecture diagram path. Neither the Well-Architected Tool nor a linter accepts a PNG of a whiteboard drawing and produces findings, and the README states the tool can generate corresponding IaC templates from diagrams following AWS best practices. That capability has no direct counterpart in the tools above, which is also why it deserves the most skepticism.
Licence, maintenance and what to verify before you commit
The repository is MIT-0. That is the most permissive option in the MIT family: it drops the attribution requirement that plain MIT carries, so you can reuse the code in a commercial or closed product without including a notice. It also means AWS is under no obligation to maintain it for you, and the README's non-production framing is consistent with that. Nothing here is legal advice; if the licence terms matter to your organization, have counsel read them rather than an article.
Maintenance cost is the part that is easy to underestimate. You are operating a CDK deployment, a Bedrock knowledge base with a synchronized corpus of Well-Architected whitepapers, and either an S3 Vectors store or an OpenSearch Serverless collection. The knowledge base synchronization is the ongoing piece: as AWS updates the framework or the lenses, the corpus needs to be refreshed, and the README does not describe how that synchronization is triggered or how you would detect that it has gone stale. If you add custom lenses, you own the authoring and re-ingestion of that documentation as your internal standards change.
Before deploying, verify the two things that are cheapest to check and most expensive to discover late. Confirm the specific Claude models named in the README are enabled for your account in your target region, since the 1M token context window claim depends on them. Then decide between the default S3 Vectors store and OpenSearch Serverless, and check whether the batch size default sits comfortably below your account's Bedrock throttling limits. Those three checks come before any evaluation of whether the findings are any good.
Editorial conclusion
Adopt this if you want a working reference for wiring Amazon Bedrock, a synchronized Well-Architected knowledge base and a React front end into an IaC review workflow, and you have the AWS and Bedrock model access to stand it up. Do not adopt it if you need a production compliance gate, because the README states plainly that it is a sample for non-production usage and that security and legal review must happen before deployment. Before spending time on it, verify two things: that the Claude models listed in the README are enabled in your target Bedrock region, and whether your deployment will use the default S3 Vectors store or the OpenSearch Serverless option, since that choice is made at deployment time and affects both cost and what you have to operate.
Community notes