# nachiket-kumar/aws-cost-optimization architecture

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

- Interactive diagram: https://gitdiagram.com/nachiket-kumar/aws-cost-optimization
- Repository: https://github.com/nachiket-kumar/aws-cost-optimization

## Overview

##### Project type and purpose
- This is a cloud-native **DevSecOps + FinOps** tool built on AWS.
- Its primary purpose is to automatically monitor and analyze AWS costs, emit metrics and alerts, provide recommendations, and surface cost-dashboards in Grafana/Power BI.

##### File structure
- **src/cost_reporter/** contains Python modules that implement the core logic:
- `main.py` — AWS Lambda handler
- `metrics_calculator.py` — processes cost data into CloudWatch metrics
- `cloudwatch_alerter.py` — creates CloudWatch alarms for cost spikes
- `slack_notifier.py` — pushes alerts to Slack
- `benchmark_comparator.py`, `recommendations.py` — compare against benchmarks and generate FinOps recommendations
- **src/scripts/** holds bootstrap scripts for local/demo setups.
- **terraform/** defines all AWS infrastructure (Lambda, IAM roles, Inspector, GuardDuty, CloudWatch, EventBridge, S3 backend for Terraform state, etc.).
- **dashboards/** holds exported Grafana JSON and Power BI `.pbix`.
- **.github/workflows/deploy.yml** orchestrates CI/CD (runs tests, lints, applies Terraform, deploys Lambda).

##### Readme insights
- Key technologies: AWS Lambda (runtime), Terraform (IaC), CloudWatch, Slack, Grafana & Power BI, GitHub Actions, AWS Inspector + GuardDuty + Trivy for security.

##### Main components & relationships
a. Components
1. GitHub Actions CI/CD pipeline
2. Terraform (IaC)
3. AWS Lambda function
4. AWS EventBridge (cron trigger)
5. AWS CloudWatch (metrics + alarms)
6. Slack (alerts via webhook)
7. Grafana & Power BI dashboards (read-only visualization)
8. AWS security services: Inspector & GuardDuty (provisioned by Terraform)
9. S3 (remote state backend)
b. Interactions
- CI/CD triggers on git push → Terraform apply → deploy Lambda & supporting resources.
- EventBridge schedules Lambda runs (e.g., daily).
- Lambda retrieves cost CSV/JSON (from AWS Cost Explorer API or embedded data), calculates metrics, publishes to CloudWatch .
- Based on threshold logic, Lambda also creates/alters CloudWatch alarms.
- On alarm breach, another Lambda or same function triggers `slack_notifier` to send real-time Slack messages.
- Benchmarks & recommendations modules run inside Lambda and write to S3 or push into dashboards.
- Grafana connects to CloudWatch as a data source; Power BI imports cost reports from S3 or direct CSV.
- Terraform provisions AWS Inspector and GuardDuty for DevSecOps scanning.
c. Architectural patterns
- Serverless micro-service: single-purpose AWS Lambda.
- Event-driven: EventBridge → Lambda → CloudWatch → Slack.
- Infrastructure as Code with reusable Terraform modules.
- Modular code structure separating concerns: metrics, alerts, notifications, recommendations.
d. Key technologies
- AWS Lambda, EventBridge, CloudWatch, S3, IAM
- Terraform (main.tf, variables.tf, outputs.tf, backend.tf, security.tf)
- Python 3.x modules
- Slack Webhook API
- Grafana (JSON) and Power BI (.pbix)

##### Detail & fidelity
- **every** Terraform-provisioned AWS service.
- Security scanning steps in the CI/CD flow (Trivy scan, Inspector findings).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External boundary
    subgraph "External" 
        direction TB
        GH["GitHub Actions CI/CD Pipeline"]:::ciic
        SL["Slack Webhook"]:::external
        GRAF["Grafana Dashboard"]:::external
        PBI["Power BI Report"]:::external
    end

    %% AWS Account boundary
    subgraph "AWS Account" 
        direction TB
        TF["Terraform (IaC)"]:::infra
        subgraph "Serverless Compute"
            direction TB
            LAMBDA["Lambda Function"]:::compute
            subgraph "Lambda Code Modules"
                direction TB
                MAIN["main.py"]:::compute
                METRICS["metrics_calculator.py"]:::compute
                ALERTER["cloudwatch_alerter.py"]:::compute
                SLACKMOD["slack_notifier.py"]:::compute
                BENCH["benchmark_comparator.py"]:::compute
                RECO["recommendations.py"]:::compute
            end
        end
        EB["EventBridge Cron Trigger"]:::aws
        CW_MET["CloudWatch Metrics"]:::aws
        CW_AL["CloudWatch Alarm"]:::aws
        S3["S3 (TF State)"]:::aws
        INSPEC["AWS Inspector"]:::aws
        GD["AWS GuardDuty"]:::aws
    end

    %% CI/CD to IaC
    GH -->|"on push"| TF
    click GH "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/.github/workflows/deploy.yml"
    click TF "https://github.com/nachiket-kumar/aws-cost-optimization/tree/main/terraform/"
    click TF "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/terraform/main.tf"
    click TF "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/terraform/variables.tf"
    click TF "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/terraform/outputs.tf"
    click TF "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/terraform/backend.tf"
    click TF "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/terraform/security.tf"

    %% Terraform provisions AWS resources
    TF --> EB
    TF --> LAMBDA
    TF --> CW_MET
    TF --> CW_AL
    TF --> S3
    TF --> INSPEC
    TF --> GD

    %% Event-driven invocation
    EB -->|"daily cron"| LAMBDA
    click EB "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/terraform/main.tf"

    %% Lambda internal flow
    LAMBDA --> MAIN
    MAIN --> METRICS
    MAIN --> ALERTER
    MAIN --> SLACKMOD
    MAIN --> BENCH
    MAIN --> RECO

    click MAIN "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/src/cost_reporter/main.py"
    click METRICS "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/src/cost_reporter/metrics_calculator.py"
    click ALERTER "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/src/cost_reporter/cloudwatch_alerter.py"
    click SLACKMOD "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/src/cost_reporter/slack_notifier.py"
    click BENCH "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/src/cost_reporter/benchmark_comparator.py"
    click RECO "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/src/cost_reporter/recommendations.py"

    %% Data flow from Lambda to Monitoring & Storage
    METRICS --> CW_MET
    ALERTER --> CW_AL
    CW_AL -->|"alarm breach"| SLACKMOD
    SLACKMOD --> SL

    %% Visualization
    CW_MET --> GRAF
    S3 --> PBI
    click S3 "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/terraform/backend.tf"

    %% Security services
    INSPEC -.-> TF
    GD -.-> TF
    click INSPEC "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/terraform/security.tf"
    click GD "https://github.com/nachiket-kumar/aws-cost-optimization/blob/main/terraform/security.tf"

    %% Styles
    classDef aws fill:#f90,stroke:#333,stroke-width:1px
    classDef compute fill:#ffeb3b,stroke:#333,stroke-width:1px
    classDef external fill:#03a9f4,stroke:#333,stroke-width:1px
    classDef ciic fill:#4caf50,stroke:#333,stroke-width:1px
    classDef infra fill:#8bc34a,stroke:#333,stroke-width:1px
```
