Ingredients & Allergens — Admin User Guide

A walkthrough of the admin UX for the Ingredients & Allergens app.

1. What this app does

The Ingredients & Allergens app puts a clear, trustworthy ingredient label behind every product scan.

When a customer scans a product (or opens its page) they see:

• A readable ingredient list, automatically translated into their language
• The 14 EU major allergens that are present, with clear icons
• "May contain" warnings for cross-contamination risk
• Dietary labels (vegan, halal, gluten-free, organic, and more)
• A personal warning if the product contains anything on their allergen list

It works for food, drink, cosmetics, and any product where ingredient transparency matters. You configure ingredients once per product (or once for a group of products); customers get a personalised, multilingual experience automatically.

2. The admin shell at a glance

When you open the app from a product page in the SmartLinks console, you land directly on that product's ingredient record — no picker, no list view.

The shell has three parts:

• Scope tabs along the top — Collection · Rule · Facet · Product · Variant · Batch. The tab matching the current context is selected by default. Switching tabs lets you target a different anchor (e.g. share a recipe across a whole facet, or override one batch).
• Browser pane on the left — lists every existing record in the current scope. Click one to load it into the editor. Use the + New button to start a fresh record.
• Editor on the right — the five editing tabs (Ingredients, Allergens, Dietary, Origin, Translations).

A sticky footer runs along the bottom with Save, Discard, and Delete. The Save button is enabled only when there are unsaved changes; Delete is hidden until a record has been saved at least once.

Inheritance markers. When you view a product that doesn't have its own record but inherits one from a facet rule, the editor shows a small banner indicating where the record actually lives. Edits create a new product-level record that overrides the inherited one.

3. Creating a record

Step 1 — Pick the scope

Use the scope tab that matches what you want to do:

Override order (most specific wins): batch → variant → product → rule → facet → collection.

Step 2 — Fill in the editor

Ingredients tab

Paste your full ingredient text — comma-separated, exactly as it appears on the pack. Click Parse with AI.

The parser splits ingredients, flags allergens, suggests dietary labels, and seeds translations. Each detected ingredient appears as a badge; ones containing an allergen are highlighted.

Allergens tab

Two sections, both showing all 14 EU major allergens:

Click an allergen to toggle it. Each allergen can only sit in one list at a time — moving it to "Contains" automatically removes it from "May Contain", and vice versa.

The 14 EU major allergens: celery, gluten-containing cereals, crustaceans, eggs, fish, lupin, milk, molluscs, mustard, tree nuts, peanuts, sesame, soybeans, sulphites.

Dietary tab

Toggle each label that applies (vegan, vegetarian, pescatarian, halal, kosher, gluten-free, dairy-free, nut-free, low-sodium, organic). For every label you turn on, choose how it should be shown:

Origin tab

For each parsed ingredient, optionally add a country or region (e.g. "France", "Italy"). Customers see this in the detailed ingredient view. Leave blank if unknown.

Translations tab

Translations now work in two layers:

1. On-the-fly — at render time the public page asks the platform's translation service to translate any missing language on demand, using the source-language rawIngredientText. Customers in all 10 supported languages get something readable without you doing anything. Machine-translated entries are tagged "auto" on the public page, with a small disclaimer that the printed pack is authoritative.
2. Curated overrides — click any language button to generate, review, and save a translation into the record. Saved translations are treated as authoritative and replace the machine version. A green tick appears next to languages that have a curated entry.

Use the curated layer when copy matters (regulated markets, legal phrasing, brand voice); otherwise the on-the-fly layer is enough.

Step 3 — Save

Click Save in the sticky footer. The record is written immediately and the public page picks it up within seconds.

4. Day-to-day usage — what customers see

A customer scans a product or opens its page and lands on the ingredients view:

1. Language. Loads in the customer's preferred language. Curated translations win; otherwise the platform translates on the fly.
2. Ingredient list. Clean, readable, comma-formatted. Allergen keywords are bolded.
3. Allergen banner. A red warning appears at the top if the product contains any of the customer's personal allergens.
4. "Contains" allergens. Red badges with icons.
5. "May contain" warnings. Amber badges with icons.
6. Dietary labels. Prominent labels shown to everyone; discrete labels only appear if the customer has selected that need.
7. Settings panel. A gear icon lets the customer set their own allergens, dietary needs, and preferred language. Their choices are remembered on their device.
8. Printable label. A print button generates a clean, regulation-style label.

Everything is mobile-first and needs no login.

5. Widgets

The app ships one widget for embedding inside other SmartLinks apps and pages: Ingredients Widget, in three sizes:

If the customer has set personal allergens, the widget highlights the ones that affect them.

6. Managing existing records

The browser pane on the left lists every record in the current scope. Each row shows the anchor (product name, facet value, rule summary) and a quick summary of allergens.

• To edit: click the row. The editor loads its contents.
• To delete: open the record and click Delete in the sticky footer. You'll be asked to confirm.
• To override an inherited record: open the product, make your changes, and Save — a product-level record is created that takes precedence over the facet/rule it was inheriting from.

Tip: Because facet and rule records cover many products at once, deleting one affects every product they match. Edit instead when in doubt.

7. Bulk import

Bulk import is handled via the SmartLinks console's record importer using the records API. The shape of each row matches the data payload documented in public/ai-guide.md (§3). Use that document — or hand it to your AI tooling — when preparing large catalogues.

8. FAQ & troubleshooting

Q: I created a facet record but a few products still show no ingredients. Check those products are actually tagged with the facet value you used. Untagged products won't match. Either tag them, or create a product-level record for the exception.

Q: I edited a record but the product page still shows the old ingredients. The customer's browser may have cached the page. Ask them to refresh. Changes are live within seconds for new visitors.

Q: AI parsing missed an allergen — is it safe to rely on? Always review what the AI detected before saving. The Allergens tab is your final say. Toggle anything that's wrong. The app stores your confirmed list, not the AI's guess.

Q: A customer says they're allergic to something but the warning didn't appear. Personal warnings only fire for allergens the customer has added to their own preferences (via the gear icon on the public page). Only the 14 EU majors are tracked.

Q: Can I change the list after launch? Yes — edit anytime. There's no review flow; saves go live immediately. Be careful with allergen edits, since these have legal implications.

Q: A product is part of a facet group but needs a different recipe for one batch. Create a batch-level (or variant-level) record. It overrides the shared facet record without affecting the other products in the group.

Q: Translations look slightly wrong in one language. Open the Translations tab, regenerate the language, edit the text inline, and Save — your curated version replaces the on-the-fly machine translation.

Q: What happens if I delete a facet record that covers 50 products? All 50 products lose their ingredient page until a replacement record matches them. The public UI shows "Allergen information unavailable" rather than displaying anything incorrect.

This guide reflects the live behaviour of the app. If something on screen doesn't match what you read here, the on-screen behaviour wins — please flag it so we can update this document.

Future surfaces

This app does not currently ship a MobileAdminContainer. Admin configuration is desk-based and there is no field/operator workflow requiring NFC, RFID, QR scanning, or camera capture by admins.