# Coffee Master - Complete Documentation

> Coffee brewing companion for iOS and Android. Recipes calibrated to the specific bean and your grinder.

## Platform Overview

Coffee Master solves the problem of inconsistent home coffee brewing by reading the coffee bag label (origin, process, roast, roast date) and building a recipe calibrated to that bean and the user's grinder.

### The Problem We Solve

1. Specialty coffee often tastes disappointing at home
2. Every coffee is different but most people use generic recipes
3. Conflicting advice from various sources

### Our Solution

Scan any coffee bag → Get a personalized recipe based on:
- Origin information
- Roast level
- Tasting notes
- Brewing method preference

## Supported Brewing Methods

Coffee Master generates personalized recipes for 10 brewing methods. The six most popular, in detail:

1. **V60 Pour-Over**
   - Precise pour timing
   - Water temperature recommendations
   - Bloom phase guidance

2. **Chemex**
   - Adapted ratios for thicker filter
   - Multi-stage pouring instructions

3. **AeroPress**
   - Standard and inverted methods
   - Pressure and timing guidance

4. **French Press**
   - Steeping time optimization
   - Plunge technique

5. **Espresso**
   - Dose and yield calculations
   - Extraction time targets

6. **Moka Pot**
   - Heat management
   - Fill level guidance

Four additional methods are available in-app. Every recipe includes water ratio, temperature, grind size in exact clicks for the user's grinder (30+ supported: Comandante, 1Zpresso, Timemore, Fellow, Baratza, Eureka, Hario, Kinu, Wilfa, KINGrinder, Option-O), and step-by-step timing.

## Pricing

The first 3 scans are free, no card required. Upgrading unlocks unlimited scans. Scanned coffees and recipes stay in the user's library either way.

## Web Platform Architecture

### Routes

Spanish URLs carry translated segments, not the English ones under an `/es`
prefix. The English-segment forms still resolve but answer 301.

- `/` - Landing page (English)
- `/es` - Landing page (Spanish)
- `/tools` - Tools index
- `/es/herramientas` - Tools index (Spanish)
- `/tools/grinder-converter` - Grinder setting converter
- `/es/herramientas/conversor-de-molinillos` - Grinder setting converter (Spanish)
- `/tools/water-quality-analyzer` - Water quality analyzer tool
- `/es/herramientas/analizador-calidad-agua` - Water quality analyzer tool (Spanish)
- `/guides` - Grinder guides index
- `/es/guias` - Grinder guides index (Spanish)
- `/guides/[slug]` - Grinder settings guide
- `/es/guias/[slug]` - Grinder settings guide (Spanish)
- `/guides/[slug].md` - The same guide as markdown, ~10 KB against ~130 KB
- `/es/guias/[slug].md` - The same, Spanish
- `/@[businessSlug]` - Business profile
- `/@[businessSlug]/[productSlug]` - Product page
- `/recipes` - Community recipes directory
- `/es/recetas` - Community recipes directory (Spanish)
- `/recipes/[method]` - Recipes for one brewing method (v60, aeropress, chemex, french-press, espresso, moka-pot)
- `/recipes/[slug]` - A community recipe with exact parameters and timed steps
- `/b/[publicId]` - Shared brew page
- `/privacy` - Privacy policy
- `/terms` - Terms of service

### Data Models

#### Business Profile

- `username`: URL-safe identifier (used as @slug)
- `name`: Business name
- `description`: About the business
- `country`: Location
- `website`: Official website
- `logo_url`: Brand image

#### Product

- `slug`: URL-safe identifier
- `name`: Product name
- `description`: Product description
- `status`: active/inactive

#### Community Recipe

Self-published by its author from the app (opt-in). Carries no coffee-bag
identity: a public recipe is method, parameters, grinder and steps.

- `name`: Recipe name
- `method`: One of 10 brewing methods (V60, AeroPress, Chemex, French Press, Espresso, Moka Pot, and more)
- `coffee_grams` / `water_grams` / `ratio`: Dose and computed ratio (e.g. 1:16)
- `water_temperature`: Normalized to °C on the directory
- `grinder` + `grind_clicks`: The author's grinder model and exact click setting; each recipe page converts them to any of 30+ supported grinders
- `steps`: Timed, step-by-step instructions (start/end timestamps)
- `saves`: How many people saved the recipe into their app

## Grinder Guides

Thirteen in-depth grind settings guides, each in English and Spanish (Spanish slugs use the `configuracion-` prefix). Append `.md` to any of these URLs for the guide without the page around it:

1. Comandante C40: /guides/comandante-c40-grind-settings
2. 1Zpresso JX-Pro: /guides/1zpresso-jx-pro-grind-settings
3. 1Zpresso K-Ultra: /guides/1zpresso-k-ultra-grind-settings
4. 1Zpresso ZP6: /guides/1zpresso-zp6-grind-settings
5. Baratza Encore: /guides/baratza-encore-grind-settings
6. Baratza Encore ESP: /guides/baratza-encore-esp-grind-settings
7. Baratza Encore ESP Pro: /guides/baratza-encore-esp-pro-grind-settings
8. Eureka Mignon Specialità: /guides/eureka-mignon-specialita-grind-settings
9. Fellow Ode Gen 2: /guides/fellow-ode-gen-2-grind-settings
10. Fellow Opus: /guides/fellow-opus-grind-settings
11. Timemore Chestnut C2: /guides/timemore-c2-grind-settings
12. Timemore Chestnut C3S Pro: /guides/timemore-chestnut-c3s-pro-grind-settings
13. Turin DF54: /guides/turin-df54-grind-settings

## Method Guides

Cross-grinder guides organised by brewing method rather than by grinder. Each one carries a table of the per-grinder setting for that method, linking back to the grinder guide above.

1. Moka Pot: /guides/moka-pot-grind-settings (ES: /es/guias/molienda-para-cafetera-moka)

The `.md` form works here too.

## Brewer Guides

Guides to one specific brewer: its official recipe, technique, filters and care. They have no per-grinder settings table yet.

1. Método Tótem, the Mexican flat-bottom ceramic dripper by Arta Cerámica that takes Kalita Wave 155 filters: /guides/totem-coffee-dripper (ES: /es/guias/metodo-totem)

The `.md` form works here too.

## Structured Data (JSON-LD)

The platform implements the following schemas:

- **Organization** - Site-wide organization info
- **WebSite** - Site-wide website info
- **MobileApplication** - App metadata with download links
- **WebApplication** - Water quality analyzer tool metadata
- **LocalBusiness** - Business profiles
- **FAQPage** - Landing page, tool page and guide FAQ sections
- **HowTo** - Brewing process and tool usage steps
- **Recipe** - Community recipe pages (with HowToStep instructions)
- **ItemList** - Recipes directory and method hubs
- **BreadcrumbList** - Navigation hierarchy

## SEO & Accessibility

### Internationalization

- Full Spanish translation
- hreflang tags for all pages
- Locale-specific meta descriptions

### Semantic HTML

- Proper heading hierarchy (H1-H2-H3)
- ARIA labels on interactive elements
- Microdata markup on profiles
- Skip links for keyboard navigation

### Performance

- Next.js static generation
- Image optimization with next/image
- Lazy loading for below-fold content

## API Information

No public API is available. This is a consumer-facing web platform for the Coffee Master mobile app.

## Contact & Support

- General: hey@coffeemaster.app
- Website: https://coffeemaster.app
- App Store: https://apps.apple.com/app/coffee-master/id6757863500
- Play Store: https://play.google.com/store/apps/details?id=com.coffeemaster.app
- TikTok: https://www.tiktok.com/@coffeemaster.app
- Instagram: https://instagram.com/coffeemaster.app