AWS Decision Referee

A production-ready decision support tool that helps users choose between AWS services and architectures through educational trade-off analysis. The system provides structured decision-making guidance without declaring winners, enabling users to learn how to make informed AWS architecture decisions.

Features

• Educational Focus: Teaches decision-making principles rather than providing single answers
• Comprehensive Analysis: Covers cost, complexity, scalability, and operational considerations
• Official Documentation: All information sourced exclusively from AWS documentation
• Performance Optimized: Sub-second response times with intelligent caching
• Production Ready: Includes monitoring, logging, and deployment configurations

Quick Start

Using Docker (Recommended)

git clone <repository-url>
cd aws-decision-referee
docker-compose up --build

Access the application at http://localhost

Local Development

Backend:

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python app.py

Frontend:

cd frontend
python -m http.server 8080

Production Deployment

python start_production.py

API Usage

Analyze AWS Services

curl -X POST http://localhost:5000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "decision_domain": "compute",
    "project_type": "startup_mvp",
    "budget_constraint": "low",
    "traffic_pattern": "medium",
    "team_skill_level": "intermediate",
    "latency_sensitivity": "medium",
    "operational_preference": "fully_managed",
    "growth_expectation": "rapid_growth"
  }'

Health Check

curl http://localhost:5000/api/health

Performance

• Response Times: < 100ms (cached), < 500ms (uncached)
• Throughput: 2+ requests/second sustained
• Memory Usage: < 500MB peak
• Cache Hit Rate: 80-90% typical

Documentation

• API Documentation - Complete API reference
• Deployment Guide - Production deployment instructions
• System Documentation - Architecture and troubleshooting

Architecture

Frontend (HTML/CSS/JS) ↔ Load Balancer (Nginx) ↔ Backend API (Python/Flask)
                                                          ↓
                                                  Decision Engine
                                                          ↓
                                    ┌─────────────────────┼─────────────────────┐
                                    │                     │                     │
                          AWS Service Dataset    Performance Optimizer    Documentation Mapper

Project Structure

aws-decision-referee/
├── backend/                    # Python Flask backend
│   ├── app.py                 # Main Flask application
│   ├── decision_engine.py     # Core decision logic
│   ├── input_validator.py     # Input validation
│   ├── performance_optimizer.py # Caching and monitoring
│   ├── aws_service_dataset.py # AWS service metadata
│   ├── models.py              # Data models and enums
│   ├── requirements.txt       # Python dependencies
│   └── test_*.py             # Test files
├── frontend/                   # HTML/CSS/JavaScript frontend
│   ├── index.html            # Main HTML structure
│   ├── styles.css            # CSS styling
│   └── script.js             # JavaScript functionality
├── Dockerfile                 # Docker configuration
├── docker-compose.yml         # Docker Compose setup
├── nginx.conf                 # Nginx configuration
├── start_production.py        # Production startup script
├── API_DOCUMENTATION.md       # API reference
├── DEPLOYMENT.md              # Deployment guide
├── SYSTEM_DOCUMENTATION.md    # System architecture
└── .kiro/specs/              # Specification documents
    └── aws-decision-referee/
        ├── requirements.md    # Feature requirements
        ├── design.md         # System design
        └── tasks.md          # Implementation tasks

Testing

# Backend tests
cd backend
python -m pytest test_*.py -v

# Performance validation
python validate_performance.py

# Integration tests
python test_integration_comprehensive.py

Development Status

✅ Completed Features:

• Core decision engine with rule-based logic
• AWS service dataset with 31+ services
• Performance optimization and caching
• Input validation and error handling
• Comparison matrix generation
• Steering summary creation
• Frontend interface with responsive design
• API endpoints with comprehensive error handling
• Performance monitoring and health checks
• Property-based testing framework
• Integration testing
• Production deployment configuration
• Comprehensive documentation

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run performance validation
5. Submit a pull request

License

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

Support

• Check System Documentation for troubleshooting
• Review API Documentation for usage examples
• Run python validate_performance.py for system diagnostics