# muhil-amuthan/carbonwise architecture

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

- Interactive diagram: https://gitdiagram.com/muhil-amuthan/carbonwise
- Repository: https://github.com/muhil-amuthan/carbonwise

## Overview

CarbonWise is a Streamlit advisor that estimates grid carbon intensity and helps users choose lower-emission appliance run times. Its documented workflow accepts generation-mix or CSV data, estimates intensity, presents visualizations and recommendations, and supports summary reporting. The main application is a large monolith; the sampled excerpts show its external API calls, while README workflow statements support the broader product stages. The excerpts do not establish that app.py calls the separate src modules, so those links are omitted.

Main entry points: [`app.py`](https://github.com/muhil-amuthan/carbonwise/blob/main/app.py) (Streamlit interface), [`src/ci.py`](https://github.com/muhil-amuthan/carbonwise/blob/main/src/ci.py) (Intensity estimate), [`src/recommend.py`](https://github.com/muhil-amuthan/carbonwise/blob/main/src/recommend.py) (Window ranking), [`src/io_utils.py`](https://github.com/muhil-amuthan/carbonwise/blob/main/src/io_utils.py) (Run log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Web application"]
  node_ui["Streamlit interface<br/>[app.py]"]
end

subgraph group_domain["Carbon analysis"]
  node_mix_input["Mix and CSV input<br/>[app.py]"]
  node_intensity["Intensity estimate<br/>[ci.py]"]
  node_window_rank["Window ranking<br/>[recommend.py]"]
  node_recommendations["Recommendations<br/>[app.py]"]
  node_visualizations["Grid visualizations<br/>[app.py]"]
end

subgraph group_records["Run records"]
  node_run_logs[("Run log<br/>[io_utils.py]")]
end

subgraph group_reporting["Reporting"]
  node_summary["Summary report"]
end

node_user(("User"))
node_grid_api["Electricity Maps API"]
node_ip_api["IP location API"]

node_user -->|"uses"| node_ui
node_ui -.->|"requests intensity"| node_grid_api
node_ui -->|"looks up location"| node_ip_api
node_ui -->|"accepts data"| node_mix_input
node_mix_input -->|"feeds calculation"| node_intensity
node_intensity -->|"displays estimate"| node_visualizations
node_intensity -.->|"ranks lower-carbon windows"| node_window_rank
node_window_rank -->|"returns ranked windows"| node_recommendations
node_ui -->|"renders results"| node_visualizations
node_ui -.->|"records runs"| node_run_logs
node_run_logs -.->|"supplies run data"| node_summary

click node_ui "https://github.com/muhil-amuthan/carbonwise/blob/main/app.py"
click node_mix_input "https://github.com/muhil-amuthan/carbonwise/blob/main/app.py"
click node_intensity "https://github.com/muhil-amuthan/carbonwise/blob/main/src/ci.py"
click node_window_rank "https://github.com/muhil-amuthan/carbonwise/blob/main/src/recommend.py"
click node_recommendations "https://github.com/muhil-amuthan/carbonwise/blob/main/app.py"
click node_visualizations "https://github.com/muhil-amuthan/carbonwise/blob/main/app.py"
click node_run_logs "https://github.com/muhil-amuthan/carbonwise/blob/main/src/io_utils.py"
click node_summary "https://github.com/muhil-amuthan/carbonwise/blob/main/generate_summary.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_ui,node_user toneBlue
class node_mix_input,node_intensity,node_window_rank,node_recommendations,node_visualizations toneAmber
class node_run_logs,node_grid_api,node_ip_api toneMint
class node_summary toneRose
```

## Components

### Web application

- [Streamlit interface](https://github.com/muhil-amuthan/carbonwise/blob/main/app.py): `app.py`

### Carbon analysis

- [Mix and CSV input](https://github.com/muhil-amuthan/carbonwise/blob/main/app.py): `app.py`
- [Intensity estimate](https://github.com/muhil-amuthan/carbonwise/blob/main/src/ci.py): `src/ci.py`
- [Window ranking](https://github.com/muhil-amuthan/carbonwise/blob/main/src/recommend.py): `src/recommend.py`
- [Recommendations](https://github.com/muhil-amuthan/carbonwise/blob/main/app.py): `app.py`
- [Grid visualizations](https://github.com/muhil-amuthan/carbonwise/blob/main/app.py): `app.py`

### Run records

- [Run log](https://github.com/muhil-amuthan/carbonwise/blob/main/src/io_utils.py): `src/io_utils.py`

### Reporting

- [Summary report](https://github.com/muhil-amuthan/carbonwise/blob/main/generate_summary.py): `generate_summary.py`

### Other components

- **User**
- **Electricity Maps API**
- **IP location API**

## Connections

- User → Streamlit interface: uses (evidence: `README.md`)
- Streamlit interface → Electricity Maps API: requests intensity (evidence: `app.py`)
- Streamlit interface → IP location API: looks up location (evidence: `app.py`)
- Streamlit interface → Mix and CSV input: accepts data (evidence: `README.md`)
- Mix and CSV input → Intensity estimate: feeds calculation (evidence: `README.md`)
- Intensity estimate → Grid visualizations: displays estimate (evidence: `README.md`)
- Intensity estimate → Window ranking: ranks lower-carbon windows
- Window ranking → Recommendations: returns ranked windows (evidence: `README.md`)
- Streamlit interface → Grid visualizations: renders results (evidence: `README.md`)
- Streamlit interface → Run log: records runs
- Run log → Summary report: supplies run data
