CisternLab

Inspiration

Rainwater harvesting sounds simple: collect the rain, store it, and use it when needed. But choosing the right storage capacity is much less straightforward.

A location may receive substantial rainfall over a year, yet much of it can arrive in a few intense events. A small tank may overflow during those events and run empty during the following dry days. Annual rainfall totals alone cannot tell homeowners, schools, or small facilities how much water they could actually use.

That observation led to CisternLab, a transparent decision-support tool designed to make rainwater harvesting easier to evaluate before investing in physical infrastructure.

The goal is to turn environmental data into practical decisions, not just display another sustainability dashboard.

What it does

CisternLab transforms historical rainfall data into understandable tank-sizing decisions and estimates of potential freshwater displacement.

Users can:

Simulate daily rainwater harvesting: Adjust roof area, collection efficiency, tank capacity, and non-potable water demand. See how rainfall becomes collected water, overflow, stored water, and supplied demand.
Explore historical rainfall: Search for a city and load complete historical ERA5 rainfall data through Open-Meteo.
Compare storage capacities: Evaluate different tank sizes using the same rainfall and demand assumptions. A transparent, adjustable rule identifies the smallest tested capacity meeting a selected percentage of the maximum modeled supply.
Investigate yearly variability: Compare independent simulations for 2023, 2024, and 2025, including water delivery, unmet demand, and shortage periods.
Understand environmental impact: Compare a no-harvesting baseline with different tank capacities and calculate potential freshwater displacement.
Inspect and share evidence: Export CSV/JSON data, inspect source records, follow a guided explanation, and generate a printable environmental impact brief.

The application also includes a preserved historical example from Edirne, Türkiye, containing 1,096 daily rainfall records. This example can be explored without a new weather API request.

No account, paid subscription, or API key is required.

Environmental impact: a reproducible example

To demonstrate the practical value of tank sizing, we analyzed three years of historical ERA5 rainfall for Edirne, Türkiye.

The illustrative scenario uses:

Roof catchment area: 120 m²
Rainwater collection efficiency: 80%
Daily non-potable water demand: 250 liters
Current tank capacity: 2,000 liters
Alternative tank capacity: 3,000 liters
Independent empty-tank starts for each year

Using the same historical rainfall and demand assumptions, CisternLab calculates:

Metric	Modeled result
Delivery with a 2,000 L tank	114,591.6 L
Delivery with a 3,000 L tank	120,687.2 L
Additional modeled delivery	6,095.6 L

These values represent the sum of three independent annual simulations covering 2023–2025, not savings from a single year.

For this scenario, CisternLab's three-year comparison rule recommends a 3,000-liter tested capacity at the default 90% relative-yield target.

The result illustrates an actionable decision: a different storage capacity can make more of the same rainfall available for useful purposes.

Environmental interpretation: Potential freshwater displacement occurs only if harvested rainwater replaces freshwater that would otherwise have been consumed. These are modeled estimates, not measured water savings at an actual property.

How we built it

CisternLab is a browser-based application developed with React, TypeScript, Vite, Tailwind CSS, Recharts, and Lucide.

At its core is a deterministic daily water-balance engine. For each day, the model calculates rainwater collected from the roof, tank overflow, water delivered to non-potable demand, unmet demand, and remaining storage.

The calculation follows a documented rain-before-demand assumption and checks water-volume conservation.

Historical weather data comes from Open-Meteo, using ERA5 reanalysis and daily rain_sum values. An independent validation layer checks dates, units, missing values, source metadata, and complete calendar coverage before accepting a dataset.

We built separate calculation modules for capacity comparison, historical variability, and environmental impact. This keeps the original water-balance calculations consistent across the application.

The preserved Edirne dataset includes source information and a SHA-256 integrity check, making the example reproducible.

CisternLab is hosted on GitHub Pages, with automated verification through GitHub Actions. The completed application passes 242 unit tests and 68 browser tests, including responsive layout and automated accessibility checks.

OpenAI Codex assisted the development workflow. The application's environmental calculations are deterministic; they do not depend on a generative AI model.

Challenges we ran into

1. Turning rainfall into meaningful water-supply estimates

Collecting rainfall data was only the beginning. Annual rainfall totals do not capture when tanks overflow or when demand goes unmet. We needed to model daily storage behavior and preserve a clear accounting of every liter.

2. Keeping historical data trustworthy

We had to distinguish modeled ERA5 reanalysis from direct weather-station measurements, handle complete calendar years and leap days, reject incomplete datasets, and preserve source provenance.

3. Making tank recommendations explainable

Rather than presenting an unexplained "optimal" tank size, we developed a transparent rule based on tested capacities and an adjustable relative-yield target. Every recommendation includes its assumptions and limitations.

4. Handling real-world network limitations

Public weather services can time out or become temporarily unavailable. We implemented validated caching, clear error handling, and an archived historical example that remains usable without a new API request.

5. Communicating environmental impact responsibly

A modeled liter of harvested rainwater is not automatically a verified liter of freshwater saved. We made this distinction explicit throughout the dashboard, exports, and evidence reports.

Accomplishments that we're proud of

The most important achievement is transforming rainfall data into an understandable, reproducible decision.

CisternLab goes beyond estimating how much rain could fall on a roof. It helps users examine how much rainwater different tanks could actually deliver under stated conditions.

We are particularly proud of the complete evidence trail: original rainfall data, source attribution, transparent calculations, comparable scenarios, accessible result tables, and downloadable reports.

The public application is functional, responsive, and available without registration or paid services.

What we learned

Building CisternLab reinforced an important lesson: environmental impact depends on how a resource is used, not simply how much of it is available.

We also learned how important it is to preserve the difference between historical data, simulations, and verified real-world outcomes.

Transparent assumptions, reproducible calculations, and understandable limitations make a sustainability tool more useful than a visually impressive result without supporting evidence.

What's next

CisternLab is a working prototype, but several improvements would make it more useful for real installations:

Validate estimates against actual tank-level and water-consumption measurements.
Explore longer historical datasets and more variable water-demand patterns.
Add physical-system factors such as first-flush losses, evaporation, leakage, and treatment requirements.
Develop more detailed engineering and economic assessments using appropriately verified inputs.

The long-term vision is to help people make better-informed water conservation decisions, grounded in transparent data rather than guesswork.

Tools, data, and limitations

Technology: React, TypeScript, Vite, Tailwind CSS, Recharts, Lucide, Vitest, Playwright, GitHub Actions, and GitHub Pages. OpenAI Codex provided development assistance.

Data: Open-Meteo, ERA5 / Copernicus Climate Change Service, and GeoNames, with the applicable source attribution and licensing preserved.

Limitations: ERA5 is modeled reanalysis, not rainfall measured at an individual rooftop. Three years do not establish a long-term climate normal. Tank recommendations apply only to tested capacities and selected assumptions. CisternLab does not certify engineering designs, drinking-water safety, or actual environmental savings.

Live application: https://hizmali.github.io/CisternLab/

Source code and methodology: https://github.com/HIZMALI/CisternLab