# aws-samples/sample-costminimizer architecture

> Architecture diagram of the GitHub repository aws-samples/sample-costminimizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-costminimizer
- Repository: https://github.com/aws-samples/sample-costminimizer

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Front-end"]:::app
        API["Python Module API"]:::app
        Container["Docker/EC2 Entrypoints"]:::app
    end

    %% Core Application
    subgraph "Core Application"
        ArgParser["Arguments Parser & Command Factory"]:::app
        ConfigMgr["Configuration Manager"]:::app
        SQLiteDB["SQLite Database"]:::datastore
        AuthMgr["Authentication Manager"]:::app
        ReqParser["Report Request Parser"]:::app
    end

    %% Data Providers & Helpers
    subgraph "Data Providers & Service Helpers"
        subgraph "Report Providers"
            ProviderBase["Provider Base & Factory"]:::app
            CE["CE Reports"]:::app
            CO["CO Reports"]:::app
            CUR["CUR Reports"]:::app
            TA["TA Reports"]:::app
        end
        subgraph "Service Helpers"
            EC2Helper["EC2 Metadata"]:::app
            PricingHelper["Pricing"]:::app
        end
    end

    %% AI Layer
    subgraph "AI Layer"
        BedrockClient["Bedrock GenAI Client"]:::ai
        MCPServer["MCP Server & Tools"]:::ai
    end

    %% Output & Delivery
    subgraph "Output & Delivery"
        OutputHandler["Report Output Handler"]:::app
        SES["Email via SES"]:::aws
        FileSystem["Local FS / S3"]:::datastore
    end

    %% External AWS Services
    subgraph "AWS Services"
        AWSCostExplorer["Cost Explorer"]:::aws
        AWSCO["Compute Optimizer"]:::aws
        AWCUR["Athena / S3 (CUR)"]:::aws
        AWSTA["Trusted Advisor"]:::aws
        AWSAthena["Athena"]:::aws
        AWSS3["S3"]:::aws
        AWSSES["SES"]:::aws
        AWSOrgs["Organizations"]:::aws
        AWSBedrock["Bedrock"]:::aws
    end

    %% Relationships
    CLI -->|invokes| ArgParser
    API -->|calls| ArgParser
    Container -->|entrypoint| CLI

    ArgParser -->|loads| ConfigMgr
    ConfigMgr -->|reads schema| SQLiteDB
    ArgParser -->|uses| AuthMgr
    ArgParser -->|parses| ReqParser

    ReqParser -->|creates request| ProviderBase
    ProviderBase --> CE
    ProviderBase --> CO
    ProviderBase --> CUR
    ProviderBase --> TA

    CE -->|boto3| AWSCostExplorer
    CO -->|boto3| AWSCO
    CUR -->|Athena/S3| AWCUR
    TA -->|boto3| AWSTA

    EC2Helper -->|metadata| AWSCostExplorer
    PricingHelper -->|pricing API| AWSPricing[(Pricing API)]:::aws

    BedrockClient -->|MCP protocol| AWSBedrock
    MCPServer -->|invokes| ArgParser

    ReqParser -->|raw data| OutputHandler
    OutputHandler -->|writes| FileSystem
    OutputHandler -->|sends| SES
    SES -->|via| AWSSES

    FileSystem -->|stores| AWSS3

    %% Click Events
    click CLI "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/arguments/arguments.py"
    click ArgParser "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/commands/factory.py"
    click API "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/CostMinimizer.py"
    click Container "https://github.com/aws-samples/sample-costminimizer/tree/main/Dockerfile"
    click ConfigMgr "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/conf/configuration_manager.py"
    click SQLiteDB "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/config/database.schema.sql"
    click AuthMgr "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/security/cow_authentication.py"
    click AuthMgr "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/security/cow_encryption.py"
    click ReqParser "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/report_request_parser/report_request_parser.py"
    click CE "https://github.com/aws-samples/sample-costminimizer/tree/main/src/CostMinimizer/report_providers/ce_reports/"
    click CO "https://github.com/aws-samples/sample-costminimizer/tree/main/src/CostMinimizer/report_providers/co_reports/"
    click CUR "https://github.com/aws-samples/sample-costminimizer/tree/main/src/CostMinimizer/report_providers/cur_reports/"
    click TA "https://github.com/aws-samples/sample-costminimizer/tree/main/src/CostMinimizer/report_providers/ta_reports/"
    click ProviderBase "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/report_providers/report_providers.py"
    click ProviderBase "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/report_providers/fixed_method.py"
    click EC2Helper "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/service_helpers/ec2.py"
    click PricingHelper "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/service_helpers/pricing.py"
    click BedrockClient "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/genai_providers/bedrock.py"
    click BedrockClient "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/genai_providers/genai_provider_client_base.py"
    click BedrockClient "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/genai_providers/genai_providers.py"
    click MCPServer "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/mcp/server.py"
    click MCPServer "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/mcp/tools.py"
    click OutputHandler "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/report_output_handler/report_output_handler.py"
    click OutputHandler "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/report_output_handler/report_output_pptx.py"
    click OutputHandler "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/report_output_handler/report_output_gen_ai.py"
    click OutputHandler "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/report_output_handler/report_output_folder_crawler.py"
    click OutputHandler "https://github.com/aws-samples/sample-costminimizer/blob/main/src/CostMinimizer/report_output_handler/report_output_report_request_parser.py"

    %% Styles
    classDef app fill:#a8d5e2,stroke:#333,stroke-width:1px
    classDef aws fill:#b0e57c,stroke:#333,stroke-width:1px
    classDef datastore fill:#f4b942,stroke:#333,stroke-width:1px
    classDef ai fill:#d291bc,stroke:#333,stroke-width:1px
```
