# agussman/aws-cost-explorer architecture

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

- Interactive diagram: https://gitdiagram.com/agussman/aws-cost-explorer
- Repository: https://github.com/agussman/aws-cost-explorer

## Overview

This is a small AWS Lambda billing-report script. Its workflow selects the previous calendar month, queries Cost Explorer for monthly blended costs grouped by the Project tag, formats the results as TSV (placing untagged costs under Other), and emails the attachment through SES. The runtime is concentrated in one file; the README additionally documents scheduled invocation and required AWS permissions. Edges reflect the excerpted calls and README statements.

Main entry points: [`generate_report.py`](https://github.com/agussman/aws-cost-explorer/blob/master/generate_report.py) (Report handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reporting["Billing reporting"]
  node_handler["Report handler<br/>[generate_report.py]"]
  node_period["Month selection<br/>[generate_report.py]"]
  node_format["TSV formatting<br/>[generate_report.py]"]
  node_email["Email composition<br/>[generate_report.py]"]
end

subgraph group_aws["AWS services"]
  node_ce["Cost Explorer"]
  node_ses["Simple Email Service"]
end

node_lambda(("Scheduled Lambda"))
node_finance(("Finance recipient"))

node_lambda -->|"invokes"| node_handler
node_handler -->|"selects month"| node_period
node_handler -->|"queries costs"| node_ce
node_handler -->|"formats results"| node_format
node_handler -->|"sends report"| node_email
node_email -->|"sends raw email"| node_ses
node_ses -.->|"delivers email"| node_finance

click node_handler "https://github.com/agussman/aws-cost-explorer/blob/master/generate_report.py"
click node_period "https://github.com/agussman/aws-cost-explorer/blob/master/generate_report.py"
click node_format "https://github.com/agussman/aws-cost-explorer/blob/master/generate_report.py"
click node_email "https://github.com/agussman/aws-cost-explorer/blob/master/generate_report.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_handler,node_period,node_format,node_email toneBlue
class node_ce,node_ses toneAmber
class node_lambda,node_finance toneIndigo
```

## Components

### Billing reporting

- [Report handler](https://github.com/agussman/aws-cost-explorer/blob/master/generate_report.py): `generate_report.py`
- [Month selection](https://github.com/agussman/aws-cost-explorer/blob/master/generate_report.py): `generate_report.py`
- [TSV formatting](https://github.com/agussman/aws-cost-explorer/blob/master/generate_report.py): `generate_report.py`
- [Email composition](https://github.com/agussman/aws-cost-explorer/blob/master/generate_report.py): `generate_report.py`

### AWS services

- **Cost Explorer**
- **Simple Email Service**

### Other components

- **Scheduled Lambda**
- **Finance recipient**

## Connections

- Scheduled Lambda → Report handler: invokes (evidence: `README.md`)
- Report handler → Month selection: selects month (evidence: `generate_report.py`)
- Report handler → Cost Explorer: queries costs (evidence: `generate_report.py`)
- Report handler → TSV formatting: formats results (evidence: `generate_report.py`)
- Report handler → Email composition: sends report (evidence: `generate_report.py`)
- Email composition → Simple Email Service: sends raw email (evidence: `generate_report.py`)
- Simple Email Service → Finance recipient: delivers email
