Architecture Definition

Overview

NutriBog BogDB Sample is a local-first educational application for exploring nutrition, ingredients, diet labels, and allergen relationships using a graph database. The system is designed for developer learners and evaluators who want to understand graph modeling and querying patterns, with a UI that remains approachable for local end users.

This architecture adopts the following intent decisions as foundational:

• The sample runs locally and does not assume hosted multi-user deployment.
• The graph and UI use the FDA major food allergen list of nine items as the only canonical allergen vocabulary in scope.
• Shellfish is the canonical term everywhere across schema, seed data, UI, example queries, and documentation.
• The Cypher Editor is a first-class capability for direct graph exploration.
• External recipe or ingredient APIs are supporting enrichment sources, not required for core local exploration.
• If external API access fails or quota is exhausted, the system should continue to support browsing and querying of already seeded local graph data.

Architectural Goals

1. Teach graph concepts clearly through a small number of coherent subsystems.
2. Preserve useful local exploration when external data enrichment is unavailable.
3. Keep allergen vocabulary and terminology internally consistent across all layers.
4. Make trust boundaries and safe failure behavior explicit for a local-only sample.
5. Support both guided UI exploration and direct Cypher query learning.

System Context

flowchart LR
  User[Developer learner and local explorer]
  UI[Local web UI]
  App[Local application runtime]
  Graph[BogDB graph database]
  API[External recipe ingredient API]
  Docs[Local docs and example queries]

  User --> UI
  User --> Docs
  UI --> App
  App --> Graph
  App --> API
  Docs --> UI

Primary Subsystems

1. Local Web UI

Purpose:

• Provide guided exploration of recipes, ingredients, diets, and allergens.
• Expose filters, detail views, and teaching-oriented example paths.
• Host the Cypher Editor as a visible first-class feature.

Key responsibilities:

• Render allergen filters using only the canonical FDA 9 set.
• Use Shellfish consistently in visible labels.
• Show clear status when live enrichment is unavailable.
• Present failures visibly and recoverably without implying data corruption.

Out of scope:

• Multi-user identity, access control, or hosted tenancy concerns.

2. Application Runtime

Purpose:

• Orchestrate UI requests, graph access, enrichment fetches, and transformation logic.

Key responsibilities:

• Query and mutate BogDB safely for sample workflows.
• Load seed data and optionally enrich the local graph from external APIs.
• Normalize inbound source data into the canonical domain model.
• Enforce vocabulary consistency where feasible through mapping and validation.
• Redact secrets and sensitive configuration values in routine logs.

Important note:

• The runtime is the main place to isolate source-specific API details from the graph schema and UI vocabulary.

3. BogDB Graph Store

Purpose:

• Persist the local knowledge graph used for browsing and Cypher exploration.

Key responsibilities:

• Store core entities and relationships for recipes, ingredients, allergens, and diets.
• Support direct Cypher access for learning and inspection.
• Remain useful even when live API enrichment is disabled or unavailable.

Design posture:

• The graph is the durable center of the sample experience.
• External data is additive enrichment, not the primary runtime dependency for every interaction.

4. Seed and Import Pipeline

Purpose:

• Create and refresh the local graph from sample fixtures and optional external data.

Key responsibilities:

• Load canonical allergen nodes for the FDA 9 only.
• Build recipe and ingredient relationships from local fixtures and enrichment data.
• Prevent drift back to the retired 12-allergen teaching set.
• Record source provenance where helpful for learning, but without overcomplicating the sample.

5. Example Query and Documentation Bundle

Purpose:

• Teach developers how to traverse the graph.

Key responsibilities:

• Provide updated example Cypher queries aligned to the FDA 9.
• Prioritize allergen to ingredient to recipe traversals as the lead teaching path.
• Keep screenshots, walkthroughs, and in-app help text aligned with current terminology.

Proposed Container View

flowchart TB
  subgraph Local machine
    UI[Web UI]
    App[Application runtime]
    Graph[BogDB]
    Seed[Seed and import tools]
    Query[Example query bundle]
  end

  ExternalAPI[Recipe ingredient API]

  UI --> App
  UI --> Query
  App --> Graph
  Seed --> Graph
  App --> ExternalAPI
  Seed --> ExternalAPI

Domain Model

The domain should stay intentionally small and teachable.

Core domain concepts

• Recipe
  • A food preparation or dish users can browse and query.
• Ingredient
  • A component used by one or more recipes.
• Allergen
  • One of the canonical FDA 9 allergen categories.
• DietLabel
  • A dietary classification used for exploration and teaching.
• DataSource
  • Optional provenance for imported or seeded content.

Canonical allergen set

The architecture assumes exactly these allergen concepts in active scope:

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

Suggested graph entities and relationships

erDiagram
  RECIPE ||--o{ RECIPE_INGREDIENT : includes
  INGREDIENT ||--o{ RECIPE_INGREDIENT : used_in
  INGREDIENT }o--o{ ALLERGEN : may_trigger
  RECIPE }o--o{ DIET_LABEL : tagged_as
  RECIPE }o--o{ DATA_SOURCE : sourced_from
  INGREDIENT }o--o{ DATA_SOURCE : sourced_from

Logical relationship semantics

Suggested conceptual edges:

• Recipe HAS_INGREDIENT Ingredient
• Ingredient MAY_CONTAIN_ALLERGEN Allergen
• Recipe HAS_DIET_LABEL DietLabel
• Recipe SOURCED_FROM DataSource
• Ingredient SOURCED_FROM DataSource

The exact edge names can vary by implementation, but the semantics should remain stable and documentation should use one naming style consistently.

Boundary Decisions

Canonical vocabulary boundary

The graph schema, UI copy, seed fixtures, example queries, and docs must all treat the FDA 9 as the only active allergen vocabulary. The architecture should not preserve a compatibility layer for the retired 12-allergen model unless a later decision explicitly reopens that scope.

External integration boundary

External APIs are optional enrichment providers. They can improve or expand the graph, but the local sample must continue functioning with pre-seeded data when they are unavailable.

Trust boundary

The sample assumes a trusted local operator. Features like Cypher execution and optional scripting are treated as intentional developer actions, but the system should still:

• avoid leaking secrets in normal logs
• fail visibly on bad queries
• avoid silent corruption of graph data
• distinguish between user query failures and data import failures

Logging and diagnostics boundary

Routine operation should keep logs concise and sanitized. Debug behavior may expose more detail, but the architecture should preserve a default of redacting:

• API keys
• secret configuration values
• unnecessary raw payload data

Query text visibility can remain a configurable implementation choice, but the architecture expects safe defaults.

Key Runtime Flows

Flow A: Browse local graph data

1. User opens local UI.
2. UI requests recipes, ingredients, diets, and allergen facets from the application runtime.
3. Runtime queries BogDB.
4. UI renders results and filters using canonical labels.
5. If no live API is available, the flow still succeeds using local graph data only.

Flow B: Enrich local graph from external API

1. Operator triggers seed or enrichment action.
2. Runtime or import tool calls external API.
3. Source data is normalized into internal recipe and ingredient structures.
4. Vocabulary normalization maps source concepts into the canonical schema.
5. Graph updates are written to BogDB.
6. If API quota or connectivity fails, the system reports the issue and preserves existing local data.

Flow C: Run teaching Cypher query

1. User opens the Cypher Editor.
2. User selects or writes a query.
3. UI submits the query to the runtime or directly to the graph integration layer, depending on implementation.
4. Query executes against BogDB.
5. Results or errors are displayed clearly.
6. Failures remain local and recoverable.

Representative Sequence

sequenceDiagram
  participant U as User
  participant UI as Web UI
  participant App as Application runtime
  participant G as BogDB
  participant API as External API

  U->>UI: Open allergen exploration
  UI->>App: Request recipes and facets
  App->>G: Read recipes ingredients allergens
  G-->>App: Local graph results
  App-->>UI: Canonical view model
  UI-->>U: Show recipes and FDA 9 filters

  U->>UI: Trigger enrichment refresh
  UI->>App: Start refresh
  App->>API: Fetch source data
  API-->>App: Data or quota failure
  App->>G: Upsert normalized data when available
  App-->>UI: Refresh status and fallback note
  UI-->>U: Local data remains explorable

Cross-Cutting Concerns

Consistency and migration control

Because the allergen taxonomy changed, the architecture should explicitly treat these as coordinated migration surfaces:

• graph seed fixtures
• UI allergen filters and pills
• example Cypher queries
• walkthrough text and screenshots
• tests and assertions
• schema labels and edge names where allergen names appear

This is important because the sample’s teaching value depends on consistency more than on exhaustive feature breadth.

Failure handling

The system should favor explicit, local, recoverable failures:

• Invalid Cypher returns an error state without damaging the graph.
• Import failures leave existing local graph data intact.
• API quota exhaustion shows a clear message that live fetch is unavailable.
• Partial enrichment should not create ambiguous UI states about what data is current.

Performance posture

As a local educational sample, the architecture should optimize for clarity and responsiveness on small to moderate datasets rather than production-scale throughput. This supports simpler schema choices and more readable example queries.

Security posture

This is not a hardened production architecture, but it should still apply basic hygiene:

• secrets stored in local configuration and not checked into sample defaults
• secret redaction in logs
• clear framing that executable query features are for trusted local use

Architecture Decisions

AD 1 Local first graph centric design

The local graph database is the center of the sample experience. The UI and query tooling should remain useful against local data alone.

AD 2 Canonical FDA 9 allergen model only

The system uses a single canonical allergen set aligned to the FDA major food allergens. The retired 12-allergen set is out of scope and should be removed from active architecture surfaces.

AD 3 Shellfish is the single canonical term

No alternate internal label should coexist for the same concept across schema, docs, examples, or UI.

AD 4 Cypher Editor is a first class subsystem

Direct graph querying is part of the primary teaching experience, not a hidden debug feature.

AD 5 External APIs are optional enrichment only

The application should degrade gracefully to local graph exploration when live sources fail.

AD 6 Safe visible failure over silent behavior

User query errors, import failures, and API outages should surface clearly and should not imply successful updates when none occurred.

Risks and Watchpoints

• Vocabulary drift risk if old example queries, fixtures, or UI labels still reference the retired taxonomy.
• Diet label ambiguity if diet teaching copy implicitly encodes allergen expectations not represented in the canonical model.
• Source normalization mismatch if external APIs use ingredient or allergen terminology that does not map cleanly to the sample schema.
• Debug leakage if verbose local diagnostics expose raw payloads or secrets by default.
• Teaching confusion if the UI and Cypher examples demonstrate different relationship names or traversal patterns.

Recommended Next Design Focus

1. Confirm the graph schema names for nodes and edges used in examples.
2. Define the canonical starter query set, with allergen to ingredient to recipe traversal first.
3. Decide the debug logging policy for query text and raw payload visibility.
4. Review diet label logic and copy for unintended allergen assumptions.

Open Questions

These remain architecture-relevant and should be resolved before detailed design is finalized:

• How should diet labels be modeled so they remain educational without implying unsupported allergen guarantees?
• What level of debug visibility is acceptable for local query text and raw source payloads?
• Which secondary migration assets must be updated in the same change set as the example query refresh?
• Should provenance be visible in the UI, or remain an internal teaching aid for graph inspection only?