# fuadalfiroj/terraloop architecture

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

- Interactive diagram: https://gitdiagram.com/fuadalfiroj/terraloop
- Repository: https://github.com/fuadalfiroj/terraloop

## Overview

TerraLoop is a browser-based crop-rotation decision-support system for smallholder farms. The principal workflow is to select a farm and record seasonal history, generate a constrained multi-year plan, evaluate budgets and soil health, then explore climate adaptations and compare or export strategies. The README also documents map-based field selection, NASA observation and dataset views, learning from harvest outcomes, and regional exhibition stories. Source excerpts here cover only the local static server, so most component relationships below reflect documented README workflows, not inspected call sites.

Main entry points: [`dist/engine.mjs`](https://github.com/fuadalfiroj/terraloop/blob/main/dist/engine.mjs) (Rotation optimizer), [`dist`](https://github.com/fuadalfiroj/terraloop/tree/main/dist) (Climate replay), [`dist/comparison.mjs`](https://github.com/fuadalfiroj/terraloop/blob/main/dist/comparison.mjs) (Strategy comparison), [`server.mjs`](https://github.com/fuadalfiroj/terraloop/blob/main/server.mjs) (Local web server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_farm_setup["Farm setup"]
  node_local_server["Local web server<br/>[server.mjs]"]
  node_browser_app["Browser application<br/>[app.mjs]"]
  node_field_selection["Field selection<br/>[farm-map.mjs]"]
  node_farm_history["Farm memory"]
end

subgraph group_planning["Rotation planning"]
  node_rotation_optimizer["Rotation optimizer<br/>[engine.mjs]"]
  node_rotation_studio["Rotation planner"]
  node_climate_adaptation["Climate replay"]
end

subgraph group_assessment["Farm assessment"]
  node_water_budget["Water budget"]
  node_nitrogen_balance["Nitrogen balance"]
  node_soil_health["Soil health<br/>[soil-health.mjs]"]
  node_farm_simulation["Farm simulation"]
end

subgraph group_observations["Earth observations"]
  node_earth_observations["NASA observations<br/>[earthdata-hub.mjs]"]
  node_nasa_datasets["NASA dataset directory<br/>[nasa-data.mjs]"]
end

subgraph group_experience["Decision experience"]
  node_strategy_comparison["Strategy comparison<br/>[comparison.mjs]"]
  node_resilience_passport["Resilience passport"]
  node_learning_loop["Harvest learning"]
  node_exhibition_studio["Exhibition studio<br/>[exhibition-ui.mjs]"]
end

node_farmer(("Farmer"))

node_farmer -->|"opens locally"| node_local_server
node_local_server -->|"serves browser app"| node_browser_app
node_farmer -->|"selects farmland"| node_field_selection
node_farmer -->|"records seasons"| node_farm_history
node_farm_history -->|"calibrates plans"| node_rotation_optimizer
node_rotation_studio -->|"generates plans"| node_rotation_optimizer
node_rotation_optimizer -->|"budgets irrigation"| node_water_budget
node_rotation_optimizer -->|"tracks nitrogen"| node_nitrogen_balance
node_rotation_optimizer -->|"models soil"| node_soil_health
node_climate_adaptation -->|"re-optimizes horizon"| node_rotation_optimizer
node_farmer -->|"applies stress"| node_climate_adaptation
node_earth_observations -->|"documents datasets"| node_nasa_datasets
node_farmer -->|"reviews observations"| node_earth_observations
node_farmer -->|"views scenarios"| node_farm_simulation
node_rotation_optimizer -->|"compares strategies"| node_strategy_comparison
node_climate_adaptation -->|"supplies stress scenario"| node_strategy_comparison
node_strategy_comparison -->|"exports comparison"| node_resilience_passport
node_farmer -->|"records outcomes"| node_learning_loop
node_learning_loop -->|"calibrates yields"| node_rotation_optimizer
node_farmer -->|"views farm stories"| node_exhibition_studio

click node_local_server "https://github.com/fuadalfiroj/terraloop/blob/main/server.mjs"
click node_browser_app "https://github.com/fuadalfiroj/terraloop/blob/main/dist/app.mjs"
click node_field_selection "https://github.com/fuadalfiroj/terraloop/blob/main/dist/farm-map.mjs"
click node_farm_history "https://github.com/fuadalfiroj/terraloop/tree/main/dist"
click node_rotation_optimizer "https://github.com/fuadalfiroj/terraloop/blob/main/dist/engine.mjs"
click node_rotation_studio "https://github.com/fuadalfiroj/terraloop/blob/main/dist/rotation-studio.mjs"
click node_climate_adaptation "https://github.com/fuadalfiroj/terraloop/tree/main/dist"
click node_water_budget "https://github.com/fuadalfiroj/terraloop/tree/main/dist"
click node_nitrogen_balance "https://github.com/fuadalfiroj/terraloop/tree/main/dist"
click node_soil_health "https://github.com/fuadalfiroj/terraloop/blob/main/dist/soil-health.mjs"
click node_farm_simulation "https://github.com/fuadalfiroj/terraloop/blob/main/dist/simulation-model.mjs"
click node_earth_observations "https://github.com/fuadalfiroj/terraloop/blob/main/dist/earthdata-hub.mjs"
click node_nasa_datasets "https://github.com/fuadalfiroj/terraloop/blob/main/dist/nasa-data.mjs"
click node_strategy_comparison "https://github.com/fuadalfiroj/terraloop/blob/main/dist/comparison.mjs"
click node_resilience_passport "https://github.com/fuadalfiroj/terraloop/tree/main/dist"
click node_learning_loop "https://github.com/fuadalfiroj/terraloop/tree/main/dist"
click node_exhibition_studio "https://github.com/fuadalfiroj/terraloop/blob/main/dist/exhibition-ui.mjs"

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_server,node_browser_app,node_field_selection,node_farm_history toneBlue
class node_rotation_optimizer,node_rotation_studio,node_climate_adaptation toneAmber
class node_water_budget,node_nitrogen_balance,node_soil_health,node_farm_simulation toneMint
class node_earth_observations,node_nasa_datasets toneRose
class node_strategy_comparison,node_resilience_passport,node_learning_loop,node_exhibition_studio,node_farmer toneIndigo
```

## Components

### Farm setup

- [Local web server](https://github.com/fuadalfiroj/terraloop/blob/main/server.mjs): `server.mjs`
- [Browser application](https://github.com/fuadalfiroj/terraloop/blob/main/dist/app.mjs): `dist/app.mjs`
- [Field selection](https://github.com/fuadalfiroj/terraloop/blob/main/dist/farm-map.mjs): `dist/farm-map.mjs`
- [Farm memory](https://github.com/fuadalfiroj/terraloop/tree/main/dist): `dist`

### Rotation planning

- [Rotation optimizer](https://github.com/fuadalfiroj/terraloop/blob/main/dist/engine.mjs): `dist/engine.mjs`
- [Rotation planner](https://github.com/fuadalfiroj/terraloop/blob/main/dist/rotation-studio.mjs): `dist/rotation-studio.mjs`
- [Climate replay](https://github.com/fuadalfiroj/terraloop/tree/main/dist): `dist`

### Farm assessment

- [Water budget](https://github.com/fuadalfiroj/terraloop/tree/main/dist): `dist`
- [Nitrogen balance](https://github.com/fuadalfiroj/terraloop/tree/main/dist): `dist`
- [Soil health](https://github.com/fuadalfiroj/terraloop/blob/main/dist/soil-health.mjs): `dist/soil-health.mjs`
- [Farm simulation](https://github.com/fuadalfiroj/terraloop/blob/main/dist/simulation-model.mjs): `dist/simulation-model.mjs`

### Earth observations

- [NASA observations](https://github.com/fuadalfiroj/terraloop/blob/main/dist/earthdata-hub.mjs): `dist/earthdata-hub.mjs`
- [NASA dataset directory](https://github.com/fuadalfiroj/terraloop/blob/main/dist/nasa-data.mjs): `dist/nasa-data.mjs`

### Decision experience

- [Strategy comparison](https://github.com/fuadalfiroj/terraloop/blob/main/dist/comparison.mjs): `dist/comparison.mjs`
- [Resilience passport](https://github.com/fuadalfiroj/terraloop/tree/main/dist): `dist`
- [Harvest learning](https://github.com/fuadalfiroj/terraloop/tree/main/dist): `dist`
- [Exhibition studio](https://github.com/fuadalfiroj/terraloop/blob/main/dist/exhibition-ui.mjs): `dist/exhibition-ui.mjs`

### Other components

- **Farmer**

## Connections

- Farmer → Local web server: opens locally (evidence: `README.md`)
- Local web server → Browser application: serves browser app (evidence: `server.mjs`)
- Farmer → Field selection: selects farmland (evidence: `README.md`)
- Farmer → Farm memory: records seasons (evidence: `README.md`)
- Farm memory → Rotation optimizer: calibrates plans (evidence: `README.md`)
- Rotation planner → Rotation optimizer: generates plans (evidence: `README.md`)
- Rotation optimizer → Water budget: budgets irrigation (evidence: `README.md`)
- Rotation optimizer → Nitrogen balance: tracks nitrogen (evidence: `README.md`)
- Rotation optimizer → Soil health: models soil (evidence: `README.md`)
- Climate replay → Rotation optimizer: re-optimizes horizon (evidence: `README.md`)
- Farmer → Climate replay: applies stress (evidence: `README.md`)
- NASA observations → NASA dataset directory: documents datasets (evidence: `README.md`)
- Farmer → NASA observations: reviews observations (evidence: `README.md`)
- Farmer → Farm simulation: views scenarios (evidence: `README.md`)
- Rotation optimizer → Strategy comparison: compares strategies (evidence: `README.md`)
- Climate replay → Strategy comparison: supplies stress scenario (evidence: `README.md`)
- Strategy comparison → Resilience passport: exports comparison (evidence: `README.md`)
- Farmer → Harvest learning: records outcomes (evidence: `README.md`)
- Harvest learning → Rotation optimizer: calibrates yields (evidence: `README.md`)
- Farmer → Exhibition studio: views farm stories (evidence: `README.md`)
