# dpan538/coffee-flavor-research architecture

> Architecture diagram of the GitHub repository dpan538/coffee-flavor-research, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dpan538/coffee-flavor-research
- Repository: https://github.com/dpan538/coffee-flavor-research

## Overview

flavorwords is a bilingual coffee-tasting PWA: a drinker sets cup context, answers adaptive sensory questions, chooses flavor words, may take a second look, then keeps and shares a flavor card. The runtime inference package also supports a separate React site, while the repository documents a professional-description corpus and its preparation. The README establishes the product stages and additional capabilities; source excerpts show selected session-engine and PWA wiring, so uncertain connections are omitted.

Main entry points: [`apps/pwa/src/App.vue`](https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/App.vue) (PWA application), [`packages/flavor-data/src/product-vector-v1/session.ts`](https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/session.ts) (Session API), [`app/routes.ts`](https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes.ts) (Web routes), [`packages/flavor-data/src/product-vector-v1/engine.ts`](https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/engine.ts) (Vector engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pwa["Tasting PWA"]
  node_pwa_app["PWA application<br/>[App.vue]"]
  node_context["Cup context"]
  node_quiz["Guided questions<br/>[QuizCard.vue]"]
  node_description["Word selection"]
  node_attribution["Second look"]
  node_result["Flavor card<br/>[FlavorCard.vue]"]
  node_export["Card export<br/>[exportCard.ts]"]
  node_pwa_store["Flow state<br/>[store.ts]"]
  node_pwa_entry["PWA entry<br/>[main.ts]"]
end

subgraph group_runtime["Flavor inference"]
  node_session["Session API<br/>[session.ts]"]
  node_engine["Vector engine<br/>[engine.ts]"]
  node_flow["Sensory flow<br/>[flow.ts]"]
  node_question_bank["Question bank<br/>[dynamicBank.ts]"]
  node_lexicon["Word mapping<br/>[lexicon.ts]"]
  node_neighbours["Reference neighbours<br/>[neighbours.ts]"]
  node_descriptor_data["Flavor vocabulary<br/>[descriptors.ts]"]
  node_comparison["Comparison data<br/>[comparison.ts]"]
end

subgraph group_research["Corpus research"]
  node_sources["Professional sources"]
  node_source_adapters["Source adapters<br/>[jats.py]"]
end

subgraph group_site["Web companion"]
  node_web_routes["Web routes<br/>[routes.ts]"]
  node_home["Home page<br/>[home.tsx]"]
  node_atlas["Flavor atlas<br/>[atlas.tsx]"]
  node_methodology["Methodology<br/>[methodology.tsx]"]
  node_flavor_page["Flavor detail<br/>[flavor.tsx]"]
end

node_drinker(("Coffee drinker"))

node_drinker -->|"starts tasting"| node_pwa_app
node_pwa_entry -->|"mounts"| node_pwa_app
node_pwa_entry -->|"restores flow"| node_pwa_store
node_pwa_app -->|"shows context"| node_context
node_pwa_app -->|"shows questions"| node_quiz
node_pwa_app -->|"shows choices"| node_description
node_pwa_app -->|"shows second look"| node_attribution
node_pwa_app -->|"shows result"| node_result
node_context -->|"updates context"| node_pwa_store
node_pwa_store -->|"advances session"| node_session
node_session -->|"infers vectors"| node_engine
node_session -->|"builds description"| node_flow
node_session -->|"gets prompts"| node_question_bank
node_session -->|"maps utterance"| node_lexicon
node_flow -->|"builds user vector"| node_engine
node_flow -->|"uses references"| node_neighbours
node_engine -.->|"uses profiles"| node_comparison
node_engine -->|"uses concepts"| node_descriptor_data
node_result -->|"exports card"| node_export
node_sources -->|"acquires material"| node_source_adapters
node_web_routes -->|"routes to"| node_home
node_web_routes -->|"routes to"| node_atlas
node_web_routes -->|"routes to"| node_methodology
node_web_routes -->|"routes to"| node_flavor_page
node_home -->|"uses vocabulary"| node_descriptor_data
node_atlas -->|"uses vocabulary"| node_descriptor_data
node_flavor_page -->|"uses vocabulary"| node_descriptor_data

click node_pwa_app "https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/App.vue"
click node_context "https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/components/ContextSetupCard.vue"
click node_quiz "https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/components/QuizCard.vue"
click node_description "https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/components/FirstDescriptionCard.vue"
click node_attribution "https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/components/FinalAttributionCard.vue"
click node_result "https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/components/FlavorCard.vue"
click node_export "https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/exportCard.ts"
click node_pwa_store "https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/store.ts"
click node_pwa_entry "https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/main.ts"
click node_session "https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/session.ts"
click node_engine "https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/engine.ts"
click node_flow "https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/flow.ts"
click node_question_bank "https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/dynamicBank.ts"
click node_lexicon "https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/lexicon.ts"
click node_neighbours "https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/neighbours.ts"
click node_descriptor_data "https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/descriptors.ts"
click node_comparison "https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/comparison.ts"
click node_sources "https://github.com/dpan538/coffee-flavor-research/blob/main/db/scripts/descriptor-pipeline.py"
click node_source_adapters "https://github.com/dpan538/coffee-flavor-research/blob/main/db/adapters/professional_sources/jats.py"
click node_web_routes "https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes.ts"
click node_home "https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes/home.tsx"
click node_atlas "https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes/atlas.tsx"
click node_methodology "https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes/methodology.tsx"
click node_flavor_page "https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes/flavor.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pwa_app,node_context,node_quiz,node_description,node_attribution,node_result,node_export,node_pwa_store,node_pwa_entry toneBlue
class node_session,node_engine,node_flow,node_question_bank,node_lexicon,node_neighbours,node_descriptor_data,node_comparison toneAmber
class node_sources,node_source_adapters toneMint
class node_web_routes,node_home,node_atlas,node_methodology,node_flavor_page toneRose
class node_drinker toneIndigo
```

## Components

### Tasting PWA

- [PWA application](https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/App.vue): `apps/pwa/src/App.vue`
- [Cup context](https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/components/ContextSetupCard.vue): `apps/pwa/src/components/ContextSetupCard.vue`
- [Guided questions](https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/components/QuizCard.vue): `apps/pwa/src/components/QuizCard.vue`
- [Word selection](https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/components/FirstDescriptionCard.vue): `apps/pwa/src/components/FirstDescriptionCard.vue`
- [Second look](https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/components/FinalAttributionCard.vue): `apps/pwa/src/components/FinalAttributionCard.vue`
- [Flavor card](https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/components/FlavorCard.vue): `apps/pwa/src/components/FlavorCard.vue`
- [Card export](https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/exportCard.ts): `apps/pwa/src/exportCard.ts`
- [Flow state](https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/store.ts): `apps/pwa/src/store.ts`
- [PWA entry](https://github.com/dpan538/coffee-flavor-research/blob/main/apps/pwa/src/main.ts): `apps/pwa/src/main.ts`

### Flavor inference

- [Session API](https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/session.ts): `packages/flavor-data/src/product-vector-v1/session.ts`
- [Vector engine](https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/engine.ts): `packages/flavor-data/src/product-vector-v1/engine.ts`
- [Sensory flow](https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/flow.ts): `packages/flavor-data/src/product-vector-v1/flow.ts`
- [Question bank](https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/dynamicBank.ts): `packages/flavor-data/src/product-vector-v1/dynamicBank.ts`
- [Word mapping](https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/lexicon.ts): `packages/flavor-data/src/product-vector-v1/lexicon.ts`
- [Reference neighbours](https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/product-vector-v1/neighbours.ts): `packages/flavor-data/src/product-vector-v1/neighbours.ts`
- [Flavor vocabulary](https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/descriptors.ts): `packages/flavor-data/src/descriptors.ts`
- [Comparison data](https://github.com/dpan538/coffee-flavor-research/blob/main/packages/flavor-data/src/comparison.ts): `packages/flavor-data/src/comparison.ts`

### Corpus research

- [Professional sources](https://github.com/dpan538/coffee-flavor-research/blob/main/db/scripts/descriptor-pipeline.py): `db/scripts/descriptor-pipeline.py`
- [Source adapters](https://github.com/dpan538/coffee-flavor-research/blob/main/db/adapters/professional_sources/jats.py): `db/adapters/professional_sources/jats.py`

### Web companion

- [Web routes](https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes.ts): `app/routes.ts`
- [Home page](https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes/home.tsx): `app/routes/home.tsx`
- [Flavor atlas](https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes/atlas.tsx): `app/routes/atlas.tsx`
- [Methodology](https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes/methodology.tsx): `app/routes/methodology.tsx`
- [Flavor detail](https://github.com/dpan538/coffee-flavor-research/blob/main/app/routes/flavor.tsx): `app/routes/flavor.tsx`

### Other components

- **Coffee drinker**

## Connections

- Coffee drinker → PWA application: starts tasting
- PWA entry → PWA application: mounts
- PWA entry → Flow state: restores flow
- PWA application → Cup context: shows context
- PWA application → Guided questions: shows questions
- PWA application → Word selection: shows choices
- PWA application → Second look: shows second look
- PWA application → Flavor card: shows result
- Cup context → Flow state: updates context
- Flow state → Session API: advances session
- Session API → Vector engine: infers vectors
- Session API → Sensory flow: builds description
- Session API → Question bank: gets prompts
- Session API → Word mapping: maps utterance
- Sensory flow → Vector engine: builds user vector
- Sensory flow → Reference neighbours: uses references
- Vector engine → Comparison data: uses profiles
- Vector engine → Flavor vocabulary: uses concepts
- Flavor card → Card export: exports card
- Professional sources → Source adapters: acquires material
- Web routes → Home page: routes to
- Web routes → Flavor atlas: routes to
- Web routes → Methodology: routes to
- Web routes → Flavor detail: routes to
- Home page → Flavor vocabulary: uses vocabulary
- Flavor atlas → Flavor vocabulary: uses vocabulary
- Flavor detail → Flavor vocabulary: uses vocabulary