hermes
76a4d0805c
A second, deeper review of PR #12 found five things the first review did not. All are fixed here. The band was not the band ------------------------- The fermentation curve's shaded range was drawn as ONE dataset with `fill: "+1"`, which fills to the NEXT dataset - and the next dataset was the median line, not the maximum. So the band shaded min-to-median, the upper half of the range was drawn as a hairline but never shaded, and the tooltip said "range min to max" while the picture showed something else. The band is now two datasets - the min curve filled down to a max curve - with the max hidden from the legend. Rising gravity -------------- `attenuation_percent` rejected a final gravity below 1.000 and one implying more than 100% attenuation, but a run whose gravity went UP produced a NEGATIVE attenuation - which was then averaged into the headline figure and plotted as a negative bar. Verified against the live code: OG 1010 -> FG 1020 gave -100.0%. Now rejected, and reported by `implausible_runs` with the reason "the gravity went up, which is usually a mis-ordered pair of readings". Undated readings ---------------- An undated reading sorted to the front of the run, so it became the original gravity - which put the OG after the FG and produced a negative attenuation. The OG now comes from the earliest *dated* reading, and `days_to_target` skips the readings it cannot place on the timeline rather than giving up on the whole run. Verified: readings 1050 (dated), 1005 (undated), 1010 (dated) gave None instead of 24 days, and an OG of 1005 instead of 1050. Active runs on the curve ------------------------ The curve chart filtered on `curve.length > 1` only, so it plotted the active runs as well - a partial fermentation on a chart meant to describe how a completed one behaves. It now excludes them, along with the suspect runs. Four fetches, one payload ------------------------- `/api/runs` carries every reading of every run, and four charts each fetched it independently - so the analysis page made two identical round-trips of the whole collection. There is now one shared fetch. Also ---- - The "Readings that need a second look" table links to the run, so a suspect reading can be corrected in one click. - `days_to_1015` and the `curves` variable were computed and never used. Removed. - A reading below 1.000 now says what it is - "beer cannot be less dense than water, so this is almost certainly a typo (a 1.012 reading entered as 012?)". The reading is still SAVED: rejecting it would lose the brewer's actual observation, and seeing it recorded is how they spot the mistake. 142 tests (up from 134).
Brew Log
Stores specific-gravity data for home-brewed beer runs in Mongo and turns it into useful figures — alcohol by volume, days in the fermenter, gravity trends.
Flask app, Mongo backend, no build step for the front end.
Running it locally
python -m venv .venv
. .venv/bin/activate
pip install -r requirements-dev.txt
export MONGO_HOST=192.168.178.229
export MONGO_USER=root
export MONGO_PASS=...
export SECRET_KEY=anything-for-local-use
cd src/flask
python -m beer_data # dev server on :5000
# or, production-style:
python -m waitress --listen=0.0.0.0:5000 --call beer_data:create_app
Then open http://localhost:5000/ and sign in.
Tests
. .venv/bin/activate
python -m pytest tests/ -q
The tests use mongomock, so they need no database and no network.
The pages
| Page | What it is for |
|---|---|
/login |
Sign in |
/brews |
The brew process: record a reading, review every run |
/active |
What is in the fermenter right now — tap, gravity, projected strength |
/history |
How every brew has gone, with charts and the standard-vs-legacy ABV comparison |
/analysis |
How consistently the brews ferment — attenuation, fermentation curves, brew timings |
/active — the active beers page
A card per brew that is still in the fermenter (a run with no reading marked final), showing:
- the tap number it is on,
- the current gravity, as a decimal reading with the point scale beneath,
- the projected alcohol, worked out from the run's original gravity,
- how many days it has been brewing,
- a sparkline of the gravity so far,
- the latest comment on a reading.
A run with only one reading and no recorded original gravity has no reliable estimate, so the alcohol figure shows a dash rather than a misleading number. Record the OG on the run (or take a second reading) and it appears.
/analysis — how the brews ferment
The page that turns the history into something you can brew better from:
- Attenuation by brew — what fraction of the original gravity was fermented away, for every finished brew.
- Fermentation curves — the typical shape of a fermentation, drawn as a median curve with the min–max envelope behind it. Plotting every brew individually gives sixteen near-identical lines and an unreadable legend.
- Every finished brew — OG, FG, ABV, attenuation, days in the fermenter, days to reach 1.010, and the finish date.
- Readings that need a second look — readings outside the plausible hydrometer range.
- Headline figures: average attenuation and its spread, average brew time, average time to 1.010.
A reading that is physically impossible — a final gravity below the original gravity by more than the wort itself could have — is excluded from the averages rather than silently distorting them, and the run is listed on the page so it can be corrected.
Run metadata
Some details cannot be derived from the readings, so they are stored per run in
the beer_runs collection and edited on the run detail page:
- the canonical name the brew is known by (overriding the drifting per-reading name),
- the tap number,
- the original gravity,
- free-text brew notes.
Populating the run metadata from the existing readings
# dry run - prints what it would do, writes nothing
python scripts/backfill_run_metadata.py
# write it
python scripts/backfill_run_metadata.py --apply
The script is idempotent and non-destructive: it only inserts into
beer_runs, never touches beer_data, and never overwrites a name you have
already set by hand (pass --force if you want it to).
Layout
src/flask/
beer_data.py entry point; exposes `app` and `create_app`
app_factory.py application factory, request-scoped Mongo repository
brewing.py pure domain logic — gravity parsing, ABV, run aggregation
views/ blueprints: auth, brews, analysis
mongo/repository.py Mongo access for the beer_data and beer_runs collections
templates/ Jinja templates
static/ CSS, JS, fonts, logo (all served locally - no CDN)
tests/ pytest suite
scripts/ operational scripts (the run-metadata backfill)
brewing.py holds every piece of arithmetic and has no Flask or Mongo
dependency, so the maths is unit-testable on its own.
Data model
beer_data — one document per gravity reading
| Field | Type | Notes |
|---|---|---|
_id |
string | 24 random characters |
beer_run_id |
string | The run this reading belongs to, e.g. "20" |
beer_type |
string | Beer/cider name. Free text, per reading — it drifts across a run |
sg |
string | Specific gravity in points: 1039 means 1.039 |
date |
string | YYYY-MM-DD |
final_reading |
string | "True" / "False" — marks the last reading of a run |
comment |
string | Free text |
The unique key is (date, beer_run_id): re-submitting a reading for the same
run and day updates it in place rather than creating a duplicate.
A run is active while it has no reading with final_reading == "True".
beer_runs — one document per run (metadata)
Added alongside the readings to hold what cannot be derived from them: the canonical beer name, the tap number, the recorded original gravity, and brew notes. This collection is only ever inserted into, never written over by the backfill.
Alcohol by volume
Standard homebrew formula:
ABV% = (OG - FG) × 131.25
With gravity stored in points, the drop is already in points, so
ABV% = points_drop × 0.13125.
The previous version of this app used
(max - min) / 7.36 + 0.5, which is not a recognised brewing formula and overstated every result. The old figure is still computed bybrewing.legacy_abv_percent()so the history page can show the difference between the two.
For a run still in the fermenter the figure is an estimate: it uses the run's first reading as the original gravity. A run with a single reading and no recorded OG has no reliable estimate, and the UI shows a dash rather than a misleading number.
Deployment
The image is built and pushed by .gitea/workflows/build_push.yml on push to
master. See RUNBOOK.md for the cluster side.