# lamvl830/aws-cost-waste-detector architecture

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

- Interactive diagram: https://gitdiagram.com/lamvl830/aws-cost-waste-detector
- Repository: https://github.com/lamvl830/aws-cost-waste-detector

## Overview

AWS Cost Waste Detector is a self-hosted FinOps application that scans AWS resources, estimates avoidable costs, tracks findings over time, ranks opportunities, and produces private reports and alerts. Its principal scheduled workflow is EventBridge Scheduler → Lambda → regional resource scans and pricing → finding persistence, lifecycle reconciliation, and prioritization → notifications and HTML report publication. The README documents EC2 utilization analysis, multi-region scans, and deployment services; source excerpts and the SOURCE INDEX support the implementation links shown. Some service wiring is documented rather than directly excerpted.

Main entry points: [`src/aws_cost_waste_detector/detector.py`](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/detector.py) (Scan orchestrator), [`src/aws_cost_waste_detector/lambda_handler.py`](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/lambda_handler.py) (Lambda handler), [`src/aws_cost_waste_detector/ec2_idle.py`](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/ec2_idle.py) (Idle EC2 analysis), [`src/aws_cost_waste_detector/scanners/ebs.py`](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/scanners/ebs.py) (Unattached EBS scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Scheduled workflow"]
  node_lambda["Lambda handler<br/>[lambda_handler.py]"]
  node_detector["Scan orchestrator<br/>[detector.py]"]
end

subgraph group_detection["Detection and pricing"]
  node_ebs_scan["Unattached EBS scan<br/>[ebs.py]"]
  node_eip_scan["Unused EIP scan<br/>[eip.py]"]
  node_ec2_idle["Idle EC2 analysis<br/>[ec2_idle.py]"]
  node_ec2_discovery["EC2 discovery<br/>[ec2.py]"]
  node_metrics["Utilization metrics"]
  node_ebs_pricing["EBS pricing<br/>[ebs.py]"]
  node_eip_pricing["Public IPv4 pricing<br/>[eip.py]"]
  node_ec2_pricing["EC2 pricing<br/>[ec2_pricing.py]"]
end

subgraph group_findings["Finding management"]
  node_finding["Finding model<br/>[models.py]"]
  node_lifecycle["Lifecycle rules<br/>[lifecycle.py]"]
  node_priority["Priority scoring<br/>[prioritization.py]"]
  node_storage[("Finding history<br/>[dynamodb.py]")]
  node_reconciliation["Scan reconciliation<br/>[reconciliation.py]"]
end

subgraph group_outputs["Reports and alerts"]
  node_summary["Cost summary<br/>[reporting.py]"]
  node_html["HTML report<br/>[html_report.py]"]
  node_publisher["Report publisher"]
  node_notifier["SNS notifier<br/>[notifier.py]"]
end

node_scheduler(("EventBridge Scheduler"))
node_sns["Amazon SNS"]
node_s3[("Private S3 bucket")]
node_aws_resources["AWS resources"]
node_cloudwatch["Amazon CloudWatch"]
node_pricing_api["AWS Pricing API"]
node_user(("Report recipient"))

node_scheduler -->|"invokes"| node_lambda
node_lambda -->|"runs scans"| node_detector
node_detector -->|"scans volumes"| node_ebs_scan
node_detector -->|"scans addresses"| node_eip_scan
node_detector -->|"scans idle instances"| node_ec2_idle
node_ebs_scan -->|"gets storage price"| node_ebs_pricing
node_eip_scan -->|"gets address price"| node_eip_pricing
node_ec2_idle -->|"lists instances"| node_ec2_discovery
node_ec2_idle -->|"reads utilization"| node_metrics
node_ec2_idle -->|"estimates compute savings"| node_ec2_pricing
node_ebs_scan -->|"creates findings"| node_finding
node_eip_scan -->|"creates findings"| node_finding
node_ec2_idle -->|"creates findings"| node_finding
node_detector -->|"persists findings"| node_storage
node_detector -->|"scores findings"| node_priority
node_storage -->|"determines status"| node_lifecycle
node_storage -->|"calculates stored priority"| node_priority
node_detector -->|"reconciles findings"| node_reconciliation
node_detector -->|"builds summary"| node_summary
node_lambda -->|"renders report"| node_html
node_lambda -->|"publishes report"| node_publisher
node_publisher -->|"stores report"| node_s3
node_detector -->|"sends finding alerts"| node_notifier
node_lambda -->|"sends report summary"| node_notifier
node_notifier -->|"publishes messages"| node_sns
node_sns -->|"delivers alerts"| node_user
node_aws_resources -->|"provides volume data"| node_ebs_scan
node_aws_resources -->|"provides address data"| node_eip_scan
node_aws_resources -->|"provides instances"| node_ec2_discovery
node_metrics -->|"queries metrics"| node_cloudwatch
node_ebs_pricing -->|"queries prices"| node_pricing_api
node_eip_pricing -->|"queries prices"| node_pricing_api
node_ec2_pricing -.->|"queries prices"| node_pricing_api
node_s3 -->|"serves temporary link"| node_user

click node_lambda "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/lambda_handler.py"
click node_detector "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/detector.py"
click node_ebs_scan "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/scanners/ebs.py"
click node_eip_scan "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/scanners/eip.py"
click node_ec2_idle "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/ec2_idle.py"
click node_ec2_discovery "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/ec2.py"
click node_metrics "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/cloudwatch_metrics.py"
click node_ebs_pricing "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/pricing/ebs.py"
click node_eip_pricing "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/pricing/eip.py"
click node_ec2_pricing "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/ec2_pricing.py"
click node_finding "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/models.py"
click node_lifecycle "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/lifecycle.py"
click node_priority "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/prioritization.py"
click node_storage "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/storage/dynamodb.py"
click node_reconciliation "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/reconciliation.py"
click node_summary "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/reporting.py"
click node_html "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/html_report.py"
click node_publisher "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/report_publisher.py"
click node_notifier "https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/notifier.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lambda,node_detector toneBlue
class node_ebs_scan,node_eip_scan,node_ec2_idle,node_ec2_discovery,node_metrics,node_ebs_pricing,node_eip_pricing,node_ec2_pricing,node_s3 toneAmber
class node_finding,node_lifecycle,node_priority,node_storage,node_reconciliation,node_pricing_api toneMint
class node_summary,node_html,node_publisher,node_notifier,node_scheduler toneRose
class node_sns,node_aws_resources,node_cloudwatch,node_user toneIndigo
```

## Components

### Scheduled workflow

- [Lambda handler](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/lambda_handler.py): `src/aws_cost_waste_detector/lambda_handler.py`
- [Scan orchestrator](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/detector.py): `src/aws_cost_waste_detector/detector.py`

### Detection and pricing

- [Unattached EBS scan](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/scanners/ebs.py): `src/aws_cost_waste_detector/scanners/ebs.py`
- [Unused EIP scan](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/scanners/eip.py): `src/aws_cost_waste_detector/scanners/eip.py`
- [Idle EC2 analysis](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/ec2_idle.py): `src/aws_cost_waste_detector/ec2_idle.py`
- [EC2 discovery](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/ec2.py): `src/aws_cost_waste_detector/ec2.py`
- [Utilization metrics](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/cloudwatch_metrics.py): `src/aws_cost_waste_detector/cloudwatch_metrics.py`
- [EBS pricing](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/pricing/ebs.py): `src/aws_cost_waste_detector/pricing/ebs.py`
- [Public IPv4 pricing](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/pricing/eip.py): `src/aws_cost_waste_detector/pricing/eip.py`
- [EC2 pricing](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/ec2_pricing.py): `src/aws_cost_waste_detector/ec2_pricing.py`

### Finding management

- [Finding model](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/models.py): `src/aws_cost_waste_detector/models.py`
- [Lifecycle rules](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/lifecycle.py): `src/aws_cost_waste_detector/lifecycle.py`
- [Priority scoring](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/prioritization.py): `src/aws_cost_waste_detector/prioritization.py`
- [Finding history](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/storage/dynamodb.py): `src/aws_cost_waste_detector/storage/dynamodb.py`
- [Scan reconciliation](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/reconciliation.py): `src/aws_cost_waste_detector/reconciliation.py`

### Reports and alerts

- [Cost summary](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/reporting.py): `src/aws_cost_waste_detector/reporting.py`
- [HTML report](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/html_report.py): `src/aws_cost_waste_detector/html_report.py`
- [Report publisher](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/report_publisher.py): `src/aws_cost_waste_detector/report_publisher.py`
- [SNS notifier](https://github.com/lamvl830/aws-cost-waste-detector/blob/main/src/aws_cost_waste_detector/notifier.py): `src/aws_cost_waste_detector/notifier.py`

### Other components

- **EventBridge Scheduler**
- **Amazon SNS**
- **Private S3 bucket**
- **AWS resources**
- **Amazon CloudWatch**
- **AWS Pricing API**
- **Report recipient**

## Connections

- EventBridge Scheduler → Lambda handler: invokes (evidence: `README.md`)
- Lambda handler → Scan orchestrator: runs scans (evidence: `src/aws_cost_waste_detector/lambda_handler.py`)
- Scan orchestrator → Unattached EBS scan: scans volumes (evidence: `src/aws_cost_waste_detector/detector.py`)
- Scan orchestrator → Unused EIP scan: scans addresses (evidence: `src/aws_cost_waste_detector/detector.py`)
- Scan orchestrator → Idle EC2 analysis: scans idle instances (evidence: `src/aws_cost_waste_detector/detector.py`)
- Unattached EBS scan → EBS pricing: gets storage price (evidence: `src/aws_cost_waste_detector/scanners/ebs.py`)
- Unused EIP scan → Public IPv4 pricing: gets address price (evidence: `src/aws_cost_waste_detector/scanners/eip.py`)
- Idle EC2 analysis → EC2 discovery: lists instances (evidence: `src/aws_cost_waste_detector/ec2_idle.py`)
- Idle EC2 analysis → Utilization metrics: reads utilization (evidence: `src/aws_cost_waste_detector/ec2_idle.py`)
- Idle EC2 analysis → EC2 pricing: estimates compute savings (evidence: `src/aws_cost_waste_detector/ec2_idle.py`)
- Unattached EBS scan → Finding model: creates findings (evidence: `src/aws_cost_waste_detector/scanners/ebs.py`)
- Unused EIP scan → Finding model: creates findings (evidence: `src/aws_cost_waste_detector/scanners/eip.py`)
- Idle EC2 analysis → Finding model: creates findings (evidence: `src/aws_cost_waste_detector/ec2_idle.py`)
- Scan orchestrator → Finding history: persists findings (evidence: `src/aws_cost_waste_detector/detector.py`)
- Scan orchestrator → Priority scoring: scores findings (evidence: `src/aws_cost_waste_detector/detector.py`)
- Finding history → Lifecycle rules: determines status (evidence: `src/aws_cost_waste_detector/storage/dynamodb.py`)
- Finding history → Priority scoring: calculates stored priority (evidence: `src/aws_cost_waste_detector/storage/dynamodb.py`)
- Scan orchestrator → Scan reconciliation: reconciles findings (evidence: `src/aws_cost_waste_detector/detector.py`)
- Scan orchestrator → Cost summary: builds summary (evidence: `src/aws_cost_waste_detector/detector.py`)
- Lambda handler → HTML report: renders report (evidence: `src/aws_cost_waste_detector/lambda_handler.py`)
- Lambda handler → Report publisher: publishes report (evidence: `src/aws_cost_waste_detector/lambda_handler.py`)
- Report publisher → Private S3 bucket: stores report (evidence: `README.md`)
- Scan orchestrator → SNS notifier: sends finding alerts (evidence: `src/aws_cost_waste_detector/detector.py`)
- Lambda handler → SNS notifier: sends report summary (evidence: `src/aws_cost_waste_detector/lambda_handler.py`)
- SNS notifier → Amazon SNS: publishes messages (evidence: `src/aws_cost_waste_detector/notifier.py`)
- Amazon SNS → Report recipient: delivers alerts (evidence: `README.md`)
- AWS resources → Unattached EBS scan: provides volume data (evidence: `README.md`)
- AWS resources → Unused EIP scan: provides address data (evidence: `README.md`)
- AWS resources → EC2 discovery: provides instances (evidence: `README.md`)
- Utilization metrics → Amazon CloudWatch: queries metrics (evidence: `README.md`)
- EBS pricing → AWS Pricing API: queries prices (evidence: `src/aws_cost_waste_detector/pricing/ebs.py`)
- Public IPv4 pricing → AWS Pricing API: queries prices (evidence: `src/aws_cost_waste_detector/pricing/eip.py`)
- EC2 pricing → AWS Pricing API: queries prices (evidence: `README.md`)
- Private S3 bucket → Report recipient: serves temporary link (evidence: `README.md`)
