# mr-saab-29/causal-energy-intelligence architecture

> Architecture diagram of the GitHub repository mr-saab-29/causal-energy-intelligence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mr-saab-29/causal-energy-intelligence
- Repository: https://github.com/mr-saab-29/causal-energy-intelligence

## Overview

The repository is a carbon-aware energy forecasting and workload-scheduling platform. Its principal workflow refreshes energy and weather data, derives modeling features, forecasts energy signals, estimates carbon intensity, ranks cleaner scheduling hours, and exposes dashboard recommendations. It also documents future recommendations, causal analysis, and operational monitoring. The README supplies the broad pipeline; sampled source confirms ingestion, dashboard orchestration, and monitoring details, so uncertain internal calls are not inferred.

Main entry points: [`src/models`](https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/models) (Forecast models), [`src/features`](https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/features) (Feature engineering), [`orchestration/definitions.py`](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/orchestration/definitions.py) (Refresh orchestration), [`src/optimization/workload_shift.py`](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/optimization/workload_shift.py) (Clean-hour ranking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data foundation"]
  node_local_ingest["Local ingestion<br/>[local_ingest.py]"]
  node_supabase_ingest["Supabase ingestion<br/>[supabase_ingest.py]"]
  node_storage[("Transformed data store")]
  node_features["Feature engineering"]
end

subgraph group_forecast["Forecasting"]
  node_forecast["Forecast models"]
end

subgraph group_decisions["Scheduling decisions"]
  node_carbon["Carbon estimates"]
  node_ranking["Clean-hour ranking<br/>[workload_shift.py]"]
  node_causal["Causal analysis"]
  node_causal_recs["Causal recommendations<br/>[recommendations.py]"]
  node_future_recs["Future recommendations"]
end

subgraph group_product["Product delivery"]
  node_dashboard_data["Dashboard data contract"]
  node_frontend["Decision dashboard<br/>[main.jsx]"]
  node_api["Platform API<br/>[main.py]"]
end

subgraph group_ops["Operations"]
  node_orchestration["Refresh orchestration<br/>[definitions.py]"]
  node_health["Pipeline health<br/>[pipeline_health.py]"]
  node_monitor["Forecast monitoring"]
  node_tracking["MLflow tracking<br/>[mlflow_tracking.py]"]
end

node_sources(("Energy and weather sources"))
node_user(("Dashboard user"))

node_sources -->|"fetches"| node_local_ingest
node_sources -.->|"fetches"| node_supabase_ingest
node_local_ingest -->|"rebuilds"| node_features
node_supabase_ingest -.->|"loads"| node_storage
node_supabase_ingest -.->|"exports"| node_features
node_storage -->|"feeds"| node_features
node_features -->|"trains and predicts"| node_forecast
node_forecast -->|"supplies forecasts"| node_carbon
node_carbon -->|"informs ranking"| node_ranking
node_ranking -->|"provides rankings"| node_causal_recs
node_causal -->|"supports analysis"| node_causal_recs
node_forecast -->|"supports recommendations"| node_future_recs
node_ranking -->|"supplies results"| node_dashboard_data
node_future_recs -->|"supplies results"| node_dashboard_data
node_dashboard_data -->|"serves data"| node_frontend
node_user -->|"views"| node_frontend
node_orchestration -->|"dispatches refresh"| node_local_ingest
node_orchestration -->|"runs checks"| node_health
node_orchestration -->|"dispatches generation"| node_future_recs
node_orchestration -->|"dispatches build"| node_dashboard_data
node_features -->|"validated by"| node_health
node_forecast -->|"quality monitored"| node_monitor
node_ranking -->|"drift monitored"| node_monitor
node_forecast -.->|"tracked by"| node_tracking

click node_local_ingest "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/data/local_ingest.py"
click node_supabase_ingest "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/data/supabase_ingest.py"
click node_storage "https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/data/pipelines"
click node_features "https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/features"
click node_forecast "https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/models"
click node_carbon "https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/carbon"
click node_ranking "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/optimization/workload_shift.py"
click node_causal "https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/causal"
click node_causal_recs "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/causal/recommendations.py"
click node_future_recs "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/models/future_recommendations.py"
click node_dashboard_data "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/scripts/build_dashboard_data.py"
click node_frontend "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/frontend/src/main.jsx"
click node_api "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/api/main.py"
click node_orchestration "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/orchestration/definitions.py"
click node_health "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/data/pipeline_health.py"
click node_monitor "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/monitoring/forecast_monitor.py"
click node_tracking "https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/tracking/mlflow_tracking.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_local_ingest,node_supabase_ingest,node_storage,node_features,node_user toneBlue
class node_forecast toneAmber
class node_carbon,node_ranking,node_causal,node_causal_recs,node_future_recs toneMint
class node_dashboard_data,node_frontend,node_api toneRose
class node_orchestration,node_health,node_monitor,node_tracking,node_sources toneIndigo
```

## Components

### Data foundation

- [Local ingestion](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/data/local_ingest.py): `src/data/local_ingest.py`
- [Supabase ingestion](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/data/supabase_ingest.py): `src/data/supabase_ingest.py`
- [Transformed data store](https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/data/pipelines): `src/data/pipelines`
- [Feature engineering](https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/features): `src/features`

### Forecasting

- [Forecast models](https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/models): `src/models`

### Scheduling decisions

- [Carbon estimates](https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/carbon): `src/carbon`
- [Clean-hour ranking](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/optimization/workload_shift.py): `src/optimization/workload_shift.py`
- [Causal analysis](https://github.com/mr-saab-29/causal-energy-intelligence/tree/main/src/causal): `src/causal`
- [Causal recommendations](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/causal/recommendations.py): `src/causal/recommendations.py`
- [Future recommendations](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/models/future_recommendations.py): `src/models/future_recommendations.py`

### Product delivery

- [Dashboard data contract](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/scripts/build_dashboard_data.py): `scripts/build_dashboard_data.py`
- [Decision dashboard](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Platform API](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/api/main.py): `api/main.py`

### Operations

- [Refresh orchestration](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/orchestration/definitions.py): `orchestration/definitions.py`
- [Pipeline health](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/data/pipeline_health.py): `src/data/pipeline_health.py`
- [Forecast monitoring](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/monitoring/forecast_monitor.py): `src/monitoring/forecast_monitor.py`
- [MLflow tracking](https://github.com/mr-saab-29/causal-energy-intelligence/blob/main/src/tracking/mlflow_tracking.py): `src/tracking/mlflow_tracking.py`

### Other components

- **Energy and weather sources**
- **Dashboard user**

## Connections

- Energy and weather sources → Local ingestion: fetches
- Energy and weather sources → Supabase ingestion: fetches
- Local ingestion → Feature engineering: rebuilds
- Supabase ingestion → Transformed data store: loads
- Supabase ingestion → Feature engineering: exports
- Transformed data store → Feature engineering: feeds
- Feature engineering → Forecast models: trains and predicts
- Forecast models → Carbon estimates: supplies forecasts
- Carbon estimates → Clean-hour ranking: informs ranking
- Clean-hour ranking → Causal recommendations: provides rankings
- Causal analysis → Causal recommendations: supports analysis
- Forecast models → Future recommendations: supports recommendations
- Clean-hour ranking → Dashboard data contract: supplies results
- Future recommendations → Dashboard data contract: supplies results
- Dashboard data contract → Decision dashboard: serves data
- Dashboard user → Decision dashboard: views
- Refresh orchestration → Local ingestion: dispatches refresh
- Refresh orchestration → Pipeline health: runs checks
- Refresh orchestration → Future recommendations: dispatches generation
- Refresh orchestration → Dashboard data contract: dispatches build
- Feature engineering → Pipeline health: validated by
- Forecast models → Forecast monitoring: quality monitored
- Clean-hour ranking → Forecast monitoring: drift monitored
- Forecast models → MLflow tracking: tracked by