# prahalya05/aws-waste-scanner architecture

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

- Interactive diagram: https://gitdiagram.com/prahalya05/aws-waste-scanner
- Repository: https://github.com/prahalya05/aws-waste-scanner

## Overview

aws-waste-scanner is a scheduled AWS idle-resource auditing job. EventBridge invokes a Lambda that selects registered accounts, scans EC2 inventory across regions, classifies idle resources, estimates their costs, and builds an account-specific report. The report is written to S3 as the authoritative result before optional Gemini narration and Slack notification. A local CLI reuses the scan and report logic without writing to S3 or calling those integrations. The graph reflects README-documented infrastructure and workflow where source excerpts are incomplete; unshown implementation details and calls are omitted.

Main entry points: [`lambda/src/handler.py`](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/handler.py) (Lambda handler), [`lambda/src/scanner.py`](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/scanner.py) (Regional scanner), [`scripts/local_run.py`](https://github.com/prahalya05/aws-waste-scanner/blob/main/scripts/local_run.py) (Local scan CLI), [`lambda/src/ai_summary.py`](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/ai_summary.py) (Optional AI summary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_lambda["Lambda handler<br/>[handler.py]"]
  node_account_registry["Account selection<br/>[handler.py]"]
  node_local_cli["Local scan CLI<br/>[local_run.py]"]
end

subgraph group_analysis["Inventory and analysis"]
  node_scanner["Regional scanner<br/>[scanner.py]"]
  node_waste_rules["Idle resource findings<br/>[scanner.py]"]
  node_pricing["Cost estimation<br/>[pricing.py]"]
end

subgraph group_outputs["Report and delivery"]
  node_report["Report assembly<br/>[report.py]"]
  node_ai_summary["Optional AI summary<br/>[ai_summary.py]"]
  node_slack["Slack notification<br/>[slack.py]"]
end

subgraph group_integrations["AWS and external services"]
  node_scheduler["Daily scheduler"]
  node_ec2_inventory["EC2 inventory API"]
  node_s3[("Report object store")]
  node_gemini["Gemini API"]
  node_slack_service["Slack webhook"]
  node_cross_account["Target account role"]
  node_cloudwatch[("CloudWatch Logs")]
end

node_operator(("Operator"))

node_scheduler -->|"invokes daily"| node_lambda
node_lambda -->|"selects accounts"| node_account_registry
node_lambda -->|"assumes role"| node_cross_account
node_lambda -->|"runs scan"| node_scanner
node_local_cli -->|"runs scan"| node_scanner
node_local_cli -->|"builds report"| node_report
node_scanner -->|"describes resources"| node_ec2_inventory
node_scanner -->|"identifies waste"| node_waste_rules
node_waste_rules -->|"estimates costs"| node_pricing
node_lambda -->|"assembles report"| node_report
node_lambda -->|"writes JSON"| node_s3
node_lambda -->|"requests summary"| node_ai_summary
node_ai_summary -->|"sends prompt"| node_gemini
node_lambda -->|"posts report summary"| node_slack
node_slack -->|"sends notification"| node_slack_service
node_operator -->|"runs locally"| node_local_cli
node_lambda -->|"writes logs"| node_cloudwatch

click node_lambda "https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/handler.py"
click node_account_registry "https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/handler.py"
click node_local_cli "https://github.com/prahalya05/aws-waste-scanner/blob/main/scripts/local_run.py"
click node_scanner "https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/scanner.py"
click node_waste_rules "https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/scanner.py"
click node_pricing "https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/pricing.py"
click node_report "https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/report.py"
click node_ai_summary "https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/ai_summary.py"
click node_slack "https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/slack.py"
click node_cross_account "https://github.com/prahalya05/aws-waste-scanner/tree/main/spoke"

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_account_registry,node_local_cli toneBlue
class node_scanner,node_waste_rules,node_pricing toneAmber
class node_report,node_ai_summary,node_slack toneMint
class node_scheduler,node_ec2_inventory,node_s3,node_gemini,node_slack_service,node_cross_account,node_cloudwatch toneRose
class node_operator toneIndigo
```

## Components

### Run orchestration

- [Lambda handler](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/handler.py): `lambda/src/handler.py`
- [Account selection](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/handler.py): `lambda/src/handler.py`
- [Local scan CLI](https://github.com/prahalya05/aws-waste-scanner/blob/main/scripts/local_run.py): `scripts/local_run.py`

### Inventory and analysis

- [Regional scanner](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/scanner.py): `lambda/src/scanner.py`
- [Idle resource findings](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/scanner.py): `lambda/src/scanner.py`
- [Cost estimation](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/pricing.py): `lambda/src/pricing.py`

### Report and delivery

- [Report assembly](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/report.py): `lambda/src/report.py`
- [Optional AI summary](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/ai_summary.py): `lambda/src/ai_summary.py`
- [Slack notification](https://github.com/prahalya05/aws-waste-scanner/blob/main/lambda/src/slack.py): `lambda/src/slack.py`

### AWS and external services

- **Daily scheduler**
- **EC2 inventory API**
- **Report object store**
- **Gemini API**
- **Slack webhook**
- [Target account role](https://github.com/prahalya05/aws-waste-scanner/tree/main/spoke): `spoke`
- **CloudWatch Logs**

### Other components

- **Operator**

## Connections

- Daily scheduler → Lambda handler: invokes daily (evidence: `README.md`)
- Lambda handler → Account selection: selects accounts (evidence: `lambda/src/handler.py`)
- Lambda handler → Target account role: assumes role (evidence: `README.md`)
- Lambda handler → Regional scanner: runs scan (evidence: `lambda/src/handler.py`)
- Local scan CLI → Regional scanner: runs scan (evidence: `scripts/local_run.py`)
- Local scan CLI → Report assembly: builds report (evidence: `scripts/local_run.py`)
- Regional scanner → EC2 inventory API: describes resources (evidence: `lambda/src/scanner.py`)
- Regional scanner → Idle resource findings: identifies waste (evidence: `lambda/src/scanner.py`)
- Idle resource findings → Cost estimation: estimates costs (evidence: `lambda/src/scanner.py`)
- Lambda handler → Report assembly: assembles report (evidence: `lambda/src/handler.py`)
- Lambda handler → Report object store: writes JSON (evidence: `lambda/src/handler.py`)
- Lambda handler → Optional AI summary: requests summary (evidence: `lambda/src/handler.py`)
- Optional AI summary → Gemini API: sends prompt (evidence: `lambda/src/ai_summary.py`)
- Lambda handler → Slack notification: posts report summary (evidence: `lambda/src/handler.py`)
- Slack notification → Slack webhook: sends notification (evidence: `README.md`)
- Operator → Local scan CLI: runs locally (evidence: `scripts/local_run.py`)
- Lambda handler → CloudWatch Logs: writes logs (evidence: `README.md`)
