# 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

```bash
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

```bash
. .venv/bin/activate
python -m pytest tests/ -q
```

The tests use `mongomock`, so they need no database and no network.

## 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, (later) 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
```

`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 by `brewing.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](RUNBOOK.md) for the cluster side.