Skip to content

About

Modern, copyleft web app for cloning bottled mineral waters from distilled water and food-grade salts

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

562 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Waterforge

Clone bottled mineral waters from distilled (or known-source) water and food-grade salts. Waterforge is a static, client-side web app: pick a target profile, set your source water, toggle the salts you own, and get a precise, batch-scaled recipe. Install it to your home screen and it works offline, at the counter, with no connection.

Try it: waterforge.app

Waterforge — desktop, light theme

What it does

Waterforge takes a named target mineral-water profile, subtracts what is already in your source water, and computes the exact salt additions (in grams, scaled to your batch size) needed to hit it. It also shows you the sulfate:chloride ratio, TDS, and charge-residual readouts, and warns when any salt approaches saturation so you know the recipe will actually dissolve.

The solver uses non-negative least-squares (NNLS) with exact stoichiometry — not rules of thumb — so results are reproducible anywhere you can get distilled water and food-grade salts.

Who it is for: homebrewers and water hobbyists who want to match a specific drinking-water profile precisely. It is not a mash-pH or brewing-salts tool; see CONSTITUTION.md for non-goals.

What you need: distilled (or known-source) water, food-grade salts, and a scale that reads to 0.01 g — the resolution sold as a pocket or jeweller's scale. A 1 g kitchen scale cannot resolve these doses and would read most of a recipe as zero. Larger batches lift small doses into range; see Weighing the salts.

Quickstart

Requirements: Node 26, pinned in .nvmrc — run nvm use in the clone to select it (check with node -v).

git clone https://github.com/cacack/waterforge.git
cd waterforge
npm install
npm run dev          # dev server at http://localhost:5173

Other useful scripts:

Script What it does
npm run build Production build to dist/
npm run preview Serve the dist/ build locally
npm run test Run the Vitest test suite (engine unit tests)
npm run typecheck svelte-check + tsc — full type-check
npm run lint ESLint + Prettier format check
npm run format Auto-format all files with Prettier

Fork and self-host

Waterforge is GPLv3 and needs no backend, so you can run your own copy — and nothing about this project has to keep working for yours to. Clone it, then:

npm ci
npm run build        # static output in dist/

Serve dist/ from anything that serves files: any static host, an object-storage bucket, npx serve dist, a directory on your own machine. The build uses a relative base path, so it works from a subpath (example.com/water/) as readily as from a domain root, with no configuration.

The water profiles are a single file — src/lib/profiles/profiles.json — under CC-BY-SA-4.0, with each profile carrying its own source citation. Take the data on its own if the app is not what you want.

What happens to this project if its maintainer stops is written down in docs/operations/continuity.md.

Documentation

Document What it covers
CONSTITUTION.md Mission, audience, principles, non-goals
USAGE.md How to use the app (intended user flow)
CONTRIBUTING.md Dev setup, conventions, testing, license terms
SECURITY.md Reporting a vulnerability; supported versions
ROADMAP.md Where the project is headed
docs/architecture/overview.md Stack, module boundaries, data flow
docs/decisions/ Architecture Decision Records
docs/guides/chemistry.md Chemistry background and unit conversions
docs/guides/reference-data.md Reference data and profile sources
docs/operations/ci-cd.md CI/CD pipeline and deployment
docs/operations/release.md Release runbook (cut, tag, publish)
docs/operations/continuity.md What must survive; forking if the project stops
docs/operations/traffic-baseline.md What the site actually receives, and how to re-measure

Getting help

Waterforge has a single maintainer, so issues are handled on a best-effort basis with no response-time guarantee (as SECURITY.md states).

  • A question, or unsure what a readout means? Open a question issue.
  • Found a bug or a wrong number? File a bug report — a shared recipe link (the share button in the app) captures the exact inputs.
  • Want a water added to the library? Open a profile request with a source for its mineral analysis.

Where the project is headed is in ROADMAP.md.

License

Waterforge uses a split license:

  • Code — GPL-3.0-or-later.
  • Profile data — CC-BY-SA-4.0. The data is an independently-sourced compilation (each profile cites its own source); CC-BY-SA-4.0 is the project's copyleft choice over it, and derived data must be shared under the same license. The recipe method is credited to Martin Lersch (Khymos).

This keeps the project free and copyleft, faithful to the freely published source method it builds on.

About

Modern, copyleft web app for cloning bottled mineral waters from distilled water and food-grade salts

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages