# satvika0112/greenshift architecture

> Architecture diagram of the GitHub repository satvika0112/greenshift, 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/satvika0112/greenshift
- Repository: https://github.com/satvika0112/greenshift

## Overview

GreenShift is a multi-tenant platform for turning submitted, deferrable workloads into explainable, carbon- and cost-aware execution windows, then governing execution through human approval and Kubernetes dispatch. Its principal flow continues through runtime status tracking and baseline-versus-actual impact reporting, with lifecycle events recorded in a tamper-evident ledger. The React control plane is the documented enterprise UI; sampled code also shows a Streamlit dashboard. README capabilities establish several subsystem responsibilities, while only selected source excerpts were available, so uncertain internal call wiring is omitted.

Main entry points: [`app/api/routers`](https://github.com/satvika0112/greenshift/tree/main/app/api/routers) (API routers), [`app/shared/database.py`](https://github.com/satvika0112/greenshift/blob/main/app/shared/database.py) (Platform database), [`app/decide/service.py`](https://github.com/satvika0112/greenshift/blob/main/app/decide/service.py) (Decision orchestration), [`app/trust/ledger.py`](https://github.com/satvika0112/greenshift/blob/main/app/trust/ledger.py) (Audit ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product_ui["Control planes"]
  node_react_ui["React control plane<br/>[App.tsx]"]
  node_streamlit_ui["Streamlit dashboard<br/>[main.py]"]
  node_frontend_api["Frontend API client<br/>[client.ts]"]
end

subgraph group_api_governance["API and governance"]
  node_api["FastAPI application<br/>[main.py]"]
  node_api_routes["API routers"]
  node_tenant_auth["Tenant and RBAC<br/>[tenant_scope.py]"]
  node_companies["Company onboarding<br/>[service.py]"]
  node_approval["Human approval gate<br/>[service.py]"]
end

subgraph group_scheduling_data["Scheduling and data"]
  node_ingest["Workload ingestion<br/>[service.py]"]
  node_telemetry["Carbon and tariff data<br/>[data_sources.py]"]
  node_decision["Decision orchestration<br/>[service.py]"]
  node_scheduler["Window scheduling<br/>[scheduler.py]"]
  node_optimization["Policy ranking"]
  node_capacity["Capacity and batching<br/>[batch_scheduler.py]"]
end

subgraph group_execution_impact["Execution and measurement"]
  node_dispatch["Kubernetes dispatch<br/>[service.py]"]
  node_status["Execution status<br/>[status_tracker.py]"]
  node_impact["Impact analytics<br/>[actual_impact.py]"]
  node_trust["Audit ledger<br/>[ledger.py]"]
  node_notifications["User notifications<br/>[service.py]"]
end

subgraph group_shared_state["Shared state"]
  node_database[("Platform database<br/>[database.py]")]
end

node_user(("Organization user"))
node_external_data(("Regional data providers"))
node_kubernetes(("Kubernetes cluster"))

node_user -->|"uses"| node_react_ui
node_react_ui -->|"requests data"| node_frontend_api
node_user -.->|"uses"| node_streamlit_ui
node_streamlit_ui -.->|"requests data"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_api
node_api -->|"dispatches routes"| node_api_routes
node_api_routes -->|"enforces scope"| node_tenant_auth
node_api_routes -->|"onboards tenants"| node_companies
node_api_routes -->|"submits workloads"| node_ingest
node_api_routes -->|"requests scheduling"| node_decision
node_api_routes -->|"records decisions"| node_approval
node_api_routes -->|"serves reports"| node_impact
node_api_routes -->|"serves audit history"| node_trust
node_ingest -->|"persists workloads"| node_database
node_external_data -.->|"provides signals"| node_telemetry
node_telemetry -->|"stores observations"| node_database
node_decision -->|"evaluates workloads"| node_scheduler
node_scheduler -->|"ranks feasible windows"| node_optimization
node_scheduler -->|"checks capacity"| node_capacity
node_decision -->|"persists decisions"| node_database
node_decision -->|"records schedule events"| node_trust
node_approval -->|"updates approval state"| node_database
node_approval -->|"records approval events"| node_trust
node_dispatch -->|"creates Jobs"| node_kubernetes
node_dispatch -->|"records dispatch events"| node_trust
node_status -->|"updates job status"| node_database
node_impact -->|"reads outcomes"| node_database
node_impact -->|"records lifecycle events"| node_trust
node_notifications -->|"sends updates"| node_user
node_database -->|"supplies pending jobs"| node_decision

click node_react_ui "https://github.com/satvika0112/greenshift/blob/main/frontend/src/App.tsx"
click node_streamlit_ui "https://github.com/satvika0112/greenshift/blob/main/app/dashboard/main.py"
click node_frontend_api "https://github.com/satvika0112/greenshift/blob/main/frontend/src/api/client.ts"
click node_api "https://github.com/satvika0112/greenshift/blob/main/app/api/main.py"
click node_api_routes "https://github.com/satvika0112/greenshift/tree/main/app/api/routers"
click node_tenant_auth "https://github.com/satvika0112/greenshift/blob/main/app/api/tenant_scope.py"
click node_companies "https://github.com/satvika0112/greenshift/blob/main/app/companies/service.py"
click node_ingest "https://github.com/satvika0112/greenshift/blob/main/app/ingest/service.py"
click node_telemetry "https://github.com/satvika0112/greenshift/blob/main/app/ingest/data_sources.py"
click node_decision "https://github.com/satvika0112/greenshift/blob/main/app/decide/service.py"
click node_scheduler "https://github.com/satvika0112/greenshift/blob/main/app/decide/scheduler.py"
click node_optimization "https://github.com/satvika0112/greenshift/blob/main/app/decide/optimization_policy.py"
click node_capacity "https://github.com/satvika0112/greenshift/blob/main/app/decide/batch_scheduler.py"
click node_approval "https://github.com/satvika0112/greenshift/blob/main/app/approval/service.py"
click node_dispatch "https://github.com/satvika0112/greenshift/blob/main/app/dispatch/service.py"
click node_status "https://github.com/satvika0112/greenshift/blob/main/app/dispatch/status_tracker.py"
click node_impact "https://github.com/satvika0112/greenshift/blob/main/app/analytics/actual_impact.py"
click node_trust "https://github.com/satvika0112/greenshift/blob/main/app/trust/ledger.py"
click node_notifications "https://github.com/satvika0112/greenshift/blob/main/app/notify/service.py"
click node_database "https://github.com/satvika0112/greenshift/blob/main/app/shared/database.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_react_ui,node_streamlit_ui,node_frontend_api,node_user toneBlue
class node_api,node_api_routes,node_tenant_auth,node_companies,node_approval toneAmber
class node_ingest,node_telemetry,node_decision,node_scheduler,node_optimization,node_capacity toneMint
class node_dispatch,node_status,node_impact,node_trust,node_notifications toneRose
class node_database,node_external_data,node_kubernetes toneIndigo
```

## Components

### Control planes

- [React control plane](https://github.com/satvika0112/greenshift/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Streamlit dashboard](https://github.com/satvika0112/greenshift/blob/main/app/dashboard/main.py): `app/dashboard/main.py`
- [Frontend API client](https://github.com/satvika0112/greenshift/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and governance

- [FastAPI application](https://github.com/satvika0112/greenshift/blob/main/app/api/main.py): `app/api/main.py`
- [API routers](https://github.com/satvika0112/greenshift/tree/main/app/api/routers): `app/api/routers`
- [Tenant and RBAC](https://github.com/satvika0112/greenshift/blob/main/app/api/tenant_scope.py): `app/api/tenant_scope.py`
- [Company onboarding](https://github.com/satvika0112/greenshift/blob/main/app/companies/service.py): `app/companies/service.py`
- [Human approval gate](https://github.com/satvika0112/greenshift/blob/main/app/approval/service.py): `app/approval/service.py`

### Scheduling and data

- [Workload ingestion](https://github.com/satvika0112/greenshift/blob/main/app/ingest/service.py): `app/ingest/service.py`
- [Carbon and tariff data](https://github.com/satvika0112/greenshift/blob/main/app/ingest/data_sources.py): `app/ingest/data_sources.py`
- [Decision orchestration](https://github.com/satvika0112/greenshift/blob/main/app/decide/service.py): `app/decide/service.py`
- [Window scheduling](https://github.com/satvika0112/greenshift/blob/main/app/decide/scheduler.py): `app/decide/scheduler.py`
- [Policy ranking](https://github.com/satvika0112/greenshift/blob/main/app/decide/optimization_policy.py): `app/decide/optimization_policy.py`
- [Capacity and batching](https://github.com/satvika0112/greenshift/blob/main/app/decide/batch_scheduler.py): `app/decide/batch_scheduler.py`

### Execution and measurement

- [Kubernetes dispatch](https://github.com/satvika0112/greenshift/blob/main/app/dispatch/service.py): `app/dispatch/service.py`
- [Execution status](https://github.com/satvika0112/greenshift/blob/main/app/dispatch/status_tracker.py): `app/dispatch/status_tracker.py`
- [Impact analytics](https://github.com/satvika0112/greenshift/blob/main/app/analytics/actual_impact.py): `app/analytics/actual_impact.py`
- [Audit ledger](https://github.com/satvika0112/greenshift/blob/main/app/trust/ledger.py): `app/trust/ledger.py`
- [User notifications](https://github.com/satvika0112/greenshift/blob/main/app/notify/service.py): `app/notify/service.py`

### Shared state

- [Platform database](https://github.com/satvika0112/greenshift/blob/main/app/shared/database.py): `app/shared/database.py`

### Other components

- **Organization user**
- **Regional data providers**
- **Kubernetes cluster**

## Connections

- Organization user → React control plane: uses
- React control plane → Frontend API client: requests data
- Organization user → Streamlit dashboard: uses
- Streamlit dashboard → Frontend API client: requests data
- Frontend API client → FastAPI application: HTTP requests
- FastAPI application → API routers: dispatches routes
- API routers → Tenant and RBAC: enforces scope
- API routers → Company onboarding: onboards tenants
- API routers → Workload ingestion: submits workloads
- API routers → Decision orchestration: requests scheduling
- API routers → Human approval gate: records decisions
- API routers → Impact analytics: serves reports
- API routers → Audit ledger: serves audit history
- Workload ingestion → Platform database: persists workloads
- Regional data providers → Carbon and tariff data: provides signals
- Carbon and tariff data → Platform database: stores observations
- Decision orchestration → Window scheduling: evaluates workloads
- Window scheduling → Policy ranking: ranks feasible windows
- Window scheduling → Capacity and batching: checks capacity
- Decision orchestration → Platform database: persists decisions
- Decision orchestration → Audit ledger: records schedule events
- Human approval gate → Platform database: updates approval state
- Human approval gate → Audit ledger: records approval events
- Kubernetes dispatch → Kubernetes cluster: creates Jobs
- Kubernetes dispatch → Audit ledger: records dispatch events
- Execution status → Platform database: updates job status
- Impact analytics → Platform database: reads outcomes
- Impact analytics → Audit ledger: records lifecycle events
- User notifications → Organization user: sends updates
- Platform database → Decision orchestration: supplies pending jobs