Contentful Content Model Setup Guide

This guide explains how to extend your Contentful content model to support the new flavor profile visualizations, brewing parameters, and enhanced coffee data.

Overview

The coffee ratings site now includes:

Flavor profile radar charts - Visual representation of flavor characteristics
Rating distribution histogram - Statistical overview of all coffee ratings
Brewing parameters - Detailed brewing specifications
Enhanced data structure - Support for detailed tasting notes taxonomy

Content Model Changes

1. Coffee Review (pageBlogPost) Content Type

Add the following fields to your existing pageBlogPost content type:

Flavor Profile Fields

Field Name	Field ID	Type	Description	Validation
Flavor: Acidity	`flavorAcidity`	Number (Decimal)	Acidity level (0-10 scale)	Min: 0, Max: 10
Flavor: Body	`flavorBody`	Number (Decimal)	Body/mouthfeel level (0-10 scale)	Min: 0, Max: 10
Flavor: Sweetness	`flavorSweetness`	Number (Decimal)	Sweetness level (0-10 scale)	Min: 0, Max: 10
Flavor: Bitterness	`flavorBitterness`	Number (Decimal)	Bitterness level (0-10 scale)	Min: 0, Max: 10
Flavor: Fruitiness	`flavorFruitiness`	Number (Decimal)	Fruitiness level (0-10 scale)	Min: 0, Max: 10
Flavor: Aftertaste	`flavorAftertaste`	Number (Decimal)	Aftertaste quality (0-10 scale)	Min: 0, Max: 10

Tasting Notes Fields

Field Name	Field ID	Type	Description	Validation
Primary Tasting Notes	`tastingNotesPrimary`	Short text (List)	Main flavor notes (e.g., "chocolate", "cherry", "caramel")	Required, 1-5 items
Secondary Tasting Notes	`tastingNotesSecondary`	Short text (List)	Supporting flavor notes	Optional, 0-5 items
Tasting Notes Description	`tastingNotesDescriptor`	Long text	Detailed flavor description	Optional

Brewing Parameter Fields (Optional - can be on Brew Method content type instead)

Field Name	Field ID	Type	Description	Example
Brew Temperature	`brewTemp`	Short text	Brewing temperature	"93°C" or "200°F"
Brew Ratio	`brewRatio`	Short text	Coffee to water ratio	"1:16"
Brew Time	`brewTime`	Short text	Total brew time	"3:30"
Grind Size	`grindSize`	Short text	Recommended grind size	"Medium-fine"

2. Brew Method Content Type (Recommended Approach)

Instead of adding brewing parameters to each coffee review, it's better to enhance your existing brew method content type:

Add to Existing Brew Method Fields

Field Name	Field ID	Type	Description	Example
Temperature	`temperature`	Short text	Recommended brewing temperature	"93°C (200°F)"
Ratio	`ratio`	Short text	Coffee to water ratio	"1:16 (15g:240ml)"
Brew Time	`brewTime`	Short text	Total extraction time	"3:00-3:30"
Grind Size	`grindSize`	Short text	Recommended grind size	"Medium-fine"
Equipment	`equipment`	Short text	Required equipment	"Gooseneck kettle, timer"

Implementation Steps

Step 1: Add Fields to Contentful

Log into your Contentful space: xe1b1r0s7mov
Navigate to Content model → pageBlogPost
Click Add field and create each flavor profile field:
- Select Number → Decimal
- Set Field name (e.g., "Flavor: Acidity")
- Set Field ID (e.g., flavorAcidity)
- Under Validation, set minimum: 0, maximum: 10
- Click Create
Repeat for all flavor fields: acidity, body, sweetness, bitterness, fruitiness, aftertaste
Add tasting notes fields:
- Primary Tasting Notes: Short text → List → Required
- Secondary Tasting Notes: Short text → List → Optional
- Tasting Notes Description: Long text → Optional

Step 2: Update Brew Method Content Type

Navigate to Content model → Find your brew method content type
Add the brewing parameter fields listed above
Save the content model

Step 3: Populate Existing Content

You have two options:

Option A: Manual Entry (Most Accurate)

Go through each coffee review and add flavor profile scores based on your tasting experience.

Option B: Keep Mock Data (Quick Start)

The current implementation includes intelligent mock data generation that:

Estimates flavor profiles based on rating and process method
Higher-rated coffees get higher flavor scores
Process methods influence flavor profiles:
- Washed: Higher acidity, brighter fruitiness
- Natural: Higher sweetness and fruitiness, more body
- Honey: Balanced sweetness and acidity
- Anaerobic: Enhanced fruitiness and complexity

To use mock data temporarily, do nothing - the site will automatically generate reasonable flavor profiles until you add real Contentful data.

Step 4: Update Contentful Data Fetching

The code in _data/coffee.js is already set up to:

Check if Contentful fields exist (e.g., flavorAcidity)
Use real data if available
Fall back to intelligent mock data if fields are empty

Once you add the fields to Contentful, simply populate them and rebuild the site.

Data Guidelines

Flavor Profile Scores (0-10 Scale)

Score	Description	Examples
9-10	Exceptional	Vibrant, complex, remarkable
7-8	Very Good	Strong, pleasant, well-developed
5-6	Good	Present, balanced, noticeable
3-4	Mild	Subtle, light, understated
1-2	Very Light	Barely present, minimal
0	None	Absent

Flavor Dimensions Explained

Acidity: Brightness, tanginess, liveliness (think citrus, berries)
Body: Mouthfeel, weight, texture (light/tea-like to heavy/syrupy)
Sweetness: Natural sugars, caramel, honey notes
Bitterness: Pleasant bitterness (dark chocolate, cocoa) vs. astringency
Fruitiness: Fruit flavors (berries, stone fruits, tropical)
Aftertaste: Lingering flavors, finish quality, persistence

Tasting Notes Taxonomy

Primary Notes (Choose 2-4):

Chocolate family: Chocolate, dark chocolate, cocoa, milk chocolate
Caramel family: Caramel, toffee, butterscotch, brown sugar
Nut family: Almond, hazelnut, walnut, pecan
Fruit family: Berry, cherry, apple, citrus, tropical fruit
Floral family: Jasmine, lavender, rose, bergamot
Spice family: Cinnamon, nutmeg, clove, cardamom

Secondary Notes (Choose 1-3):

More specific descriptors
Texture notes (creamy, silky, juicy)
Process-influenced notes (winey, fermented, clean)

Example Content Entry

High-Quality Washed Ethiopian Coffee

Rating: 9.2/10
Origin: Ethiopia - Yirgacheffe
Process: Washed

Flavor Profile:
- Acidity: 9.0
- Body: 6.5
- Sweetness: 7.5
- Bitterness: 3.0
- Fruitiness: 9.5
- Aftertaste: 8.5

Primary Tasting Notes:
- Blueberry
- Jasmine
- Bergamot

Secondary Tasting Notes:
- Black tea
- Honey
- Silky

Tasting Notes Description:
"This exceptional Yirgacheffe showcases classic Ethiopian characteristics
with explosive blueberry notes, delicate jasmine florals, and a vibrant
bergamot-like acidity. The finish is clean, sweet, and remarkably persistent."

Migration Strategy

Phase 1: Enable Mock Data (Complete)

✅ Site now generates intelligent flavor profiles automatically ✅ All visualizations working with estimated data ✅ No Contentful changes required

Phase 2: Add Contentful Fields (Your Action)

Add flavor profile fields to pageBlogPost
Add brewing parameter fields to brew method content type
Add tasting notes fields

Phase 3: Populate Priority Content

Start with your highest-rated coffees (9+) and work down:

Add accurate flavor profiles
Add detailed tasting notes
Update brew method parameters

Phase 4: Bulk Population

Use Contentful's bulk editing features or API to populate remaining entries.

Testing

After adding fields to Contentful:

Add flavor data to one test coffee review
Rebuild the site: npm run build
Check that the coffee detail page shows the radar chart
Verify the homepage shows the rating histogram
Confirm flavor values match your Contentful entry

Troubleshooting

Radar chart shows mock data instead of Contentful data

Verify field IDs match exactly (e.g., flavorAcidity not flavor_acidity)
Check that values are between 0-10
Rebuild the site to fetch fresh data

Histogram not appearing

Ensure ratingStats data is available
Check that you're on the first page (histogram only shows on page 1)
Verify rating values are numeric

Build fails after adding fields

Check for typos in field IDs
Ensure all required fields are populated
Check Contentful API tokens have proper permissions

Future Enhancements

Consider adding:

Processing method details: Fermentation time, drying method
Farm/producer stories: Rich text field for origin stories
Cupping scores: SCA cupping form scores
Roast profile: Development time ratio, roast level details
Brew recipes: Multiple recipe variations per coffee

Support

For questions about:

Content model structure: Review this guide
Field types: See Contentful Field Types docs
API integration: Check _data/coffee.js comments

Current Status: ✅ Mock data implementation complete Next Step: Add Contentful fields and populate with real data Estimated Time: 1-2 hours to set up fields, ongoing for data entry