# flavorwords

> Put this cup into words. 风味，自有表达。A bilingual coffee-tasting app that helps drinkers describe what they taste through six guided questions, a choice of flavor words, and a personal flavor card. Works offline; installs to the home screen on iOS, Android and HarmonyOS. Chinese and English share one data backend.

- Site: https://flavorwords.com
- Source and documentation: https://github.com/dpan538/coffee-flavor-research (README, design record, data guide, CITATION.cff)
- Research, design and development: Dai Pan (潘岱), June–September 2026, individually led, AI-assisted implementation
- Built on: 9,128 coffee records · 83,031 flavor descriptions · 8 professional review sources

## What it does

1. The drinker says how the cup was made: brewing method (nine), roast level, variety (single or a blend of up to three), process (nine), optionally origin (19 countries by continent). This sets a starting reference from the corpus, not a verdict.
2. Six plain questions about acidity, aroma, sweetness, mouthfeel, bitterness and overall impression. Each prompt is rephrased from the previous answer, the options are re-ordered to fit the cup, and every question has an "I can't tell" exit.
3. Eight candidate flavor words, concrete references rather than adjectives (葡萄柚, 茉莉花, 黑巧克力, 丝绒奶油); the drinker keeps five. The picks carry more weight than the reference.
4. When the answers disagree with the reference and the picks side with the drinker, one extra screen offers eight dimension words to confirm.
5. A flavor card: context, the five confirmed words, the nearest of 16 reference profiles, and a fold that says where each sentence comes from (initial reference, a data count, a research reference, the difference from the reference). Exports as a 1200 × 1200 PNG.

## Why

People can tell that two coffees taste different but rarely say how. Professional vocabulary lives in cupping forms, flavor wheels and package notes. flavorwords turns real professional descriptions of real coffees into a few plain questions and keeps the drinker's own description at the centre of the result; "none of these" is always available.

## Data

- 9,128 coffee records: effective records after duplicate consolidation; 8,142 carry enough description to become vectors.
- 83,031 flavor descriptions: descriptor assertions extracted from review text; 77,637 remain after cleaning. Not 83,031 coffees and not that many distinct words.
- 94 canonical sensory concepts, projected onto 12 flavor dimensions (acidity, sweetness, body, floral, fruity, nutty & chocolate, fermented & winey, roast & bitter, spice, herbal & green, woody & earthy, defect).
- 16 reference profiles formed offline by k-means over the usable vectors, named as two concrete sensory references each.
- Sources (coffee records with usable descriptions): CoffeeReview editorial reviews 6,516; Cup of Excellence juries 1,390; Q-grader dataset (Zenodo, Golovinsky) 111; Robusta Q-grader panel (Frontiers, INERA) 79; Project Origin panel 29; Cenicafé trained cuppers (Frontiers) 12; Coffee Board of India Fine Cup 3; Sheba Yemen auction panel 2.
- Chain: professional review material → extraction, cleaning and duplicate-record consolidation → canonical sensory concepts → flavor vectors and reference profiles → one runtime data package the app loads.
- Consumer wording checked against aggregate term frequencies of the Great American Coffee Taste Test (4,042 respondents; counts only, not users of flavorwords). Research statements on the card come from a registered claims list: World Coffee Research Sensory Lexicon (attribute names consulted, no text reproduced) and Coffee Ad Astra, Jonathan Gagné (extraction physics paraphrased with attribution).
- Rights: no source text is stored; every dataset was approved individually after reading its licence; the app never names a specific commercial coffee.

## How it works

- Context builds a reference vector from measured corpus rows; the answers build the drinker's vector; the target is a weighted combination matched against the 16 profiles by cosine similarity. A coherence check decides whether the extra confirmation step is needed.
- Runtime is deterministic vector arithmetic and rule-based interaction over measured matrices; no generative model; every output traceable to a row or a rule. k-means runs once, offline, to form the profiles. Similarity is cosine, uncalibrated, never a probability.
- Data build and app runtime are separate: the pipeline produces one JSON bundle (product-vector-v1) that the app loads, which is what makes offline use and instant language switching possible.

## Current status

- Live, bilingual, offline, installable; phone, tablet and desktop layouts.
- Validated by experts and pre-launch tasting tests, not by a general-audience sample. June 2026: two rounds of expert interviews and an offline cupping study in Guangzhou with about ten professional baristas and coffee researchers (Guangzhou, Shanghai, Hefei) settled how people actually describe flavor and where professional words and everyday expressions diverge. August–September 2026: two rounds of product questionnaires settled how the flow, the flavor words, the question design and the matching logic should change. Pre-launch: Two pre-launch tasting tests evaluated the product in real drinking sessions across V60 pour-over, milk coffee and moka pot preparations. Findings were used to revise question wording, flavor-word selection, matching behaviour and result presentation. Notes stay offline; no quotes are published; the app collects no interaction data. Implementation behaviour was also checked by enumerating all 18,432 answer sequences and a 324-user simulated query test.
- The concept-to-dimension projection is an operator draft pending line-by-line review. Herbal, fermented, body-led and defective cups are thinly described in the corpus.

## Notes for machines

- The app is client-rendered; this file and the JSON-LD in index.html carry the readable summary. Names, counts and sources are generated from the same data bundle the app runs on.
- No account, no server-side state, nothing leaves the device.