How aws-samples/sample-costminimizer works
Project Type and Purpose
• CostMinimizer is an open-source CLI and Python module for AWS cost analysis and optimization.
• It aggregates data from AWS Cost Explorer, Trusted Advisor, Compute Optimizer and CUR, applies AI recommendations via Bedrock, and outputs Excel/PowerPoint reports or serves data via an MCP server.
File-Structure Analysis
• src/CostMinimizer/arguments → CLI argument parser
• src/CostMinimizer/commands → Command implementations (command pattern + factory)
• src/CostMinimizer/config & conf → Configuration manager, local SQLite DB schema, YAML loaders
• src/CostMinimizer/security → Encryption/authentication
• src/CostMinimizer/report_providers → Pluggable adapters for CE, CO, CUR, TA, each with sub-folders per report
• src/CostMinimizer/service_helpers → Low-level AWS service calls (EC2 metadata, pricing)
• src/CostMinimizer/genai_providers → AI integration (Bedrock, generic provider base)
• src/CostMinimizer/report_output_handler → Formatting into Excel/PPTX/JSON
• src/CostMinimizer/mcp → MCP server (“start-costminimizer-mcp-server.sh”) for AI assistants
• Configuration files, Dockerfile, entry scripts (sh/ps1/bat), and tests at root for packaging and CI.
Key Architectural Insights from README
• Multi-stage data flow: Data Collection → Processing → AI Analysis → Output
• Command-pattern for CLI operations, Singleton pattern for shared resources (logger, config)
• Supports three modes: local CLI, Python module, Docker container (and Windows EC2 AMI)
• Integrates with AWS IAM, S3, Athena, SES, and Bedrock.
Main Components
a. Presentation Layer
• CLI Front-end
• Python Module API
• Docker Container / Windows EC2 Host
b. Core Application
• Arguments Parser & Command Factory
• Configuration Manager & SQLite DB
• Authentication Manager (credentials, encryption)
• Report Request Parser
c. Data Providers & Helpers
• Report Providers (CE, TA, CO, CUR modules)
• Service Helpers (EC2 metadata, pricing)
d. AI Layer
• genai_providers (Bedrock client)
• MCP Server exposing tools to AI assistants
e. Output & Delivery
• Report Output Handler (Excel, PPTX)
• Email via SES
• Local file system / S3
f. External Systems
• AWS Services (Cost Explorer, Compute Optimizer, Trusted Advisor, Athena, S3, SES, Organizations, Bedrock)
Relationships and Data Flows
• CLI/Module/API → Core App → Config + Auth → Report Providers → AWS APIs
• Raw data → Processing / normalization → AI Analysis → Report Output
• Report Output → File System / S3 → (optional) SES email
• MCP Server listens for AI assistant requests → Core App commands → returns JSON data
Architectural Patterns & Principles
• Command Pattern (commands folder + factory)
• Singleton for Config/Logger
• Factory for instantiating report providers
• Modular layering: Presentation → Core → Providers → Output
• Pluggable architecture for adding new AWS services or output formats
Technologies & Frameworks
• Python 3.8+ with argparse, boto3, pyyaml
• SQLite (via SQL scripts under config/)
• AWS services: Cost Explorer, CUR (Athena + S3), Compute Optimizer, Trusted Advisor, SES, Organizations, Bedrock
• AI: AWS Bedrock (genai_providers)
• Docker for containerization
• MCP Protocol for AI assistant integration