> ## Documentation Index
> Fetch the complete documentation index at: https://brewgravity.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> The four things Brewgravity stores, and how they relate.

Brewgravity has a small object model. Learn these five nouns and the rest of the app
— and the whole API — follows from them.

<Steps>
  <Step title="Recipe" icon="flask">
    What you intend to brew. A recipe owns its **fermentables**, **hops**,
    **yeasts**, **other ingredients**, and **mash steps**, plus the brewhouse
    numbers those calculations depend on: batch size, boil time, and efficiency.

    A recipe is a plan. Editing it never rewrites the history of beers you have
    already brewed from it — see **Recipe version** below for how that works.
  </Step>

  <Step title="Recipe version" icon="clock-rotate-left">
    A snapshot of a recipe at one moment, frozen. Versions are created two ways:
    you save one yourself from the **History** tab, and every brew day saves one
    automatically.

    A version never changes once written. That is what lets a brew session point
    at one and still show the recipe *as brewed* however much the recipe moves
    on afterwards. From the History tab you can compare any version against the
    recipe as it stands, restore it, or brew it again as it was.

    <Note>
      Saving a version when nothing has changed reuses the last one rather than
      adding a duplicate, so brewing the same unchanged recipe four times gives
      you four sessions and one version.
    </Note>
  </Step>

  <Step title="Brew session" icon="list-check">
    One actual brew day, made from a recipe. A session owns its **steps** (the
    brew day checklist) and its **fermentation logs**, and records what really
    happened: brew date, measured OG and FG, when fermentation started, when it
    finished.

    One recipe can have many sessions. That is the point — the third time you
    brew a beer is where the interesting data is.

    Every session pins the recipe version it was brewed from, so its brew day
    numbers — strike water, hop schedule, OG and FG targets — are the ones you
    actually brewed with, not whatever the recipe says today.

    <Note>
      Deleting a recipe does not delete its sessions. The recipe is hidden and
      restorable, and its sessions keep working: each one still holds the
      snapshot of what it brewed.
    </Note>
  </Step>

  <Step title="Fermentation log" icon="chart-line">
    A single timestamped reading against a session: gravity, temperature, pH,
    volume, notes, or any combination. Readings marked as **annotations** show
    up as labelled events on the fermentation chart rather than as data points.
  </Step>

  <Step title="Inventory item" icon="box">
    An ingredient you physically have, independent of any recipe: a category
    (fermentable, hop, yeast, or misc), an amount, and the fields that matter
    for that category — alpha acid for hops, colour and yield for grain,
    attenuation for yeast.
  </Step>
</Steps>

## How a session gets its status

Sessions move through four states. Nothing is enforced — you can set any status
at any time — but the intended path is:

| Status       | Means                                                           |
| ------------ | --------------------------------------------------------------- |
| `planning`   | Created but not brewed yet. This is where a new session starts. |
| `brewing`    | Brew day is happening. Work through the checklist.              |
| `fermenting` | Yeast is pitched. Start logging readings.                       |
| `complete`   | Packaged and done.                                              |

## Units

Brewgravity stores everything in metric, always: kilograms, grams, litres,
degrees Celsius, minutes. That is what the API returns, whatever you have
selected in the app.

What you *see* is a display preference. Switch **Settings → Unit system** to US
and the app shows pounds, ounces, gallons, and Fahrenheit while storing the same
underlying numbers. Two brewers on the same account can prefer different units
without either of them converting anything by hand.

<Note>
  Gravity readings are the exception worth knowing about: they are stored as
  specific gravity, but you can enter them as SG, degrees Plato, or Brix, and
  Brewgravity records which unit you typed so the reading round-trips correctly.
</Note>

## Ownership

Every recipe, session, log, and inventory item belongs to exactly one account —
yours. There is no sharing model, no team workspace, and no public recipe
library. The API enforces this on every request: an id that is not yours returns
`404`, not `403`, because whether it exists at all is none of the caller's
business.