# Nutrition data — the contract between the agent team, Fiesta and the app

The customer app shows a nutrition panel on the product screen. The data comes
from the global catalogue, which the agent team fills. This is what each side
has to produce and can rely on.

---

## 1. What the app receives

`GET /live/api/v1/mob/products/getproductbyvariant?tenantid=&productid=&variantid=`

Each product in `details[]` carries:

```json
"nutrition": {
  "per": "100g",
  "servingsize": "30g",
  "items": [
    { "name": "Energy",        "value": 520, "unit": "kcal" },
    { "name": "Protein",       "value": 6.5, "unit": "g" },
    { "name": "Total Sugars",  "value": 22,  "unit": "g" },
    { "name": "Sodium",        "value": 310, "unit": "mg" }
  ]
}
```

Rules the app can build on:

- **The key is ABSENT when nothing is known.** Not `null`, not `{}`. A missing
  key means "we do not know", never "this food has no nutrition".
- **`items` is never empty when `nutrition` is present.** A panel with no rows
  is not sent, because an empty box on a product page reads as a claim.
- **`per` and `servingsize` are each optional** and often absent — see §3. Show
  the basis only when it is there. Do not default it to `100g`: a wrong basis
  makes every figure beneath it a misstatement rather than an unknown.
- **`value` is a number, and may be a decimal.** Saturated fat is 11.5 g as
  often as 11 g.
- **`unit` is free text and may be absent.** "Servings per pack 4" has a figure
  and no unit.
- **A row may have a `name` and a `value` of 0 with no unit.** That is real
  label text with no number in it — "Contains permitted natural colour". Render
  the name and leave the figure column blank; do not print `0`.
- Every member of a variant group carries its own panel, so switching from
  500 ml to 1 L does not blank the screen.

## 2. What the agent team fills

A `nutrition` column of type **`jsonb`** on each `brand_*` table in the
catalogue database, holding exactly the object above.

```sql
ALTER TABLE brand_patanjali ADD COLUMN IF NOT EXISTS nutrition jsonb;
```

Notes:

- **The column is optional and Fiesta already handles its absence.** Catalogue
  reads discover columns per table and substitute NULL for any that are missing,
  so brands can be filled one at a time and a table without the column keeps
  working. Nothing has to be co-ordinated with a deploy.
- **Spelling is `servingsize`**, one word, lowercase. It is the shape the app
  was written against.
- **Write what the label says.** If the pack states per 100 g, `per` is `"100g"`.
  If it states per serving, say so. If it states neither, omit the field rather
  than assuming.
- `nutrition` and the older `nutrients` may both exist on a row. Keep both —
  the console shows the lines, the app shows the panel, and they are different
  readers with different needs.

## 3. Where today's data comes from, and why it is thinner

Every catalogue row currently holds nutrition as `nutrients`, a `text[]` of
display lines:

```
{"Energy 350kcal", "Protein 7g"}
```

Fiesta parses those into the same panel shape when no structured `nutrition`
exists, so the app shows figures for products the agent team has not reached
yet. That derived panel has **no `per` and no `servingsize`** — the strings
never carried them — which is the visible difference between a filled brand and
one still waiting.

Parsing rules, in `models/nutrition.go`:

| line | becomes |
|---|---|
| `Energy 350kcal` | `{Energy, 350, kcal}` |
| `Protein: 6.5 g` | `{Protein, 6.5, g}` |
| `Energy - 520 kcal` | `{Energy, 520, kcal}` |
| `Vitamin B12 1.2µg` | `{Vitamin B12, 1.2, µg}` |
| `Servings per pack 4` | `{Servings per pack, 4, ""}` |
| `Contains permitted colour` | `{Contains permitted colour, 0, ""}` — kept whole |
| `100` | dropped — a figure with no label is noise |

Structured always wins over derived where both exist.

## 4. How it reaches a shop's product

The catalogue is the source; a tenant's product is a **snapshot** taken at
import, because the catalogue is re-scraped and rows retire. Chain:

```
brand_*.nutrition (agent team)
  └─ catalogue read  ─ repositories/catalogueRepository.go: nutritionOf
       └─ import     ─ services/productService.go: catalogueFactsOf
            └─ products.cataloguefacts → {"nutrition": {...}, "nutrients": [...]}
                 └─ endpoint ─ services/productService.go: decorateNutrition
```

`getproductbyvariant` does **not** query the catalogue database. That would be a
cross-database lookup per product on a screen a shopper is waiting on. It reads
the snapshot only.

## 5. Products imported before the snapshot existed

**This is the one thing that must be done before any of it shows.**

`cataloguefacts` is empty on every product imported before that column existed —
measured on tenant 1147: 17 products, 15 catalogue-imported, **0 with facts**.
Those products will show no nutrition no matter what the catalogue holds.

The fix is a one-off backfill, which also restores their FSSAI licence,
highlights and provider list:

```sh
go run ./scratch/cataloguefactsbackfill        # dry run — prints every change
go run ./scratch/cataloguefactsbackfill apply  # writes, then prints the undo
```

It touches only products with an `imageid` and a NULL `cataloguefacts`, so
re-running it is a no-op rather than a second opinion. Run it **after** the agent
team fills a brand to pick up that brand's structured panels; it is safe to run
repeatedly as more brands are filled.