Introduction
Internal and partner documentation for PriceHub.AI: how the product decides what to recommend, how the interface layer is built, and how to integrate with it.
What PriceHub.AI does
Most price comparison tools answer "where is it cheapest right now". That question is easy and mostly solved. The harder question is the one people actually ask before spending money:
Is this a good time to buy, or should I wait?
Answering it requires more than a current price. It requires knowing where that price sits in its own recent history, whether the retailer actually has stock, and whether something predictable is about to change the picture.
How an answer is built
| Stage | What happens | Failure behaviour |
|---|---|---|
| Intent | The question is classified | Falls back to open search |
| Retrieval | Sources are queried in parallel | Slow sources are dropped |
| Verification | Freshness and stock are checked | Stale data is discarded |
| Composition | Verdict, evidence, caveat | Narrower verdict, never an error |
Each retrieval call carries its own time budget. Whatever returns inside the window is what the answer is built from.
The rule everything else follows
A number is shown only when it came from a verified source inside the freshness window. A missing value renders as absent, never as zero and never as an estimate.
This is not a style preference. The product competes on trust rather than coverage, and a single wrong price costs more than ten missing ones.
How this documentation is organised
Getting started covers local setup: requirements, environment variables, repository layout.
Product covers decisions rather than code: what the system will and will not claim, and how an answer is assembled.
Design system covers the interface layer: the three-tier token architecture, the six custom components that extend the shadcn/ui baseline, and the motion rules.
Engineering covers the runtime: orchestration, retrieval, and what happens when a source fails.
MCP covers integration for external clients.
Conventions
Code identifiers appear as --color-accent or search_products. Anything in a table marked unavailable means the system had no verified value, not that the value is zero.
Every page has an "Edit this page" link at the bottom. Corrections go through a pull request like any other change.
Funding
PriceHub.AI is developed with funding from the European Union under the EIC Accelerator programme. Views and opinions expressed are those of the authors only and do not necessarily reflect those of the European Union or the granting authority.