AWS Well-Architected Review Automation (AutoWAFR)

AutoWAFR is an AI-powered tool designed to automate AWS Well-Architected Reviews (WAR) by analyzing meeting transcripts and generating:

• Pillar Coverage Analysis: Identifies which pillars of the framework have sufficient information to review.
• AWS Well-Architected Tool (WAT) Answers: Formatted answers, notes, and justifications ready to copy or push directly.
• Direct AWS Console Sync: Creates workloads and pushes answers directly to the AWS Well-Architected Tool console using the official AWS API.
• Professional Reports: Polished .docx documents containing executive summaries, risk tables, gaps, and recommendations.

AutoWAFR can be run either as a lightweight CLI Tool or as a full-featured Web Application with authentication, persistent database storage, and a beautiful UI.

---

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│  Transcript(s)  │────▶│  Transcript      │────▶│  Coverage           │
│  (.txt files)   │     │  Processor       │     │  Analyzer           │
└─────────────────┘     └──────────────────┘     └─────────────────────┘
                                                              │
                              ┌────────────────────────────┘
                              ▼
                   ┌──────────────────────┐
                   │  LLM Inference       │
                   │  (Claude/GPT/Bedrock)│
                   └──────────┬───────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
     ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
     │ WAT Answers │  │ JSON Export │  │ DOCX Report │
     │ (.txt)      │  │ (.json)     │  │ (.docx)     │
     └─────────────┘  └─────────────┘  └─────────────┘

---

Quick Start

Option A: Local Setup (CLI & Web UI)

1. Prerequisites

Ensure you have Python 3.10+, Node.js (for report generation), and PostgreSQL installed and running.

2. Install Dependencies

# Install Python packages
pip install -r requirements.txt

# Install Node.js packages (from root directory)
npm install

3. Configure Environment

Create a .env file in the project root (use .env.example as a template):

cp .env.example .env

Fill in your database URL and API keys for the LLM providers you want to use (Groq, Anthropic, OpenAI, or AWS Bedrock).

4. Run the Application

• To run the Web UI locally:

  streamlit run web/app.py

• To run the CLI:

  python src/war_orchestrator.py transcripts/sample_wafr_discussion.txt --workload "My Workload"

---

Option B: Docker Setup (Recommended)

AutoWAFR is fully containerized. A convenience script ./autowafr.sh is provided for managing the Docker environment.

1. Run Setup Script

chmod +x setup.sh
./setup.sh

This script will check dependencies, help you configure your .env settings, build the containers, and start the application.

2. Management Commands

Use ./autowafr.sh for easy management:

• ./autowafr.sh start - Start the stack (accessible at http://localhost:8501)
• ./autowafr.sh stop - Stop all containers
• ./autowafr.sh restart - Restart the stack
• ./autowafr.sh logs - Follow live container logs
• ./autowafr.sh db - Open PostgreSQL shell

---

Features

1. Transcript Processor

AutoWAFR parses raw transcripts from sources like Gong, Google Meet/Gemini, and generic plain-text formats. It automatically handles speaker mapping, cleans filler words, and ignores timestamps.

2. Coverage Analyzer

Estimates how much information is available for each of the 5 pillars by matching keywords against the Well-Architected Framework question bank. It flags the review status as:

• PROCEED (≥50% coverage): Full review recommended.
• PARTIAL (30-50% coverage): Proceed with covered pillars.
• INSUFFICIENT (<30% coverage): More transcript data needed.

3. Multiple LLM Provider Support

Abstracted API client supporting:

• Groq (Recommended for speed and cost)
• Anthropic Claude (Excellent for deep reasoning)
• OpenAI GPT
• AWS Bedrock (Ideal for enterprise compliance)

4. Direct AWS WAT Sync

Syncs review answers directly to your AWS account. It maps AutoWAFR question IDs to AWS Well-Architected Tool question IDs, selects appropriate best practice choices, writes justifications to the notes, and updates the console.

Configure separate WAT_AWS_ACCESS_KEY_ID and WAT_AWS_SECRET_ACCESS_KEY credentials in your .env to restrict permissions.

---

Command Line (CLI) Options

Option	Description
--workload	Workload name (default: "Workload")
--coverage-only	Only check coverage, skip LLM analysis
--provider	LLM provider: anthropic, bedrock, openai, groq, mock (auto-detected if not specified)
--model	Model ID (uses sensible defaults per provider)
--region	AWS region for Bedrock (default: us-east-1)
--output-dir	Output directory (default: ./outputs)
--pillars	Specific pillars to analyze (e.g., security reliability)

---

Project Structure

autowafr/
├── data/
│   ├── waf_question_bank.json        # All WAF questions, keywords, and best practices
│   └── wellarchitected-framework.pdf # Reference framework document
├── migrations/
│   └── 001_wat_workloads.sql         # SQL migrations for database setup
├── src/
│   ├── war_orchestrator.py           # CLI Entry point & orchestrator
│   ├── transcript_processor.py       # Transcript formatting and parsing
│   ├── waf_analyzer.py               # WAF pillar mapping & coverage logic
│   ├── llm_inference.py              # LLM client abstractions
│   ├── wat_client.py                 # AWS Well-Architected Tool integration
│   └── report_generator.js           # DOCX report generator (Node.js)
├── transcripts/                      # Transcript files directory
│   └── sample_wafr_discussion.txt    # Synthetic transcript for testing
├── web/                              # Streamlit Web Application
│   ├── app.py                        # Web UI Entry point
│   ├── auth.py                       # User registration and authentication
│   ├── database.py                   # DB connection manager
│   ├── models.py                     # SQLAlchemy ORM models
│   ├── repository.py                 # DB repositories for data operations
│   ├── components/                   # Shared UI components
│   └── pages/                        # Multi-page Streamlit views
├── autowafr.sh                       # Docker orchestration script
├── docker-compose.yml                # Docker compose services config
├── setup.sh                          # One-click Ubuntu system installation script
└── LICENSE                           # MIT License details

---

Limitations

• Transcript Dependency: Accuracy depends heavily on transcript clarity and completeness.
• Validation: High-risk issues and choices should be verified by a qualified AWS Solutions Architect before final submission.
• Notes Limit: AWS WAT console limits notes to 2048 characters; justifications are automatically truncated to fit.

---

Future Enhancements

• MCP server integration for real-time transcript processing.
• Direct AWS WAT API integration.
• Support for Well-Architected Lenses (SaaS, Serverless, etc.).
• Multi-workload comparison.
• Remediation tracking.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.