# vaglar/greenhouse-digital-twin architecture

> Architecture diagram of the GitHub repository vaglar/greenhouse-digital-twin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vaglar/greenhouse-digital-twin
- Repository: https://github.com/vaglar/greenhouse-digital-twin

## Overview

Greenhouse Digital Twin simulates a configured hydroponic tomato crop hour by hour using site weather, coupled greenhouse-climate and crop-growth models, and reports climate, resource-use, and yield results. The main user workflow is to adjust parameters in the web interface, request a run, and inspect daily charts and selected-day views. The README also describes automatic climate controls and hydroponic recipe/yield effects. Some implementation details for those capabilities were not sampled, so their wiring is shown only where the documented workflow or sampled source supports it.

Main entry points: [`api/main.py`](https://github.com/vaglar/greenhouse-digital-twin/blob/main/api/main.py) (FastAPI endpoints), [`twin/simulate.py`](https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/simulate.py) (Hourly orchestrator), [`frontend/src/App.tsx`](https://github.com/vaglar/greenhouse-digital-twin/blob/main/frontend/src/App.tsx) (Twin dashboard), [`frontend/src/api.ts`](https://github.com/vaglar/greenhouse-digital-twin/blob/main/frontend/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_app["Twin dashboard<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_params_ui["Parameter controls<br/>[ParamSlider.tsx]"]
end

subgraph group_service["API service"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_results["Simulation results<br/>[main.py]"]
end

subgraph group_simulation["Simulation core"]
  node_params["Parameter schema<br/>[params.py]"]
  node_simulator["Hourly orchestrator<br/>[simulate.py]"]
  node_climate["Climate model<br/>[climate_model.py]"]
  node_crop["Tomato crop model<br/>[crop_model.py]"]
  node_fertigation["Fertigation totals<br/>[simulate.py]"]
  node_weather["Weather loader<br/>[weather.py]"]
end

subgraph group_inputs["Model inputs"]
  node_config["Greenhouse config"]
  node_weather_data["Weather CSV"]
end

node_grower(("Grower"))

node_grower -->|"sets parameters"| node_app
node_app -->|"edits values"| node_params_ui
node_app -->|"requests config or run"| node_api_client
node_api_client -->|"HTTP requests"| node_api
node_api -->|"reads config"| node_config
node_api -->|"validates parameters"| node_params
node_api -->|"runs simulation"| node_simulator
node_api -->|"previews weather"| node_weather
node_simulator -->|"loads time series"| node_weather
node_weather -->|"reads CSV"| node_weather_data
node_simulator -->|"steps climate"| node_climate
node_simulator -->|"steps crop"| node_crop
node_climate -->|"supplies climate state"| node_crop
node_crop -->|"returns transpiration and CO2 uptake"| node_climate
node_simulator -->|"derives water and nutrient totals"| node_fertigation
node_simulator -->|"returns daily series and yield"| node_results
node_api -->|"formats response"| node_results
node_api_client -->|"returns data"| node_app
node_app -->|"shows charts and day views"| node_grower

click node_app "https://github.com/vaglar/greenhouse-digital-twin/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/vaglar/greenhouse-digital-twin/blob/main/frontend/src/api.ts"
click node_params_ui "https://github.com/vaglar/greenhouse-digital-twin/blob/main/frontend/src/ParamSlider.tsx"
click node_api "https://github.com/vaglar/greenhouse-digital-twin/blob/main/api/main.py"
click node_params "https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/params.py"
click node_simulator "https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/simulate.py"
click node_climate "https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/climate_model.py"
click node_crop "https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/crop_model.py"
click node_fertigation "https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/simulate.py"
click node_weather "https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/weather.py"
click node_config "https://github.com/vaglar/greenhouse-digital-twin/blob/main/config/greenhouse_example.yaml"
click node_weather_data "https://github.com/vaglar/greenhouse-digital-twin/blob/main/config/weather/alexandreia-imathias-typical-year.csv"
click node_results "https://github.com/vaglar/greenhouse-digital-twin/blob/main/api/main.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_app,node_api_client,node_params_ui toneBlue
class node_api,node_results toneAmber
class node_params,node_simulator,node_climate,node_crop,node_fertigation,node_weather toneMint
class node_config,node_weather_data toneRose
class node_grower toneIndigo
```

## Components

### Web interface

- [Twin dashboard](https://github.com/vaglar/greenhouse-digital-twin/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/vaglar/greenhouse-digital-twin/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Parameter controls](https://github.com/vaglar/greenhouse-digital-twin/blob/main/frontend/src/ParamSlider.tsx): `frontend/src/ParamSlider.tsx`

### API service

- [FastAPI endpoints](https://github.com/vaglar/greenhouse-digital-twin/blob/main/api/main.py): `api/main.py`
- [Simulation results](https://github.com/vaglar/greenhouse-digital-twin/blob/main/api/main.py): `api/main.py`

### Simulation core

- [Parameter schema](https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/params.py): `twin/params.py`
- [Hourly orchestrator](https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/simulate.py): `twin/simulate.py`
- [Climate model](https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/climate_model.py): `twin/climate_model.py`
- [Tomato crop model](https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/crop_model.py): `twin/crop_model.py`
- [Fertigation totals](https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/simulate.py): `twin/simulate.py`
- [Weather loader](https://github.com/vaglar/greenhouse-digital-twin/blob/main/twin/weather.py): `twin/weather.py`

### Model inputs

- [Greenhouse config](https://github.com/vaglar/greenhouse-digital-twin/blob/main/config/greenhouse_example.yaml): `config/greenhouse_example.yaml`
- [Weather CSV](https://github.com/vaglar/greenhouse-digital-twin/blob/main/config/weather/alexandreia-imathias-typical-year.csv): `config/weather/alexandreia-imathias-typical-year.csv`

### Other components

- **Grower**

## Connections

- Grower → Twin dashboard: sets parameters
- Twin dashboard → Parameter controls: edits values
- Twin dashboard → API client: requests config or run
- API client → FastAPI endpoints: HTTP requests
- FastAPI endpoints → Greenhouse config: reads config
- FastAPI endpoints → Parameter schema: validates parameters
- FastAPI endpoints → Hourly orchestrator: runs simulation
- FastAPI endpoints → Weather loader: previews weather
- Hourly orchestrator → Weather loader: loads time series
- Weather loader → Weather CSV: reads CSV
- Hourly orchestrator → Climate model: steps climate
- Hourly orchestrator → Tomato crop model: steps crop
- Climate model → Tomato crop model: supplies climate state
- Tomato crop model → Climate model: returns transpiration and CO2 uptake
- Hourly orchestrator → Fertigation totals: derives water and nutrient totals
- Hourly orchestrator → Simulation results: returns daily series and yield
- FastAPI endpoints → Simulation results: formats response
- API client → Twin dashboard: returns data
- Twin dashboard → Grower: shows charts and day views