Roadmap Item: Release 0.6 — External Integration¶

Status¶

PROPOSED

Date: 2026-02-07

Changelog¶

Context¶

For online ordering, ingredient needs must be mapped to retailer-specific catalog items. A shared food knowledge base enables consistent ingredient definitions, categories, and nutrition facts across instances, reducing manual data entry and improving data quality. Price awareness allows the system to select the cheapest acceptable option that satisfies nutrition constraints and brand preferences.

Proposal¶

Overview¶

Online ordering integration via retailer catalog mapping, price awareness with cheapest-acceptable-option selection, and shared food knowledge base syncing.

Goals¶

• Online ordering: map ingredient needs to retailer catalog items
• Respect nutrition constraints and brand preferences during product resolution
• Price awareness: track prices and select cheapest acceptable option
• Knowledge base: shared upstream definitions with local overrides
• Nutrition dataset import from knowledge base

Non-Goals¶

• Smart recommendations for what to cook/eat/buy (v0.7)
• Payment processing or order fulfillment
• Real-time price scraping

Technical Details¶

Approach¶

• RetailerCatalogItem entity mapping ingredient to retailer-specific product with price
• Product resolution service respecting constraints and preferences
• Knowledge base sync protocol (pull upstream, merge with local overrides)
• Nutrition data import pipeline

Dependencies¶

• v0.5 must be complete (nutrition facts, constraints, brand preferences)
• External retailer catalog API (design TBD)
• Knowledge base service (design TBD)

TDs¶

• TD-006: External Integration (planned)

Backwards Compatibility¶

• New integration layer; existing catalog and shopping flows unchanged
• Catalog items gain optional retailer_catalog_item_id link

Implementation Plan¶

Phase 1: Retailer Catalog Mapping¶

• RetailerCatalogItem entity + repository
• Product resolution service
• Migration
• Tests

Phase 2: Price Awareness¶

• Price tracking model
• Cheapest-acceptable-option selection logic
• Integration with shopping plan generation
• Tests

Phase 3: Knowledge Base Sync¶

• Sync protocol design
• Upstream pull + local override merge
• Nutrition dataset import
• Tests

Open Questions¶

• What retailer catalog APIs are available and what formats do they use?
• How frequently should prices be refreshed?
• Should knowledge base sync be manual or automatic?
• How to handle conflicts between upstream and local data?

References¶

• TBD