Derived Allergens

Understand how allergens automatically propagate through ingredients, combos, and variants.

What Are Derived Allergens?

Derived allergens are automatically calculated from relationships:

• From ingredients - Item contains milk because it contains cheese
• From combo components - Combo contains wheat because the burger does
• From variant options - Pizza contains all allergens from all size options

This automation:

• Reduces manual data entry
• Ensures consistency
• Catches allergens you might miss

Ingredient-Based Derivation

When you add ingredients to an item, allergens are suggested:

How It Works

1. You add “parmesan cheese” to an item
2. System recognizes cheese as a dairy product
3. Suggests: This item Contains Milk
4. You confirm or override the suggestion

Common Ingredient Mappings

Confirming Suggestions

Suggestions appear in the allergen section:

1. Open the item
2. Go to Allergens tab
3. See suggestions with “Suggested” label
4. Click to confirm (Contains) or dismiss (Safe)

Overriding Suggestions

If a suggestion is wrong:

1. Click the suggested allergen
2. Select the correct status
3. Add a note explaining why (optional)
4. Save the item

Example: “Contains soy sauce” but you use a wheat-free version → Mark Wheat as Safe.

Combo Derivation

Combo allergens derive from all components and choices.

Fixed Components

If a fixed component contains an allergen, the combo contains it:

Burger Combo:
├── Burger (Contains: Wheat, Milk)
├── Fries (Safe for all)
└── Soda (Safe for all)

Derived: Burger Combo Contains: Wheat, Milk

Choice Groups

Combos show allergens from ALL possible choices:

Pasta Bowl:
├── Pasta (Contains: Wheat)
└── Choose Your Sauce:
    ├── Marinara (Safe)
    ├── Alfredo (Contains: Milk)
    └── Pesto (Contains: Nuts)

Derived: Pasta Bowl Contains: Wheat, Milk, Nuts

Why All Choices?

When diners filter by allergen, they need to know if the combo MIGHT contain it. The parent shows all possibilities so diners investigate further before ordering.

Variant Derivation

Variant parents derive allergens from all options.

How It Works

Salad (Variant Parent):
├── With Chicken (Safe for most)
├── With Shrimp (Contains: Shellfish)
└── With Tofu (Contains: Soy)

Derived: Salad Contains: Shellfish, Soy

Option Changes Propagate

When you update an option’s allergens:

1. Change is saved to the option item
2. Parent’s derived allergens update automatically
3. Any combo using the parent also updates

Update Propagation

Changes ripple through the system:

Ingredient Updated
       ↓
Items Using Ingredient Updated
       ↓
Combos Using Those Items Updated
       ↓
Public Menu Reflects Changes

Timing

• Changes propagate within seconds
• Cached values refresh automatically
• Force refresh by editing and saving

Cache Management

For performance, allergen derivations are cached:

• Cache duration: ~1 minute
• Invalidated on component changes
• Manually refresh by editing the item

Viewing Derived Allergens

On Items

Open an item to see:

• Direct allergens - Set on this item
• Derived allergens - From ingredients/components
• Source - Where each allergen comes from

On Combos

Combo view shows:

• Component breakdown
• Per-component allergens
• Combined result

In Table View

The items table shows:

• Allergen badge count
• Derived indicator (if applicable)
• Click for full breakdown

Managing Derivations

Overriding Derived Allergens

If derivation is wrong, override at the item level:

1. Open the combo or variant parent
2. Go to Allergens
3. Find the derived allergen
4. Click to override
5. Select the correct status

Overrides are stored separately and won’t be changed by automatic derivation.

Resetting to Derived

To remove an override and use derived values:

1. Open the item
2. Find the overridden allergen
3. Click Reset to derived
4. Allergen returns to automatic calculation

Troubleshooting

”Allergen not deriving correctly”

Check:

1. Source item has the allergen marked
2. Component/option is properly linked
3. Wait a minute for cache refresh
4. Edit and save to force update

”Derived allergen is wrong”

Common causes:

1. Source ingredient changed
2. Component was updated
3. Override exists on the item

Fix: Review source items or set an override.

”Changes not propagating”

1. Wait 1-2 minutes for cache
2. Hard refresh the page
3. Edit and save the parent item
4. Check that source items are saved

Best Practices

1. Start with ingredients - Add complete ingredient lists
2. Review derivations - Don’t blindly trust automation
3. Document overrides - Note why you overrode
4. Check after changes - Verify propagation worked
5. Audit periodically - Review derived allergens quarterly

Technical Details

Derivation Rules

1. Contains propagates - If any source Contains, parent Contains
2. Safe requires all Safe - Parent is Safe only if ALL sources are Safe
3. Unconfirmed is neutral - Doesn’t affect derivation
4. Overrides take precedence - Manual settings override derived

Performance

• Derivation happens at save time
• Results are cached for performance
• Complex menus may have brief delays
• Background jobs handle large updates