# Hestia Domain

> **Hestia** - Culinary Intelligence and Smart Home

Library-only domain providing a comprehensive culinary intelligence platform
covering recipe management, guided cooking with voice interface, ingredient
science (flavor compounds and pairing), nutrition analysis with bioavailability
modeling, meal planning, pantry inventory, smart kitchen IoT integration,
culinary heritage preservation, sustainability tracking, culinary education,
professional kitchen tools, social cooking features, and AI/ML-driven
optimization. Named after the Greek goddess of the hearth and home.

---

## Overview

The Hestia domain implements a full-stack culinary technology platform spanning
from ingredient chemistry and nutritional science through to smart kitchen
device orchestration and social cooking experiences. The platform covers the
complete culinary lifecycle: discovering and managing recipes, planning meals
for households, sourcing and tracking ingredients, guided step-by-step cooking
with timer management, nutrition analysis with dietary compliance, and food
preservation through sustainability practices. A distinguishing characteristic
is the depth of food science integration: flavor compound databases drive
ingredient pairing suggestions, bioavailability modeling accounts for nutrient
interactions during cooking, and allergen detection operates at the molecular
level. The IoT layer connects smart ovens, sous vide circulators, thermometers,
scales, and other kitchen devices into automated cooking workflows. Cultural
heritage preservation digitizes family recipes, records oral cooking histories,
and archives regional cuisine traditions. The professional module provides
commercial kitchen tools including menu costing, HACCP food safety compliance,
kitchen workflow optimization, and catering event management.

---

## Architecture

```
             @hestia/ai-ml
             (recipe gen, flavor AI,
              image recog, NLP, predict)
                    |
    +-------+-------+-------+-------+
    |       |       |       |       |
 social  education  professional  heritage
 (sharing, (techniques, (menu cost,  (family,
  cook-along, progression, HACCP,     oral
  challenges) food science) catering)  history)
    |       |       |       |
    +-------+-------+-------+-------+
                    |
    +-------+-------+-------+
    |       |       |       |
 meal-     pantry   sustainability
 planning  (inventory, (carbon,
 (calendar, scanning,  waste,
  budget,   expiration, ethical
  batch)    shopping)   sourcing)
    |       |       |
    +-------+-------+-------+
    |       |       |
 recipes   cooking  smart-kitchen
 (model,   (guided, (devices,
  parsing,  timers,  sensors,
  scaling,  voice,   appliances,
  search)   doneness) automation)
    |       |       |
    +-------+-------+
            |
    +-------+-------+
    |               |
 ingredients     nutrition
 (database,      (analysis,
  flavor         bioavailability,
  compounds,     dietary,
  pairing,       allergen,
  substitution,  medical diet,
  seasonality)   goals)
            |
       @hestia/core
    (schemas, DB, types,
     events, auth)
```

### Layer Summary

1. **Core** - Domain schemas with pure TypeScript interfaces and validation
   functions, Drizzle ORM database schema, domain event definitions, types, and
   authentication utilities
2. **Science** - Ingredient master database with flavor compound analysis and
   pairing intelligence; nutrition analysis with bioavailability modeling,
   allergen detection, and medical diet support
3. **Cooking** - Recipe management with parsing, scaling, and versioning; guided
   cooking with timers and voice interface; smart kitchen IoT integration
4. **Planning** - Meal planning with household support and budgeting; pantry
   inventory with barcode scanning and expiration tracking; sustainability
   metrics
5. **Culture** - Culinary heritage preservation; culinary education with
   progression tracking; professional kitchen tools; social cooking features;
   AI/ML intelligence

---

## Libraries (14)

### `@hestia/core` - Core Foundation

Core foundation providing domain schemas, database schema, type definitions,
domain events, and authentication utilities for the entire Hestia platform.

**Key exports:** `schemas` (pure TypeScript interfaces with validation
functions), `db-schema` (Drizzle ORM tables), `types`, `events`, `auth`

The schema layer defines comprehensive domain types using pure TypeScript
interfaces rather than Zod runtime schemas. Measurement units cover both US
(tsp, tbsp, cup, fl_oz, pint, quart, gallon, oz, lb) and metric (ml, liter,
gram, kg) systems plus informal units (pinch, dash, piece, clove, sprig, bunch).
Cooking methods enumerate all major techniques (bake, roast, broil, grill,
saute, fry, deep_fry, stir_fry, steam, boil, simmer, and more). These enums are
defined as const objects with derived type unions for both runtime and compile-
time safety.

**Dependencies:** none (zero runtime dependencies)

### `@hestia/smart-kitchen` - Smart Kitchen IoT Integration

Smart kitchen device management and automation with six sub-modules.

**Devices** provides device registration, discovery, pairing, and lifecycle
management for kitchen IoT devices.

**Cooking devices** manages smart ovens, sous vide circulators, induction
cooktops, pressure cookers, and other connected cooking appliances with
temperature profiles and cooking programs.

**Sensors** handles kitchen sensors including temperature probes, humidity
sensors, smoke detectors, and smart scales with real-time data streaming.

**Smart appliances** integrates with connected refrigerators, dishwashers, and
other household appliances for inventory awareness and energy optimization.

**Automation** implements rule-based automation workflows triggered by cooking
events, sensor readings, timer completions, and recipe steps.

**Orchestration** coordinates multi-device cooking scenarios where multiple
appliances work together for complex meal preparation with timing
synchronization.

**Peer dependencies:** `@hestia/core`

### `@hestia/recipes` - Recipe Management

Comprehensive recipe management system with seven sub-modules.

**Recipe model** defines the core recipe data structure with ingredients,
instructions, timing, equipment, tags, and metadata.

**Parsing** extracts structured recipe data from unstructured text, URLs, and
images using pattern matching and NLP techniques.

**Import/export** handles recipe interchange in multiple formats including JSON,
YAML, Recipe Schema.org JSON-LD, and plain text.

**Scaling** adjusts ingredient quantities for different serving sizes with
intelligent rounding and unit conversion, handling edge cases like eggs and
seasoning that do not scale linearly.

**Versioning** tracks recipe modifications with full history, branching, and
merge support for collaborative recipe development.

**Search** provides full-text search across recipes with filtering by cuisine,
diet, cooking method, ingredient, time, and difficulty.

**Collections** organizes recipes into user-defined collections, cookbooks, and
auto-generated seasonal or thematic groupings.

**Peer dependencies:** `@hestia/core`

### `@hestia/cooking` - Guided Cooking

Step-by-step cooking guidance with six sub-modules.

**Guided cooking** provides interactive step-through cooking sessions with
progress tracking, step reordering for multi-recipe meal coordination, and
real-time adjustments.

**Timers** manages multiple concurrent cooking timers with alerts, including
relative timers (start when step begins) and absolute timers (finish by specific
time) with conflict detection.

**Voice** implements voice command recognition for hands-free cooking control
including timer management, step navigation, unit conversion queries, and
substitution lookups.

**Doneness** provides visual and temperature-based doneness guides for proteins,
baked goods, and other items with USDA-recommended internal temperatures and
resting time calculations.

**Techniques** offers detailed technique instruction for fundamental cooking
methods with video references, common mistakes, and skill-level appropriate
guidance.

**Session log** records complete cooking session data including timing, notes,
modifications, and outcomes for future reference and skill tracking.

**Peer dependencies:** `@hestia/core`

### `@hestia/ingredients` - Ingredient Intelligence

Deep ingredient knowledge with six sub-modules.

**Master database** provides a comprehensive ingredient database with
categorization, aliases, regional name variations, and measurement conversions.

**Nutrition** maps ingredients to complete nutritional profiles including
macronutrients, micronutrients, and USDA FDC (FoodData Central) identifiers.

**Flavor compounds** models the volatile and non-volatile compounds responsible
for ingredient flavors, enabling scientifically-grounded flavor pairing. Covers
hundreds of compounds across flavor families (fruity, floral, earthy, umami,
Maillard, sulfurous).

**Pairing** uses flavor compound overlap analysis and traditional culinary
affinity databases to suggest complementary ingredient combinations, with
scoring that accounts for both chemical compatibility and cultural context.

**Substitution** recommends ingredient replacements accounting for flavor
profile similarity, textural properties, cooking behavior, and dietary
restrictions. Handles common allergenic substitutions (dairy-free, gluten-free,
egg-free) with tested alternatives.

**Seasonality** tracks ingredient availability by season and region, providing
peak season recommendations for optimal flavor and sustainability.

**Peer dependencies:** `@hestia/core`

### `@hestia/nutrition` - Nutritional Analysis

Six-module nutritional science engine.

**Analysis** calculates per-serving and per-recipe nutritional content
accounting for cooking method effects (boiling leaches minerals, frying adds
fat, roasting concentrates sugars).

**Bioavailability** models nutrient absorption efficiency based on preparation
method, nutrient interactions (vitamin C enhances iron absorption, phytates
inhibit zinc uptake), and individual factors. Goes beyond raw nutrient values to
estimate actual nutritional benefit.

**Dietary** manages dietary frameworks including vegetarian, vegan, keto, paleo,
Mediterranean, DASH, low-FODMAP, and custom user-defined diets with compliance
checking against recipes and meal plans.

**Allergen** detects allergens at the ingredient level covering the major
allergen groups (dairy, eggs, fish, shellfish, tree nuts, peanuts, wheat/gluten,
soy) plus additional sensitivities. Handles hidden allergens in processed
ingredients and cross-contamination warnings.

**Medical diet** supports medically-prescribed dietary restrictions including
renal diet, diabetic diet, cardiac diet, and elimination diets with professional
guidance integration.

**Goals** manages personalized nutrition targets based on age, sex, activity
level, and health goals with progress tracking and deficit/surplus alerting.

**Peer dependencies:** `@hestia/core`

### `@hestia/meal-planning` - Meal Planning

Six-module meal planning system.

**Calendar** provides weekly and monthly meal plan calendars with drag-and-drop
meal assignment, recurring meal patterns, and leftover integration.

**Household** manages multi-person households with individual dietary
preferences, allergen profiles, and portion size adjustments per family member.

**Suggestions** generates meal recommendations based on pantry contents,
seasonal ingredients, budget constraints, nutritional balance, and taste
preferences.

**Budget** tracks meal costs with per-serving calculations, weekly/monthly
budget targets, and cost optimization suggestions.

**Batch cooking** plans batch cooking sessions that maximize efficiency by
identifying recipes that share ingredients and preparation steps, with
make-ahead and freezer-friendly meal scheduling.

**Events** handles meal planning for special occasions, dinner parties, and
holiday meals with guest count scaling and dietary accommodation.

**Peer dependencies:** `@hestia/core`

### `@hestia/pantry` - Pantry Inventory

Pantry and kitchen inventory management with six sub-modules.

**Inventory** tracks pantry items with quantities, locations, and categories.

**Scanning** supports barcode scanning and OCR receipt processing for rapid item
entry with automatic product identification.

**Expiration** monitors expiration dates with configurable alerts, FIFO rotation
guidance, and waste reduction recommendations.

**Shopping** generates shopping lists from meal plans and low-stock alerts with
store aisle organization and price comparison.

**Grocery store** maps to specific store layouts for optimized shopping routes
with price tracking and sale notifications.

**Equipment** manages kitchen equipment inventory with maintenance schedules and
usage tracking to inform recipe feasibility.

**Peer dependencies:** `@hestia/core`

### `@hestia/heritage` - Culinary Heritage Preservation

Cultural culinary heritage preservation system with five sub-modules.

**Family recipes** digitizes handwritten and oral family recipes with photograph
preservation, author attribution, and family tree linkage.

**Oral history** records and transcribes cooking-related oral histories with
audio/video storage, tagging, and searchable transcripts.

**Regional archive** catalogs regional cuisine traditions with geographic
mapping, historical context, and endangered recipe identification.

**Food history** provides research-grade food history content with timeline
visualization, cultural influence mapping, and ingredient origin tracking.

**Community** enables community contribution to heritage preservation with
moderation, peer review, and cultural sensitivity guidelines.

**Peer dependencies:** `@hestia/core`

### `@hestia/sustainability` - Sustainable Living

Environmental sustainability tracking with five sub-modules.

**Carbon footprint** calculates the carbon impact of meals considering
ingredient sourcing, transportation distance, farming practices, and cooking
energy consumption.

**Food waste** tracks food waste with categorization, reduction goal setting,
and composting guidance. Provides waste-reduction recipe suggestions for
ingredients approaching expiration.

**Ethical sourcing** evaluates ingredient sourcing practices including fair
trade certification, organic status, animal welfare standards, and labor
practices.

**Seasonal and local** promotes seasonal and locally-sourced cooking with
regional availability data, farmer market integration, and food mile reduction
tracking.

**Composting** provides composting guidance for kitchen waste with carbon-to-
nitrogen ratio management, troubleshooting, and harvest timing.

**Peer dependencies:** `@hestia/core`

### `@hestia/education` - Culinary Education

Comprehensive culinary education platform with six sub-modules.

**Techniques** provides a technique library covering knife skills, heat control,
flavor development, sauce making, baking fundamentals, and preservation methods
with difficulty ratings and video references.

**Progression** implements skill progression tracking with mastery levels,
practice logging, and personalized learning paths.

**Food science** offers courses on the science of cooking including Maillard
reaction, emulsification, gelation, fermentation, and protein denaturation with
interactive experiments.

**Cuisine** provides deep-dive modules into world cuisines covering essential
techniques, pantry staples, and signature dishes for each cuisine tradition.

**Certifications** manages culinary certification programs with curriculum
tracking, assessment, and credential issuance.

**Interactive** implements interactive learning features including quizzes,
cooking challenges, and peer-assessed assignments.

**Peer dependencies:** `@hestia/core`

### `@hestia/professional` - Professional Kitchen Tools

Commercial kitchen operations with six sub-modules.

**Menu costing** calculates food cost percentage, plate cost, and menu pricing
with ingredient cost tracking and profit margin analysis.

**Kitchen workflow** optimizes kitchen station assignments, prep scheduling, and
service timing for restaurant operations.

**Inventory management** provides commercial-scale inventory with par levels,
vendor management, purchase order generation, and waste tracking.

**Food safety** implements HACCP (Hazard Analysis Critical Control Points)
compliance with critical control point monitoring, corrective action logging,
temperature logs, and audit-ready documentation.

**Catering and events** manages catering operations including event quotation,
menu customization, dietary accommodation, staffing requirements, and timeline
planning.

**Recipe development** supports professional recipe development with version
control, test batch tracking, sensory evaluation, and production scaling.

**Peer dependencies:** `@hestia/core`

### `@hestia/social` - Social Cooking Features

Social cooking platform with six sub-modules.

**Recipe sharing** enables recipe publishing with privacy controls, attribution,
and collaborative editing.

**Profiles and following** provides cook profiles with following relationships,
activity feeds, and cooking statistics.

**Ratings and reviews** implements recipe rating with detailed reviews, photo
submissions, and helpful voting.

**Cook-alongs and events** organizes live cooking events with real-time
participation, synchronized timers, and video integration.

**Family cookbook** creates shared family cookbooks with contribution
management, printing support, and gift preparation.

**Community challenges** runs cooking challenges with themes, entry submission,
voting, and prize management.

**Peer dependencies:** `@hestia/core`

### `@hestia/ai-ml` - AI/ML Intelligence

Machine learning capabilities for culinary intelligence with six sub-modules.

**Recipe generation** creates novel recipes using LLM-based generation
constrained by ingredient availability, dietary requirements, cuisine style, and
nutritional targets.

**Flavor pairing** uses ML models trained on flavor compound data and recipe
corpora to discover non-obvious ingredient combinations.

**Image recognition** identifies ingredients and dishes from photographs with
portion size estimation and nutritional inference.

**Recommendations** provides personalized recipe and meal recommendations using
collaborative filtering, content-based filtering, and contextual signals (time
of day, season, weather, pantry contents).

**NLP** processes natural language cooking queries, recipe search, and
conversational cooking assistance.

**Predictive analytics** forecasts grocery needs, identifies cooking trends,
predicts meal preferences, and optimizes batch cooking schedules.

**Peer dependencies:** `@hestia/core`

---

## Technology Stack

| Component   | Technology                         |
| ----------- | ---------------------------------- |
| Language    | TypeScript (ESM)                   |
| Runtime     | Node.js                            |
| Build       | Nx with `@nx/js:tsc`               |
| Testing     | Vitest                             |
| Validation  | Pure TypeScript (no Zod runtime)   |
| Food Safety | HACCP, USDA temperature guidelines |
| Nutrition   | USDA FoodData Central reference    |
| IoT         | Smart kitchen device protocols     |

---

## Development

```bash
# Test a specific library
pnpm nx test @hestia/core

# Build all Hestia libraries
pnpm nx run-many --target=build --projects=tag:scope:hestia

# Lint a library
pnpm nx lint @hestia/recipes

# Run all domain tests
pnpm nx run-many --target=test --projects=tag:scope:hestia
```

### Configuration

- **Project tags:** `["scope:hestia", "layer:domain", "type:lib"]`
- **Build executor:** `@nx/js:tsc`
- All libraries use ESM (`"type": "module"`)
- Core has zero runtime dependencies (pure TypeScript schemas)
- All other libraries use `@hestia/core` as a peer dependency

### Dependency Graph

```
@hestia/core (standalone, zero deps)
  |
  +-- @hestia/smart-kitchen (peer: core)
  +-- @hestia/recipes (peer: core)
  +-- @hestia/cooking (peer: core)
  +-- @hestia/ingredients (peer: core)
  +-- @hestia/nutrition (peer: core)
  +-- @hestia/meal-planning (peer: core)
  +-- @hestia/pantry (peer: core)
  +-- @hestia/heritage (peer: core)
  +-- @hestia/sustainability (peer: core)
  +-- @hestia/education (peer: core)
  +-- @hestia/professional (peer: core)
  +-- @hestia/social (peer: core)
  +-- @hestia/ai-ml (peer: core)
```
