Problem

NutriBog BogDB Sample is a local-first educational sample that demonstrates how a nutrition and ingredient knowledge graph can support dietary and allergen exploration using BogDB. The sample is intended primarily for developers and builders learning graph modeling, querying, and UX patterns, while remaining understandable for end users exploring food-related data.

This intent update sets the FDA major food allergen list as the canonical allergen vocabulary for the sample. Downstream design and implementation should treat this list as authoritative for seed data, UI filters, example queries, and documentation. The earlier custom 12-allergen teaching set is removed entirely from current scope and should not be preserved as a parallel taxonomy or backward-compatibility layer.

Context

• The sample showcases graph-backed exploration of foods, ingredients, diet labels, and allergen relationships.
• The runtime target remains local-only execution for development and education, not a hosted production service.
• The Cypher Editor remains a first-class feature for developers to inspect and query the graph directly.
• The allergen model now aligns to the FDA major allergen list rather than the earlier custom 12-allergen teaching set.
• Shellfish is the canonical term to use across schema, docs, example queries, and UI, rather than keeping a longer alternate internal label.

graph TD
  Dev[Developer learner]
  Explorer[Local explorer]
  App[NutriBog sample]
  DB[BogDB graph]
  API[Recipe data API]

  Dev --> App
  Explorer --> App
  App --> DB
  App --> API

Operators and Stakeholders

Primary operators

• Developer learners who want to understand BogDB schema design, graph seeding, and query patterns.
• Builders and evaluators assessing whether BogDB is a good fit for nutrition or relationship-heavy domains.

Secondary stakeholders

• End users of the sample UI exploring foods, ingredients, diets, and allergen relationships in a local environment.
• Project maintainers responsible for keeping sample data, labels, documentation, and examples internally consistent.

Desired Outcomes

• Provide a coherent, runnable sample that demonstrates graph modeling for foods, ingredients, diet labels, and allergens.
• Teach developers how to explore the graph through both guided UI flows and direct Cypher queries.
• Keep allergen handling understandable and intentionally scoped by using the FDA major food allergen list as the sample's canonical allergen set.
• Preserve usefulness when external recipe or ingredient API access is unavailable or quota is exhausted by keeping local graph exploration available.
• Make trust boundaries explicit for a local-only sample, including secret handling, log hygiene, and safe failure behavior.
• Ensure example Cypher queries clearly reflect the FDA 9 allergen model and no longer teach or imply the removed 12-allergen set.
• Prioritize a teaching path that shows how to find relationships from allergens to ingredients and from those ingredients to recipes that include them.

Success Measures

• The sample ships with one canonical allergen vocabulary used consistently across schema, seed data, UI labels, example queries, and documentation.
• The prior 12-allergen teaching set no longer appears in active sample behavior, example queries, UI facets, or primary documentation.
• A developer can run the sample locally and successfully explore allergen relationships without requiring hosted infrastructure.
• The UI exposes allergen-related exploration without contradictory counts or labels.
• Example Cypher queries are updated to the FDA 9 and are treated as the highest-priority migration surface.
• The primary example query set includes at least one clear traversal that helps a learner find allergen relationships from ingredients to recipes that include those ingredients.
• When external API quota is exhausted, users can still browse and query previously seeded local graph data, and the UI clearly explains that live fetch is unavailable.
• Sample documentation makes it clear that the allergen list is based on the FDA major food allergens and is not a comprehensive clinical or international allergen ontology.
• Logs and routine UI states avoid exposing API secrets or unnecessary raw payload detail during normal local use.

Assumptions

• The sample is local-only and intended for education, experimentation, and product evaluation rather than clinical, regulatory, or production decision-making.
• The canonical allergen vocabulary for the sample is the FDA major food allergen list of nine items.
• The prior custom 12-allergen set is fully retired from current scope rather than mapped forward for compatibility.
• The Cypher Editor is a first-class capability for the sample experience and is not hidden as an internal-only tool.
• If external recipe data is unavailable, the core graph exploration experience should remain functional using already seeded local data.
• Routine logs should redact secrets and sensitive configuration values.
• Shellfish is the standard label everywhere in the sample and should not coexist with a longer alternate schema term for the same concept.

Constraints and Boundaries

• Local-only runtime: no assumption of hosted multi-user deployment in this phase.
• Educational scope: the sample may illustrate allergen relationships, but it must not imply medical safety guarantees, regulatory compliance review, or suitability for allergy risk decisions.
• Canonical allergen scope: the sample uses the FDA major allergen list and must not silently mix it with prior custom allergen sets.
• Canonical terminology: downstream work should use the settled nine-item display and schema vocabulary consistently, including Shellfish rather than alternate longer wording.
• Migration boundary: downstream work should remove references to the retired 12-allergen model rather than preserve compatibility shims or mapping tables.
• Priority of update work: example Cypher queries are the highest-priority artifact to revise during this allergen transition, followed by other affected assets.
• Teaching-query priority: the first query examples should emphasize traversing relationships among allergens, ingredients, and recipes, rather than only listing allergen nodes in isolation.
• Data-source boundary: external APIs are supporting sources for enrichment, not a required dependency for every local interaction.
• Failure behavior: when user-provided queries or logic fail, the sample should fail visibly and recoverably rather than corrupting the local graph or leaving the UI in an ambiguous state.
• Sensitive output handling: secrets must be redacted; raw API payloads and verbose query output should not appear in routine logs unless intentionally enabled for debugging.
• Trust boundary for executable features: if the sample supports scripts, custom queries, or executable extensions, they are treated as trusted local-developer actions and should be clearly framed as such.
• Keyboard and host-tool collisions: any editor shortcuts should avoid common host conflicts where practical or document collisions clearly.

Non-Goals

• Building a clinically accurate allergen risk engine.
• Providing legal or regulatory compliance tooling for food labeling.
• Covering every possible allergen, intolerance, additive sensitivity, or international labeling regime.
• Preserving the earlier 12-allergen teaching set for backward compatibility.
• Delivering a hosted SaaS experience or multi-tenant permission model in this phase.
• Guaranteeing that externally sourced nutrition or ingredient data is complete, current, or medically authoritative.
• Maintaining parallel terminology for the same allergen concept across schema, docs, and UI.

Open Decisions

• Diet label interplay: does any current diet-label logic or teaching copy imply allergen categories beyond the FDA list and therefore require cleanup?
• Log sanitization level: should debug mode allow raw query text and API payload inspection, or should those remain redacted by default even during local troubleshooting?
• Migration completion checklist: beyond example Cypher queries, which concrete secondary assets require coordinated cleanup next such as seed fixtures, UI pills, screenshots, walkthrough text, or tests?
• Example query breadth: after the primary allergen to ingredient to recipe traversal is updated, which additional 2 to 4 example queries should complete the teaching sequence?

Canonical FDA Allergen Vocabulary

The sample should use the following allergen concepts as its canonical set:

1. Milk
2. Eggs
3. Fish
4. Shellfish
5. Tree Nuts
6. Peanuts
7. Wheat
8. Soybeans
9. Sesame

Terminology note

• The model is intended to align to the FDA major allergen list.
• The sample standardizes on concise labels where practical.
• For the shellfish category, downstream design should use Shellfish everywhere in schema, documentation, example queries, and UI.

Notes for Downstream Stages

• Treat the FDA list above as the source of truth for schema names, UI filters, fixtures, examples, and tests unless an explicit later decision changes scope.
• If earlier artifacts reference 10 or 12 allergens, interpret those as superseded by this intent update rather than parallel valid vocabularies.
• Remove the earlier 12-allergen teaching set entirely from active examples and educational framing.
• Prioritize updating example Cypher queries before other migration surfaces so the teaching path matches the new allergen scope immediately.
• The first example-query updates should focus on how to find relationships from allergens to ingredients and from those ingredients to recipes that include them.
• Documentation should clarify that this is a teaching-oriented sample aligned to the FDA major allergen list, not a comprehensive food safety knowledge base.