Hestia — Technical Specifications

Culinary Intelligence and Smart Home domain. Named after the Greek goddess of the hearth and home.

Hestia is the Oshun culinary intelligence platform: 14 feature libraries under libs/hestia/ plus three applications — apps/hestia/api (Fastify REST + GraphQL), apps/hestia/web (Next.js), and apps/hestia/mobile (Expo / React Native). This document is the complete technical reference, grounded directly in the source under libs/hestia/* and apps/hestia/*.

The 14 libraries share a single foundation (@hestia/core) that carries the canonical domain types, the PostgreSQL schema, the event system, and the authorization model — all with zero runtime dependencies, so they can be used in any Node.js, browser, or edge context. Every other library declares @hestia/core as a peer dependency and adds its own domain logic on top. No feature library depends on another feature library; all coupling between capabilities happens at the application layer.

This reference covers: the domain overview property table; the full library inventory; the core domain model (types, enumerations, database schema, events, authorization); the domain logic of each feature library; the API application's REST surface, GraphQL schema, and state machines; the web and mobile applications; and build/integration notes.

1. Domain Overview#

The table below summarizes the key runtime characteristics of the domain at a glance. All of these properties are derived from the source tree — they are not aspirational targets.

2. Library Inventory#

All 14 libraries live under libs/hestia/. Each declares tags: ["scope:hestia", "layer:domain", "type:lib"], "type": "module", and (except @hestia/core) a peerDependencies entry of @hestia/core: workspace:*.

The table below maps each package to its filesystem path and lists the source modules it contains. Every module has a co-located *.spec.ts test file and each library has its own vitest.config.ts. The flat sibling structure means there are no inter-library dependencies within the feature layer — @hestia/core is the only shared dependency.

3. Core Domain Model (@hestia/core)#

@hestia/core carries the canonical domain types for the whole domain. It has zero runtime dependencies — domain types are plain TypeScript interfaces and enumerations are const objects with derived union types; validation is done by explicit hand-written functions rather than Zod. This design keeps the library suitable for browser and edge environments where Zod's bundle cost would be unacceptable, and it ensures the domain model can be understood without any build-time schema transformation.

Its barrel (src/index.ts) re-exports schemas, db-schema, types, events, and auth. Each of those five modules is described in detail below.

3.1 Enumerations (schemas.ts)#

Each enumeration is a const object plus a derived type and a readonly array of values (e.g. MEASUREMENT_UNITS, COOKING_METHODS). This pattern provides both runtime value access (iterating the array for UI dropdowns) and compile-time exhaustiveness checking in switch statements — with no Zod overhead.

MeasurementUnit — 24 values across four groups:

• US volume: tsp, tbsp, cup, fl_oz, pint, quart, gallon
• Metric volume: ml, liter
• US weight: oz, lb
• Metric weight: gram, kg
• Informal: pinch, dash, piece, whole, clove, sprig, bunch, can, package, slice, to_taste

CookingMethod — 35 values: bake, roast, broil, grill, saute, fry, deep_fry, stir_fry, steam, boil, simmer, poach, braise, stew, smoke, cure, ferment, pickle, dehydrate, sous_vide, pressure_cook, slow_cook, microwave, blanch, caramelize, flambe, reduce, marinate, brine, temper, toast, sear, char, confit, emulsify.

DietaryRestriction — 20 values: vegan, vegetarian, pescatarian, lacto_vegetarian, ovo_vegetarian, kosher, halal, gluten_free, dairy_free, nut_free, soy_free, egg_free, low_sodium, low_carb, keto, paleo, whole30, fodmap, diabetic_friendly, heart_healthy.

Allergen — 14 values aligned with EU + US allergen regulation: milk, eggs, fish, shellfish, tree_nuts, peanuts, wheat, soy, sesame, mustard, celery, lupin, mollusks, sulfites.

MealType — 10 values: breakfast, brunch, lunch, dinner, snack, appetizer, side_dish, dessert, beverage, cocktail.

IngredientCategory — 9 values: produce, dairy, meat, seafood, grain, spice, condiment, baking, other.

Preparation — 24 values describing ingredient cuts/treatments: diced, minced, sliced, chopped, julienned, grated, shredded, crushed, pureed, mashed, peeled, deveined, deboned, halved, quartered, cubed, torn, chiffonade, brunoise, sifted, melted, softened, toasted, blanched, whole.

3.2 Difficulty and cuisine taxonomy#

DifficultyLevel is an interface — level (1 | 2 | 3 | 4 | 5), name, description, criteria (string array). DIFFICULTY_LEVELS ships five calibrated entries: 1 Beginner, 2 Easy, 3 Intermediate, 4 Advanced, 5 Expert, each with five criteria strings (equipment, knife skills, ingredient count, cooking-method count, precision). getDifficultyLevel(level) looks one up.

The cuisine taxonomy is a recursive tree rather than a flat list, reflecting the real-world nesting of culinary traditions. French cuisine contains Provençal and Lyonnaise sub-cuisines; Chinese cuisine contains Cantonese, Sichuan, and many others. This nesting is encoded in the type system and the data at the same time.

CuisineType is { id, name, region, subCuisines? } (recursively nested). CUISINE_TAXONOMY is a fixed tree of named world cuisines grouped by region (Europe, Asia, Middle East, Africa, Americas, Oceania, Global). Top-level cuisines such as italian, french, chinese, japanese, indian, mexican carry nested subCuisines (Tuscan, Sichuan, North Indian, Oaxacan, etc.). flattenCuisines() returns the full flattened list including sub-cuisines; findCuisineById(id) searches the tree.

3.3 Nutrition value objects#

The nutrition types form a hierarchy: a NutritionInfo object carries the main macros (required) plus optional micronutrient groups, each with their own typed interface. This structure maps directly to both USDA FoodData Central data and the FDA/EU nutrition label format.

NutritionInfo — calories (kcal), protein, carbs, fat (grams, required); optional fiber, sugar (g), sodium, cholesterol (mg), saturatedFat, transFat (g), vitamins (VitaminProfile), minerals (MineralProfile).

VitaminProfile — all optional: vitaminA (mcg), vitaminC (mg), vitaminD (mcg), vitaminE (mg), vitaminK (mcg), vitaminB1/B2/B3/B5 (mg), vitaminB6 (mg), vitaminB7 (mcg, biotin), vitaminB9 (mcg, folate), vitaminB12 (mcg).

MineralProfile — all optional: calcium, iron, potassium, magnesium, zinc, phosphorus (all mg).

3.4 Flavor and texture profiles#

Flavor and texture profiles are normalized numeric or boolean objects rather than free-text strings. This normalization is what enables the flavor pairing engine in @hestia/ingredients to compute compatibility scores across ingredients programmatically.

FlavorProfile — six required numeric intensities 0–10: sweet, salty, sour, bitter, umami, spicy; optional booleans aromatic, rich, light; optional descriptors string array.

TextureProfile — 11 optional boolean attributes (crispy, crunchy, tender, chewy, creamy, silky, flaky, crumbly, firm, soft, juicy) plus an optional descriptors string array.

3.5 Ingredient and Recipe entities#

These are the two most important domain objects. Ingredient is the master database entry; RecipeIngredient is how an ingredient appears within a specific recipe (with quantity, unit, and preparation). The decoupling is intentional — a single master ingredient entry can appear across thousands of recipes, each with different quantities and preparations, with only one place to update when nutritional data changes.

Ingredient — id, name, category (IngredientCategory); optional description, shelfLife (e.g. "7 days"), storageMethod, substitutes (string array), allergens (Allergen[]), nutritionPer100g (NutritionInfo).

RecipeIngredient — ingredientId, name, quantity (number), unit (MeasurementUnit), optional (boolean, required); optional preparation (Preparation | string), substituteNote.

Instruction — step (positive integer), text; optional duration (minutes), method (CookingMethod), temperature (number), temperatureUnit ('F' | 'C'), tips (string array).

Recipe — the canonical recipe object. All fields with constraints listed below:

3.6 Validation functions#

schemas.ts exposes a complete set of validation functions — one per type that can arrive from user input or external sources. Each returns a ValidationResult ({ valid, errors }, where each ValidationError is { field, message, value? }). validateRecipe is the most comprehensive: it recursively validates every nested ingredient, instruction, nutrition, flavor, and texture object.

The full validator set: validateMeasurementUnit, validateCookingMethod, validateDietaryRestriction, validateAllergen, validateMealType, validateIngredientCategory, validateFlavorIntensity (0–10), validateDifficulty (integer 1–5), validateNutritionInfo (non-negative numerics), validateFlavorProfile, validateTextureProfile, validateIngredient, validateRecipeIngredient, validateInstruction, and validateRecipe.

3.7 Unit, temperature, equipment, and user types (types.ts)#

types.ts provides the measurement conversion system, temperature utilities, equipment catalog, and user/household model that are used across all feature libraries.

Measurement conversion. ML_PER (volume anchored on ml) and GRAM_PER (weight anchored on grams) drive conversions. VOLUME_UNITS, WEIGHT_UNITS, and INFORMAL_UNITS are Sets; areUnitsConvertible(from, to) and getUnitCategory(unit) classify a unit. buildVolumeConversionTable() and buildWeightConversionTable() produce all ConversionFactor ({ from, to, factor }) pairs. convert(amount, from, to) returns a ConversionResult ({ success, value?, from, to, error? }); cross-category, informal, and unknown-unit conversions fail with an explanatory error. The UnitConverter class wraps convert and adds convertWithDensity(amount, from, to, gramsPerMl) for volume↔weight conversion, plus getSupportedUnits().

Temperature. TemperatureUnit is 'F' | 'C' | 'K'. Pairwise converters (fahrenheitToCelsius, celsiusToFahrenheit, celsiusToKelvin, kelvinToCelsius, fahrenheitToKelvin, kelvinToFahrenheit) plus convertTemperature(value, from, to) returning a TemperatureResult. OVEN_TEMPERATURES lists 11 reference oven settings (name, fahrenheit, celsius, gas mark) from Very Cool (250 °F) to Extremely Hot (500 °F).

Equipment. EquipmentCategory is 'cookware' | 'bakeware' | 'appliance' | 'utensil' | 'cutlery'. CookingEquipment is { id, name, category, essential, alternativeEquipment, description?, careInstructions? }. ESSENTIAL_EQUIPMENT ships 18 standard items (chef's knife, cutting board, skillet, saucepan, stock pot, sheet pan, mixing bowls, wooden spoon, spatula, measuring cups/spoons, colander, tongs, whisk, can opener, paring knife, oven, stovetop). validateEquipment(eq) checks structure.

User and household. SkillLevel is 'beginner' | 'easy' | 'intermediate' | 'advanced' | 'expert' (SKILL_LEVELS array). UserProfile carries id, name, email, dietaryRestrictions, allergens, skillLevel, householdSize, favoriteCuisines, dislikedIngredients, kitchenEquipment, and optional timestamps. HouseholdMember is { userId, name, role, joinedAt } where role is 'owner' | 'admin' | 'member'. Household is { id, name, members, sharedPantry, sharedMealPlan, sharedShoppingList, createdAt?, updatedAt? }. validateUserProfile and validateHousehold enforce structure; a household must have at least one member and at least one owner.

4. Database Schema (@hestia/core/db-schema.ts)#

@hestia/core exports Drizzle ORM PostgreSQL definitions: 20 tables and 10 pgEnum enum types, all prefixed hestia_. The prefix prevents name collisions with tables from other Oshun domains that share the same PostgreSQL instance. Tables, enums, and Drizzle relations are all exported; ALL_TABLES and ALL_ENUMS constants enumerate them for introspection and test setup.

4.1 Enum types#

PostgreSQL pgEnum types mirror the TypeScript enumerations in schemas.ts. The following table lists the ten enum types and their allowed values.

4.2 Tables#

All tables use a uuid primary key with defaultRandom() and timezone-aware timestamps. The 20 tables, with their key columns and indexes, are:

1. hestia_recipes — title, slug (unique index), description, servings, prepTime, cookTime, totalTime, difficulty, cuisine, mealType, status, visibility, authorId, version, isPublic, dietaryTags/allergens/photos (JSONB string arrays), flavorProfile/ textureProfile (JSONB), sourceUrl. Indexed on slug, author, cuisine, meal type, status, created-at.
2. hestia_ingredients — name (unique index), category, description, shelfLife, storageMethod, substitutes/allergens (JSONB). Indexed on name and category.
3. hestia_recipe_ingredients (junction) — recipeId (FK → recipes, cascade), ingredientId (FK → ingredients, restrict), name, quantity (decimal(10,3)), unit, preparation, optional, substituteNote, sortOrder.
4. hestia_nutritional_data — optional ingredientId / recipeId FKs; calories/protein/carbs/fat (real, default 0); optional fiber, sugar, sodium, cholesterol, saturatedFat, transFat; vitamins/ minerals (JSONB); servingSize, servingUnit.
5. hestia_flavor_compounds — name (unique index), casNumber, category, description, flavorNotes/foundIn (JSONB string arrays), threshold (real).
6. hestia_ingredient_pairings — ingredientAId/ingredientBId (FKs → ingredients, cascade; pair unique index), compatibilityScore (real), sharedCompounds (integer), notes.
7. hestia_user_preferences — userId (unique index), skillLevel (difficulty enum), householdSize, favoriteCuisines/dislikedIngredients/ preferredMealTypes/cookingEquipment (JSONB string arrays), maxPrepTime, maxCookTime.
8. hestia_dietary_restrictions — userId, restriction, severity (default strict), notes; unique on (userId, restriction).
9. hestia_allergen_profiles — userId, allergen, severity (default severe), reaction, diagnosedDate; unique on (userId, allergen).
10. hestia_meal_plans — userId, name, startDate, endDate, meals (JSONB array of { date, mealType, recipeId, servings }), notes.
11. hestia_pantry_inventory — userId, ingredientId (FK → ingredients, cascade), quantity (decimal(10,3)), unit, status (inventory enum), purchaseDate, expirationDate, location, notes. Indexed on user, ingredient, status, expiration.
12. hestia_shopping_lists — userId, name, items (JSONB array of { ingredientId, name, quantity, unit, status, category }), mealPlanId (FK → meal plans, set null), completed.
13. hestia_equipment_registry — name (unique index), category (equipment enum), description, essential, alternativeEquipment (JSONB), brand, careInstructions.
14. hestia_cooking_sessions — userId, recipeId (FK → recipes, cascade), status (session enum), startedAt, completedAt, currentStep, notes, servingsCooked, rating (real), feedback, photosUrls (JSONB).
15. hestia_recipe_versions — recipeId (FK → recipes, cascade), version, title, description, changes, snapshot (JSONB, not null), authorId; unique on (recipeId, version).
16. hestia_recipe_ratings — recipeId (FK → recipes, cascade), userId, rating (real), review, wouldMakeAgain, difficultyFeedback (difficulty enum); unique on (recipeId, userId).
17. hestia_recipe_comments — recipeId (FK → recipes, cascade), userId, parentId (self-reference for threads), content, likes, edited.
18. hestia_recipe_collections — userId, name, description, visibility (visibility enum), coverImage, recipeIds (JSONB), followerCount, tags (JSONB).
19. hestia_cooking_techniques — name (unique index), type (technique enum), description, difficulty (difficulty enum), requiredEquipment/ tips/relatedTechniques (JSONB), videoUrl.
20. hestia_cuisines — code (unique index), name, region, parentId (self-reference), description, keyIngredients/keyTechniques (JSONB), flavorProfile (JSONB).

4.3 Relations#

Drizzle relations() declarations enable type-safe eager loading across table boundaries. The relations declared are:

• Recipes resolve their ingredients, versions, ratings, comments, sessions, and nutritionalData.
• Ingredients resolve recipeIngredients, nutritionalData, pantryItems, and both directions of ingredientPairings (relation names ingredientA / ingredientB).
• Meal plans resolve shoppingLists.

5. Domain Events (@hestia/core/events.ts)#

@hestia/core ships a complete in-process event-sourcing toolkit — not just event type constants, but a full infrastructure for building, storing, subscribing to, and projecting domain events. This enables decoupled communication between modules (e.g., the social module reacting to a recipe being rated without directly calling the recipes module) and provides an audit trail of all significant actions in the domain.

5.1 Event envelope#

Every domain event is wrapped in a DomainEvent<T> envelope: id, type, timestamp (Date), aggregateId, aggregateType, payload: T, version (number), optional metadata. The factory createEvent(type, aggregateId, aggregateType, payload, version=1, metadata?) builds one; generateEventId() returns evt-NNNNNN and resetEventIdCounter() resets the counter for test isolation.

5.2 Event types and payloads#

EventTypes defines 10 event name constants. Each event has a typed payload interface and a DomainEvent<...> alias. The following table lists all ten:

5.3 Event infrastructure#

The event infrastructure beyond the envelope itself provides an append-only store, a synchronous pub/sub bus, projection utilities for building read models, and a version migration chain for evolving payloads forward.

• EventStore — in-memory append-only store: append, appendBatch, getByAggregateId, getByType, getByAggregateType, getAfter(timestamp), getAll, count, replay(handler), replayAggregate, clear.
• EventBus — synchronous pub/sub: subscribe(type, handler) and subscribeAll(handler) (each returns an unsubscribe function), publish, unsubscribe, clearHandlers, clearAll, handlerCount.
• projectEvents(initialState, events, reducer) and the EventProjection class (apply, applyBatch, getState, getProcessedCount, reset) build read models from event streams.
• Event versioning — EventUpcaster (eventType, fromVersion, toVersion, upcast) and the UpcasterChain class (register, upcast, upcastBatch) migrate old event versions forward (100-iteration safety cap).
• generateNotification(event, recipientId) maps an event to a DomainNotification (id, type, title, message, recipientId, sourceEventId, createdAt, read); it has a template for every event type and returns null for unrecognised types.

6. Authorization Model (@hestia/core/auth.ts)#

auth.ts defines a complete recipe/collection authorization model used by both the API and the libraries. The design centralizes all access rules in @hestia/core so that the same permissions logic applies whether a request comes through REST, GraphQL, or a direct library call.

The authorization system has three layers: visibility determines who can see a recipe at all; roles determine what a user can do once they can see it; and API key scopes gate programmatic access by capability rather than by user identity.

• RecipeVisibility — private, household, public (VISIBILITY_LEVELS).
• Role — owner, admin, contributor, viewer (ROLES), ordered by a numeric ROLE_HIERARCHY (viewer 0 → owner 3). hasEqualOrHigherRole compares two roles.
• Action — view, edit, delete, share, rate, comment, cook, fork (ACTIONS). A PERMISSION_MATRIX maps each role to its allowed actions: owner has all 8; admin has all except delete; contributor has view/edit/rate/comment/cook/fork; viewer has view/rate/comment/cook/fork. roleHasPermission(role, action) and getPermissionsForRole(role) query it.
• RecipeOwnership (recipeId, creatorId, contributors[], visibility, householdId?) plus HouseholdMembership (householdId, memberIds[], adminIds[]) feed getUserRole(userId, ownership, householdMembership?) — creator → owner, listed contributor → contributor, household admin → admin, household member → viewer, public → viewer. checkPermission(userId, ownership, action, householdMembership?) first enforces visibility, then the permission matrix, returning a PermissionCheckResult (allowed, reason, role).
• Household sharing — HouseholdSharingConfig (sharedRecipes, sharedMealPlans, sharedShoppingLists, sharedPantry); isSharedInHousehold and canAccessHouseholdResource gate the four resource types.
• Collection permissions — CollectionVisibility (private, public); CollectionPermissions (collectionId, ownerId, visibility, followers[], collaborators[]); canViewCollection, canEditCollection, canDeleteCollection, isFollowingCollection.
• API key scopes — APIKeyScope has 7 values: recipe_read, recipe_write, meal_plan, pantry, shopping_list, user_profile, admin (API_KEY_SCOPES). APIKey is { id, userId, name, scopes[], createdAt, expiresAt?, lastUsedAt?, active }. apiKeyHasScope (admin scope grants all; expired/inactive keys deny), apiKeyHasAllScopes, validateAPIKey, and getScopesForAction(resourceType, action) complete the model.

7. Feature Library Domain Logic#

The 13 feature libraries are pure-domain TypeScript with extensive built-in reference data. Each library follows the same pattern: types and interfaces for its domain objects, factory functions and classes implementing the domain logic, and seed data so the system is functional out of the box. The subsections below summarize the types and entry points that consumers depend on, grounded in each library's src/*.ts exports.

7.1 @hestia/recipes — recipe management#

This library covers the full lifecycle of a recipe: creation and validation, parsing from external formats, scaling to different serving sizes, version history, and collection management. The recipe-model.ts module is the entry point for creating and computing on recipes; the other modules add import/export, scaling, versioning, and search on top.

• recipe-model.ts — createRecipe(params) factory and the fluent RecipeBuilder; computeDifficulty(recipe) scores 1–5 from ingredient count, instruction count, technique complexity (ADVANCED_TECHNIQUES / INTERMEDIATE_TECHNIQUES sets), total time, and method count; estimateCost(recipe, priceMap) returns { totalCost, perServing, missingPrices }; detectAllergens(recipe, ingredientDb) uses the database then a keyword heuristic table; checkDietaryCompliance(recipe, restriction, ingredientDb?) checks excluded categories/allergens/keyword lists; RecipePhotoGallery (cover photo, reorder); computeTimings(recipe) splits prep/cook/rest from instructions; RecipeEquipment (required vs optional, checkAvailability).
• parsing.ts — natural-language recipe parsing: parseQuantity (ParsedQuantity), normalizeUnit, parsePreparation, parseIngredientLine (ParsedIngredient), extractTimeFromText (ExtractedTime[]), extractTemperature (ExtractedTemperature[]), extractEquipment, extractTechnique, detectVisualCue, detectDonenessCue, parseInstructionStep (ParsedInstruction).
• import-export.ts — ImportFormat is 'jsonld' | 'markdown' | 'plaintext' | 'schemaorg'; ExportFormat is 'jsonld' | 'markdown' | 'plaintext'. importJsonLd/exportJsonLd (Schema.org JsonLdRecipe), importSchemaOrg(html), importMarkdown/exportMarkdown, importPlainText/exportPlainText; classes RecipeImporter (with ImportProgress) and RecipeExporter; generateRecipeCard(recipe) → RecipeCard; compileCookbook(recipes, metadata) → Cookbook of CookbookChapters.
• scaling.ts — typed per-ingredient scaling rules (ScalingRule): linearScale, spiceScale, leaveningScale, yeastScale, eggScale, gelatinScale, sauceReductionScale; adjustCookingTime, adjustTemperature, adjustPanSize (PanSize); detectMinimumBatch and detectMaximumBatch (BatchLimits); BUILT_IN_SCALING_RULES; the top-level scaleRecipe(...).
• versioning.ts — Git-like recipe history: RecipeVersion, FieldChange (FieldChangeType = added/removed/modified), RecipeDiff; diffRecipes(a, b); the RecipeHistory class; three-way merge via mergeRecipes(base, theirs, mine) returning MergeResult with MergeConflicts; forkRecipe (ForkInfo); RecipeLineage (LineageNode); generateChangelog(history) → ChangelogEntry[].
• search.ts — SearchFilters, SearchResult, NutritionConstraints; buildSearchTokens, calculateSimilarity(a, b), seasonalRecipes(recipes, month), personalizeResults (UserSearchProfile), and the RecipeIndex full-text index class.
• collections.ts — CollectionManager, SmartCollection (SmartCollectionRule / SmartCollectionConfig), TagManager (Tag), FolderOrganizer (Folder), RecentlyCooked (CookingRecord), FavoritesManager (FavoriteEntry).

7.2 @hestia/cooking — guided cooking#

This library drives the active cooking experience. The GuidedCookingSession class is the central stateful object — it holds the current step, tracks paused time, and computes percentage progress. The TimerManager, VoiceSession, and DonenessLibrary classes handle the supporting concerns that make a cooking session workable without a free hand.

• guided-cooking.ts — CookingStep (stepNumber, text, ingredients, equipment, technique?, duration?, temperature?, tips?, completed), GuidedCookingState, RecipeInput; the StepParser class extracts equipment/technique/timing/temperature from instruction text; the GuidedCookingSession class drives a session — start(recipe), getCurrentStep, getProgress (0–100 % from completed steps), step navigation, and pause/resume tracking (paused, pausedAt, totalPausedMs).
• timers.ts — TimerState (idle/running/paused/completed), TimerAlert (none/sound/vibrate/both), CookingTimer (with optional cascadeTimerId for chained timers), TimerPreset, TimerHistoryEntry; the TimerManager, TimerPresets, and TimerHistory classes.
• voice.ts — VoiceCommandType union, VoiceCommand, SupportedLanguage (en/es/fr/de/it/ja/zh/ko); the VoiceCommandParser, TextToSpeechFormatter, VoiceSession, and MultiLanguageSupport classes.
• doneness.ts — DonenessLevel (name, description, internalTemp? with min/max + unit, visualCues, touchTest?, timeGuide?), DonenessCategory (meat/bread/egg/vegetable/sauce/caramel/ dough/emulsion), DonenessGuide; the DonenessLibrary class with built-in USDA-referenced doneness guides (e.g. beef-steak rare → well-done).
• techniques.ts — TechniqueGuide, TechniqueProgress, Achievement; the TechniqueLibrary and TechniqueTracker classes.
• session-log.ts — SessionStatus (in_progress/completed/ abandoned), CookingSession, SessionStep, SubstitutionLog; the SessionLogger and SessionAnalytics classes.

7.3 @hestia/ingredients — ingredient intelligence#

The ingredient library is the scientific foundation of the platform. Its most distinctive modules are flavor-compounds.ts and pairing.ts, which implement the volatile compound overlap analysis that powers Hestia's non-obvious pairing suggestions. The seasonality.ts module ties sourcing data to geographic region and calendar month, enabling the meal planning layer to prioritize in-season recommendations.

• master-database.ts — IngredientDatabase, IngredientHierarchy (CategoryNode), AliasManager, StorageGuide (StorageInfo), SelectionGuide (SelectionCriteria), WasteCalculator; SEED_INGREDIENTS seed data.
• flavor-compounds.ts — CompoundCategory (volatile/taste/aroma), FlavorCompound, CompoundProfile, CompoundInteraction, MaillardProduct, FermentationProduct, SynergyPair; the FlavorCompoundDB class plus SEED_COMPOUNDS and SEED_COMPOUND_PROFILES.
• pairing.ts — PairingBasis (compound/tradition/novel), PairingScore, TraditionalPairing, BeverageSuggestion, IngredientColor; the PairingEngine class plus SEED_TRADITIONAL_PAIRINGS.
• substitution.ts — Substitution, MultiIngredientSubstitution, EmergencySubstitutionResult; the SubstitutionEngine class.
• nutrition.ts — detailed NutrientProfile with AminoAcidProfile, FattyAcidProfile, FiberDetail, and FodmapCategory / HistamineLevel / OxalateLevel / PurineLevel classifications; the NutrientDatabase class plus SEED_NUTRIENT_PROFILES.
• seasonality.ts — SeasonalQuality (peak/good/fair), SeasonalData, FarmersMarket, CSABox, SustainabilityScore, CertificationInfo, FairTradeInfo, ForagingEntry; the SeasonalityDB and SourcingTracker classes.

7.4 @hestia/nutrition — nutritional analysis#

This library goes beyond label math. The key differentiator is bioavailability.ts, which models the difference between what a food contains on paper and what the body actually absorbs — accounting for nutrient interactions, cooking method effects, and individual physiology. The medical-diet.ts module covers eight clinically-named diet plans, and goals.ts handles BMR/TDEE calculation and life-stage-specific nutrition targets.

• analysis.ts — calculateRecipeNutrition, perServingBreakdown, dailyValuePercent (against the FDA_DAILY_VALUES constant), generateFDALabel (FDALabelData) and generateEULabel (EULabelData), nutrientDensityScore; the DailyIntakeTracker and NutritionReportGenerator classes (MealEntry, DailyTotals, NutritionGoals, DayRecord, PeriodReport, TrendPoint).
• bioavailability.ts — ABSORPTION_FACTORS table; cookingImpact, nutrientInteraction, ironAbsorptionOptimizer, calciumAbsorptionFactors, vitaminCEnhancement, fatSolubleVitaminPairing, phytateOxalateImpact, personalizedBioavailability (PersonalFactors) — all returning typed absorption-score results.
• dietary.ts — DietaryProfile, DietRule, ComplianceResult; predicate functions isVegetarian, isVegan, isPescatarian, isKosher, isHalal, isHinduCompliant, isJainCompliant, isBuddhistVegetarian, isRawFood, isPaleo, isKeto, isWhole30, isDASH, isMediterranean; checkCompliance, createCustomDiet, filterRecipes.
• allergen.ts — AllergenEntry, AllergenProfile, AllergenDetectionResult, SubstitutionSuggestion, AllergenCardData, ConflictInfo; the AllergenDetector, AllergenFilter, and AllergenMatrix classes; generateAllergenCard(...).
• medical-diet.ts — MedicalDietPlan and eight built-in plans (DIABETIC_PLAN, RENAL_PLAN, CARDIAC_PLAN, GERD_PLAN, IBS_PLAN, CELIAC_PLAN, GOUT_PLAN, PKU_PLAN, indexed by MEDICAL_DIET_PLANS); the CarbCounter class (CarbEntry, InsulinEstimate); IDDSI dysphagia levels (IDDSILevel, DysphagiaLevels, getIDDSILevel); the MedicationInteractionChecker; checkMedicalDietCompliance.
• goals.ts — NutritionGoal, ActivityLevel, UserPhysicalProfile; the GoalCalculator (BMR/TDEE/macro-ratio/weight-goal), GoalTracker, IntermittentFastingTracker, and SupplementRecommender classes; life-stage goal presets (PREGNANCY_GOALS, BREASTFEEDING_GOALS, PEDIATRIC_GOALS(age), SENIOR_GOALS, ATHLETE_GOALS, MUSCLE_BUILDING_GOALS).

7.5 @hestia/smart-kitchen — IoT orchestration#

The smart kitchen library abstracts over the fragmented kitchen device ecosystem. Rather than integrating brand by brand, it defines capability-based adapter interfaces — OvenAdapter, SousVideAdapter, ThermometerAdapter, etc. — that any device can implement. The WorkflowEngine and CookingOrchestrator classes sit on top of these adapters, enabling event-driven automation and multi-device coordination.

• devices.ts — DeviceCapability / DeviceType unions, DeviceStatus (online/offline/error/updating), SmartDevice, DeviceCommand, CommandStatus (queued/sent/acknowledged/completed/failed), FirmwareUpdateInfo; the DeviceRegistry class.
• cooking-devices.ts — adapter interfaces + mock adapters + controllers for smart ovens (OvenAdapter/MockOvenAdapter/SmartOvenController, OvenCookingMode, OvenCookingProgram), sous-vide (SousVideAdapter/SousVideController, MultiBagSchedule), and pressure cookers (PressureCookerAdapter/PressureCookerController, PressureLevel, PressureCookingProgram, PressureReleaseType).
• sensors.ts — ThermometerAdapter/MockThermometerAdapter and the TemperatureMonitor (DonenessPrediction); ScaleAdapter/MockScaleAdapter and the SmartScaleController (BakersPercentResult, NutritionEstimate).
• smart-appliances.ts — RefrigeratorAdapter + SmartFridgeController (FridgeZone, ExpirationAlert, RecipeSuggestion); CoffeeMachineAdapter
  • CoffeeController (CoffeeType, GrindLevel); CooktopAdapter + CooktopController (SafetyCheckResult).
• automation.ts — TriggerType / ActionType (send_command/notify/start_timer/log/chain_workflow) unions; Workflow, WorkflowTrigger, WorkflowAction, WorkflowStep; the WorkflowEngine class with WorkflowExecutionResult and WorkflowDebugResult debug logging; WorkflowTemplates; SmartHomeIntegration for SmartHomePlatform ecosystems.
• orchestration.ts — multi-device meal coordination: ExecutionPlan / ExecutionPlanStep, CookingProgress, TimelineEntry; the CookingOrchestrator, DeviceScheduler (ScheduleConflict), and KitchenDashboard (DeviceOverview, ActiveOperation, DashboardAlert, EnergyUsage) classes.

7.6 @hestia/meal-planning — meal planning#

Meal planning connects the pantry (what you have), the budget (what you can spend), the household (who you are cooking for), and the calendar (when you are cooking). The suggestions.ts module is where these concerns meet — it uses NutritionBalancer, IngredientOptimizer, and VarietyTracker together to produce meal suggestions that are simultaneously nutritious, budget-conscious, waste-reducing, and varied.

• calendar.ts — MealSlot, RecurringMeal, SpecialOccasion, MealPrepSession; the MealCalendar and WeeklyView classes.
• household.ts — HouseholdMember, GuestInfo, DietaryException, ComponentMealPlan, KidFriendlyCriteria; the Household, ComponentMealPlanner, DietaryExceptionHandler, and KidFriendlyFilter classes.
• suggestions.ts — MealRecord, VarietyScoreResult, NutritionAnalysis, NutritionGap, LeftoverPlan, WasteAnalysis; the VarietyTracker, NutritionBalancer, IngredientOptimizer, and ContextualSuggester classes.
• budget.ts — FoodBudget, MealCostEstimate, SpendingRecord, BudgetComparison, Coupon, BulkBuyOpportunity; the BudgetManager, BulkBuyOptimizer, CouponManager, and BudgetSubstituter classes.
• batch-cooking.ts — PrepTask, PrepSession, FreezerMeal, ThawEntry, BatchSauce, MarinadeSchedule; the BatchCookingPlanner, FreezerMealPlanner, and ComponentPrepPlanner classes.
• events.ts — EventCourse, EventMeal, BuffetPlan, PotluckPlan, CocktailPartyPlan, HolidayTemplate, GuestDietarySummary; the EventPlanner, HolidayTemplates, and EquipmentRentalAdviser classes.

7.7 @hestia/pantry — pantry and inventory#

The pantry library manages physical food inventory from purchase through consumption or disposal. A notable feature is grocery-store.ts, which ships concrete adapters for Kroger, Target/Shipt, Whole Foods, and a generic fallback, enabling one-click ordering directly from the shopping list. The equipment.ts module tracks kitchen tools and maintenance schedules, feeding the feasibility checker in @hestia/recipes.

• inventory.ts — PantryLocation (pantry/fridge/freezer/counter/ spice_rack, PANTRY_LOCATIONS array), PantryItem; the PantryInventory and BrandPreference (BrandRating) classes.
• scanning.ts — BarcodeType (UPC-A/UPC-E/EAN-13/EAN-8/QR), BarcodeResult, ProductInfo, ReceiptItem, ReceiptResult, ScanSession; calculateUPCCheckDigit, calculateEANCheckDigit, detectBarcodeType, validateBarcode; the ProductDatabase, ReceiptParser, ManualEntryHelper, and BulkScanner classes.
• expiration.ts — AlertLevel (info/warning/urgent/expired), WasteReason (expired/spoiled/excess/damaged), ExpirationAlert, WasteEntry/WasteReport, FreezingSuggestion, DonationSuggestion, CompostSuggestion; the ExpirationManager, FIFOAdvisor, and WasteTracker classes.
• shopping.ts — ShoppingItem, AisleDefinition, StoreLayoutConfig, RecurringItem (RecurringFrequency = weekly/biweekly/monthly), SharedListInfo; the ShoppingList, ShoppingListGenerator, StoreLayout, SharedList, and RecurringItems classes.
• grocery-store.ts — GroceryStoreAdapter interface + BaseStoreAdapter abstract class, with concrete adapters KrogerAdapter, TargetShiptAdapter, WholeFoodsAdapter, GenericStoreAdapter; Order/OrderStatus, CartItem/CartSummary, PriceComparison; the PriceComparator / EnhancedPriceComparator, OrderManager, OneClickOrderService, and DeliveryScheduler classes.
• equipment.ts — EquipmentCategoryType union, EquipmentEntry, MaintenanceTask/MaintenanceLog, UsageAnalysis, UpgradeRecommendation; the EquipmentRegistry, EquipmentMatcher, MaintenanceScheduler, and EquipmentRecommender classes.

7.8 @hestia/heritage — culinary heritage#

The heritage library digitizes and preserves culinary cultural memory. Its scope is unusually broad: OCR-driven handwritten recipe capture, audio/video oral history recording with transcription, a geographic archive of regional cuisines, food history research with trade route data, and a full community moderation workflow for community-submitted content. The community.ts module is particularly detailed, covering expert verification, translation volunteers, and reward catalogues for contributors.

• family-recipes.ts — OCR-driven family-recipe digitisation: ScanSettings, OCRConfig/OCRResult/OCRBlock, RecipeStory, RecipePhoto/PhotoAlbum, AudioRecording/VideoRecording, FamilyMember/ FamilyTree, Occasion (OccasionType), LegacyPreservationConfig (PreservationFormat), FamilyRecipeRecord; built-in OCR_CONFIGS, COMMON_OCCASIONS, PRESERVATION_PRESETS, and sample family data.
• oral-history.ts — AudioConfig/AudioSession, TranscriptionConfig/ TranscriptionResult/TranscriptionSegment (TranscriptionEngine), VideoInterview, InterviewGuide/InterviewQuestion (QuestionCategory), Timeline/TimelineEvent, RecipeOriginMap/GeoLocation, MigrationStory, LanguageGlossary/CulinaryTerm, SharingConfig (SharingPermission).
• regional-archive.ts — RegionalCuisineRecord (CuisineRegionType), GeoRecipePin, HistoricalRecipe (HistoricalEra), TraditionalTechnique, IndigenousIngredient, SeasonalTradition, FestivalFood, ReligiousFoodPractice (ReligiousTradition), StreetFoodItem, EndangeredRecipe (EndangermentLevel); extensive seed databases plus region/era/city query helpers.
• food-history.ts — HistoricalCookbook, RecipeEvolution, IngredientHistoryEntry, CookingTechnology, TradeRoute, ColonialFoodImpact, ImmigrationFoodStory, FoodEtymology, HistoricalMenu, ResearchTopic (ResearchMethodology); large reference datasets with country/era/word query helpers.
• community.ts — SubmissionType/SubmissionStatus, CommunitySubmission, ReviewWorkflow/ReviewStage, Attribution/CreditPolicy, CommunityVote (VoteType)/VotingConfig, ExpertBadge/ExpertVerifier, CulturalConsultant, TranslationRequest/ TranslationVolunteer, Moderator (ModeratorRole), Reward/RewardTier (RewardType), PartnerOrganization; preset workflows, policies, badges, and reward catalogues.

7.9 @hestia/sustainability — sustainability#

This library makes environmental impact measurable and actionable. It is organized around five interconnected concerns: carbon calculation, waste tracking, ethical sourcing scoring, seasonal/local sourcing, and composting guidance. Each module has substantial built-in reference data — the carbon database, transport emission factors, seafood sustainability ratings, and a Dirty Dozen/Clean Fifteen produce list are all embedded.

• carbon-footprint.ts — enums FoodCategory, TransportMode, SourcingDistance, PackagingMaterial, CookingMethodCarbon, WasteDisposalMethod, EnergySource, TimePeriod, OffsetCategory; IngredientCarbonEntry / RecipeCarbonResult, CarbonRating (A–F), CarbonBudget / CarbonBudgetProgress, CarbonOffsetProvider; the INGREDIENT_CARBON_DATABASE, TRANSPORT_EMISSION_FACTORS, COOKING_EMISSION_FACTORS, CARBON_OFFSET_PROVIDERS datasets; calculateRecipeCarbon, calculateTransportCarbon, calculateCookingCarbon, calculateFoodWasteCarbon, calculateDailyCarbon / calculateWeeklyCarbon, generateCarbonReductionSuggestions, compareCookingMethods, findLowerCarbonSubstitutes, estimateAnnualFootprint.
• food-waste.ts — enums WasteCategory, WasteReason, StorageLocation, WasteSeverity, WasteUnit, FoodGroup, AgeGroup, ActivityLevel, AnalyticsPeriod, ContainerType; WasteEvent, WasteReductionGoal / GoalProgress, UseItUpSuggestion, PortionRecommendation, RootToStemRecipe, NoseToTailRecipe, WasteDashboard; constants CO2_PER_KG_WASTE, WATER_LITERS_PER_KG_WASTE; classifyWasteSeverity, createWasteEvent, calculateGoalProgress, estimatePotentialSavings, prioritizeByExpiration, computePeriodAnalytics, buildWasteDashboard, computeEnvironmentalImpact.
• ethical-sourcing.ts — enums SeafoodRating, StockStatus, ImpactLevel, BycatchLevel, WelfareTier, TrustLevel, PalmOilSupplyChain, DeforestationRisk, HealthRisk, PesticideRanking, LaborProductCategory; SeafoodEntry, FishingMethod, WelfareRating, FarmCertification, FairTradeProgram, LaborPracticeInfo, PalmOilEntry, WaterFootprint, PesticideData, EthicalSourcingScore; seed databases plus lookupSeafood, getCertificationsForProduct, getDirtyDozen / getCleanFifteen, calculateEthicalSourcingScore, evaluateRecipeDeforestationRisk, calculateRecipeWaterFootprint.
• seasonal-local.ts — enums including USRegion, Month, ProduceCategory, FarmingPractice, CSAShareType, FoodTransportMode, PreservationMethod, BadgeTier; SeasonalIngredient, LocalFarm, FarmersMarket, CSAProgram, FoodMileResult, SeasonalRecipe, PreservationTechnique, LocalFoodChallenge, AchievementBadge; databases and getInSeasonIngredients, findFarmersMarkets, calculateFoodMiles, compareLocalVsImported, suggestLocalSubstitutions, generateMonthlyGuide.
• composting.ts — enums including CompostBinType, CompostabilityRating, CompostMaterialType, RecyclingMaterial, WormSpecies, BokashiPhase, MunicipalProgramType, ZeroWasteTipCategory; CompostBinGuide, CompostabilityItem, CompostProblem, VermicompostingGuide, MunicipalCompostingProgram, ZeroWasteTip; databases plus diagnoseCompostProblem, calculateCompostMixRatio (carbon:nitrogen), recommendCompostingMethod, getWasteDisposalRecommendation.

7.10 @hestia/education — culinary education#

The education library provides structured culinary learning from beginner techniques through food science to professional certifications. The progression system uses XP points and skill trees to sequence learning logically. The interactive.ts module is the most forward-looking, covering AR technique overlays, virtual kitchen simulations, spaced-repetition flashcards, and an expert critique marketplace.

• techniques.ts — TechniqueCategory union; Technique and the specialised KnifeSkill, HeatTechnique, BakingTechnique, SauceTechnique interfaces; built-in curricula KNIFE_SKILLS_CURRICULUM, HEAT_TECHNIQUES_CURRICULUM, BAKING_FUNDAMENTALS, SAUCE_MASTERS, FERMENTATION_TECHNIQUES, PRESERVATION_TECHNIQUES; getPrerequisiteChain, suggestNextTechnique.
• progression.ts — SkillLevel (novice/apprentice/journeyman/ expert/master), Badge, Challenge/ChallengeCriterion, SkillTree/ SkillNode, LearnerProfile, Assessment, LearningPath; XP math (calculateLevel, xpToNextLevel, getLevelProgress, awardXp); ALL_BADGES; buildSkillTree, evaluateChallenge, four built-in paths (BEGINNER_PATH, INTERMEDIATE_PATH, ADVANCED_PATH, PROFESSIONAL_PATH).
• food-science.ts — ScienceTopic union, ScienceLesson (with LessonSection, Experiment, FoodScienceQuestion, Diagram, TemperatureDataPoint); 15 built-in courses including MAILLARD_REACTION_COURSE, CARAMELIZATION_COURSE, PROTEIN_DENATURATION_COURSE, EMULSION_SCIENCE_COURSE, FERMENTATION_BIOLOGY_COURSE, STARCH_GELATINIZATION_COURSE; generateQuiz.
• cuisine.ts — CuisineRegion union, CuisineModule (KeyIngredient, SignatureDish, FlavorProfile); 20 built-in cuisine modules (FRENCH_CUISINE, ITALIAN_CUISINE, JAPANESE_CUISINE, INDIAN_CUISINE, etc.); getSimilarCuisines, getByFlavorProfile.
• certifications.ts — CertificationCategory / CertificationLevel (entry/intermediate/advanced/expert), CertificationProgram (ExamSection, PracticeQuestion, StudyPlan); built-in programs FOOD_HANDLER_CERT, SERVSAFE_CERT, HACCP_CERT, SOMMELIER_CERT, CICERONE_CERT, BARISTA_CERT, CHEESE_PROFESSIONAL_CERT, NUTRITION_CERT, PERSONAL_CHEF_CERT, CULINARY_COMPETITION_PREP; generatePracticeExam.
• interactive.ts — VideoLesson, RecipeWalkthrough (WalkthroughStep, WalkthroughStepType), ARTechniqueOverlay (AROverlayType, ARMarker), VirtualKitchenConfig (KitchenStationType, SimulationScenario), QuizConfig (QuizQuestion, AssessmentResult), SpacedRepetitionDeck (FlashCard, ReviewSchedule with calculateNextReview), PracticeAssignment (GradingRubric), ExpertCritiqueMarketplace (ExpertProfile, CritiqueRequest); built-in VIDEO_LESSONS, RECIPE_WALKTHROUGHS, AR_OVERLAYS, VIRTUAL_KITCHENS, QUIZ_BANK.

7.11 @hestia/professional — professional kitchen tools#

Each module in this library exports an extensive prefixed type set and a flat function API backed by in-memory stores (with reset*Stores() and load*SampleData() helpers for test isolation). The prefixed naming convention (MC*, KW*, INV*, FS*, CT*, RD*) prevents type name collisions across what is otherwise a very large surface area covering six distinct professional domains.

• menu-costing.ts — MCIngredientCost, MCRecipeCost, MCFoodCostMetrics, MCPricingSuggestion, MCProfitAnalysis, MCCostTrend, MCLaborCost, MCMenuItem (MCMenuCategory = star/plow-horse/puzzle/dog), MCMenuEngineeringReport; calculateRecipeCost, calculateFoodCostPercentage, getOptimalSellingPrice, suggestPricing, analyzeProfitMargin, classifyMenuItems, generateMenuEngineeringReport.
• kitchen-workflow.ts — KWKitchenStation (KWStationType), KWPrepItem (KWPrepType), KWMiseEnPlace, KWServiceOrder (KWOrderStatus), KWKitchenTicket (KWTicketPriority/KWTicketStatus), KWKDSConfig/KWKDSScreen, KWExpoView, KWCookTimeBenchmark, KWShift; optimizeAssignments, generatePrepList, generateMiseEnPlace, coordinateCourses, KDS/expo views, identifyBottlenecks, generateShiftReport.
• inventory-management.ts — INVInventoryItem (INVStorageLocation, INVItemCategory), INVParLevel, INVAutoOrderRule/INVAutoOrderEvent, INVSupplier/INVSupplierPerformance, INVPurchaseOrder (INVPOStatus), INVReceivingRecord, INVInventoryCount (INVCountType), INVVarianceReport, INVFIFOBatch, INVWasteLog (INVWasteType); par-level checks, auto-ordering, PO lifecycle, receiving, variance counts, FIFO batches, waste/shrinkage analysis.
• food-safety.ts — FSHACCPPlan (FSPlanStatus), FSCriticalControlPoint (FSHazardType, FSCCPStatus, FSCCPReading), FSTempLog/FSTempZone, FSCorrectiveAction, FSCleaningTask/ FSCleaningRecord, FSSanitizationTest, FSAllergenProfile, FSSupplierVerification, FSAuditEntry, FSInspectionReport (FSFindingSeverity, FSInspectionStatus); CCP monitoring, temperature logging, corrective actions, cleaning/sanitation compliance, allergen matrix, supplier verification, audit trail, calculateComplianceScore.
• catering-events.ts — CTCateringQuote (CTQuoteStatus), CTEventMenu/ CTCourse, CTScalingResult, CTDietaryProfile/CTAccommodationReport, CTEquipmentRental (CTRentalStatus), CTStaffingPlan, CTEventTimeline, CTVenueInfo, CTTransportPlan, CTEventInvoice (CTInvoiceStatus), CTRevenueReport; quote lifecycle, menu scaling per service style, dietary accommodation, rentals, staffing, timelines, invoicing, revenue reporting.
• recipe-development.ts — RDProject (RDProjectStatus), RDTestBatch (RDTestBatchOutcome), RDIteration, RDTastingPanel/RDTastingScores, RDCostOptimization, RDShelfLifeTest, RDNutritionAnalysis, RDScaleTest, RDProductionDoc, RDApprovalRequest (RDApprovalStatus); project status machine, test-batch logging, iteration diffing, tasting panels, cost/shelf- life/nutrition/scale testing, production docs, multi-reviewer approval.

7.12 @hestia/social — social cooking#

The social library covers the full spectrum of community cooking — from recipe publishing with an attribution chain (tracking forks and remixes back to the original author) through live cook-along events with synchronized timers and chat, to family cookbook management and community challenges with a state machine from draft → open → closed → judging → completed.

• recipe-sharing.ts — RecipeStatus (draft/in_review/published/ unpublished/scheduled), DraftRecipe/PublishedRecipe, RecipeProfile, FeedItem/FeedConfig/PaginatedFeed (FeedSortMode), AttributionChain/AttributionNode, RemixRecord (RemixType), RecipeLicense (LicenseType), FeaturedCollection, TrendingScore, RecipeCategory, Hashtag; the draft→review→publish workflow, forkRecipe/createRemix, attribution chains, trending scores, category tree, hashtags.
• profiles-following.ts — UserProfile (SkillLevel), FollowRelationship, ActivityItem (ActivityType), ProfileTheme, CookingStats/HeatmapEntry, Achievement (AchievementCategory/ AchievementRarity), Badge (BadgeCategory/BadgeTier), VerificationApplication (VerificationStatus), CreatorSubscription/ TierConfig (MonetizationTier), PrivacySettings (PrivacyLevel); follow graph, activity feeds, cooking stats/heatmap, achievements/badges, chef verification, creator monetization, privacy and blocking.
• ratings-reviews.ts — RecipeRating (RatingSubScores), RecipeReview, ReviewPhoto (ReviewPhotoType), HelpfulVote, ReviewModerationRecord (ReviewModerationStatus, ReviewContentFlag), ReviewResponse, AggregatedRating, CookPhoto, ModificationNote (ModificationCategory), VerifiedCook (CookVerificationMethod); 1–5★ ratings with sub-scores, reviews with photos, helpful voting, moderation (autoModerate), responses, rating aggregation, cook verification.
• cook-alongs-events.ts — CookAlongEvent (CookAlongEventStatus = scheduled/live/completed/cancelled), EventCalendar/CalendarEntry, StreamSession (StreamQuality, StreamStatus), ChatMessage (ChatMessageType), EventParticipant (ParticipantRole/ParticipantStatus), EventRecording/RecordingChapter, EventReminder (ReminderType), IngredientKit/KitOrder, TimezoneInfo, EventAnalytics/HostDashboard; event lifecycle, calendars, live streams, chat, participants, recordings, reminders, ingredient kits, cross-timezone scheduling.
• family-cookbook.ts — FamilyGroup/FamilyMember (FamilyMemberRole, FamilyRelationship), FamilyCookbook (FamilyCookbookSection), ContributionRequest (FamilyContributionStatus), FamilyPermission, FamilyComment, CookingHistoryEntry (FamilyCookingOccasion), PrintedCookbook (PrintLayout), FamilyTreeNode, RecipeInheritance (InheritanceRule/InheritanceCondition), FamilyCookingChallenge; family groups with invite codes, shared cookbooks, contribution review, comments, cooking history, print export, recipe inheritance, family challenges.
• community-challenges.ts — CommunityChallenge (ChallengeType, ChallengeStatus), ChallengeTemplate/ChallengeThemedTemplate, ChallengeSubmission (ChallengeSubmissionStatus), ChallengeVotingConfig/ CommunityVote (ChallengeVotingMethod), ChallengeLeaderboardEntry, ChallengePrize (ChallengePrizePlace/ChallengePrizeType), CommunityBadge (ChallengeBadgeRarity), ChallengeAnalytics, CommunitySponsor/ CommunitySponsorDeal; the challenge lifecycle state machine (draft → open → closed → judging → completed, plus cancelled), templates/themes, submissions, voting + judge panels, leaderboards, prizes, badges, analytics, sponsorships.

7.13 @hestia/ai-ml — AI / ML intelligence#

The AI/ML library sits at the top of the dependency graph because it relies on the data and types from every other library. Recipe generation is not free-form LLM output — it is constrained by real IngredientProfile data, real ConstraintSet objects from the domain model, and domain-specific critique logic. The recommendations module implements three exploration strategies (epsilon-greedy, UCB1, Thompson sampling) for the multi-armed-bandit component of personalization. The predictive analytics module includes a full set of statistical primitives implemented from scratch in TypeScript.

• recipe-generation.ts — GeneratedRecipe (GeneratedIngredient, GeneratedStep), GenerationConfig, PromptTemplate, CuisineProfile, RecipeTemplate, ConstraintSet, RecipeCritique/CritiqueResult, FusionResult, VariationResult, SeasonalOptimizationResult, BudgetOptimizationResult, TimeOptimizationResult; generateFromIngredients, generateWithConstraints, generateByStyle, generateFusion, generateHealthierVersion, optimizeForBudget/Time/ Season, generateVariation, completePartialRecipe, critiqueRecipe, transformRecipeCuisine, suggestCompleteMeal, scoreIngredientMatch, estimateRecipeNutrition.
• flavor-pairing.ts — FlavorCategory, CompoundClass, PairingStrength (strong/moderate/weak/clash) unions; VolatileCompound, IngredientProfile, PairingScore, PairingExplanation, CulturalPairingRule, AntiPairing, BridgeSuggestion, ContextPairing, PairingGraph (PairingNode/PairingEdge), UserFeedback, NovelPairingResult; computePairingScore, topPairingsFor, discoverNovelPairings, findBridgeIngredients, checkAntiPairing, buildPairingGraph, findClusters, shortestFlavorPath, the FeedbackStore class.
• image-recognition.ts — DishCategory, DonenessLevel, PortionSize, PlatingStyle, FreshnessLevel, BarcodeFormat, IngredientState unions; DishRecognitionResult, IngredientDetectionResult, PortionEstimate, PlatingAnalysis, DonenessResult, QualityAssessment, NutritionFromImage, BarcodeData, NutritionLabel, HandwrittenRecipeOCR, MenuParseResult; recognizeDish, identifyIngredients, estimatePortionSize, analyzePlating, detectDoneness, assessFoodQuality, estimateNutritionFromImage, parseBarcode, parseNutritionLabel, processHandwrittenRecipeOCR, parseMenuImage, detectMultipleDishes.
• recommendations.ts — RecipeFeatures, UserProfile, TasteProfile, RecommendationResult, ScoringWeights, ContextSignal, HouseholdPreferences, ExplorationConfig, RecommendationPipeline; RecommendationMethod and ExplorationStrategy (epsilon-greedy/ucb1/ thompson-sampling) unions; collaborative filtering (getCollaborativeRecommendations), content-based (getContentBasedRecommendations), getHybridRecommendations, buildTasteProfile, multi-armed-bandit exploration (epsilonGreedySelect, applyUCB1Exploration), context/health/skill-aware recommendations, getHouseholdRecommendations, runRecommendationPipeline, diversifyResults.
• nlp.ts — ChatIntent, Sentiment, SupportedLanguage, CutStyle unions; RecipeSearchFilter, CookingQAPair, ParsedIngredient, TechniqueExplanation, SubstitutionEntry, MultilingualTerm, RecipeSummary, SentimentResult, ChatResponse, TokenizedText; tokenize, computeRelevanceScore, parseRecipeSearchQuery, answerCookingQuestion, clarifyRecipeInstructions, parseIngredient, explainTechnique, handleSubstitutionQuery, translateCookingTerm, summarizeRecipe, analyzeReviewSentiment, processChatMessage.
• predictive-analytics.ts — MealLogEntry, GroceryPurchase, CookingSession, RecipeAttempt, IngredientStorage, HouseholdDemand, SkillRecord, FeatureUsageLog input types and MealPrediction, GroceryPrediction, CookingTimePrediction, RecipeSuccessPrediction, SpoilagePrediction, DemandForecast, NutritionGoalPrediction, BudgetPrediction, SkillProgressionPrediction, FeatureEngagementPrediction output types; statistical primitives (mean, variance, standardDeviation, simpleMovingAverage, exponentialMovingAverage, linearRegression, bayesianBetaUpdate, holtLinearSmoothing, sigmoid, percentile); predictors predictMealPreference, predictGroceryNeeds, predictCookingTime, predictRecipeSuccess, predictIngredientSpoilage, forecastMealDemand, predictNutritionGoalAchievement, predictBudgetAdherence, predictSkillDevelopment, predictFeatureEngagement, generatePredictiveDashboard.

8. API Application (apps/hestia/api)#

@hestia/api is a Fastify service that exposes both a versioned REST API and a GraphQL API. Project tags are ["scope:hestia", "type:app", "layer:service"]. It depends on @hestia/core, @oshun/errors, @oshun/logging, fastify, graphql + graphql-yoga, drizzle-orm, pg, ioredis, zod, nanoid, and bcryptjs.

8.1 Server composition#

The server is assembled in a fixed plugin registration order that ensures each concern is in place before the next one needs it. The buildServer / entry point separation keeps server.inject() testing simple — the factory function never binds a port.

buildServer({ config }) (src/app.ts) creates a Fastify instance and registers plugins in a fixed order: request-context, cors, error-handler, swagger, auth (JWT), database (PostgreSQL + Drizzle), redis, rate-limit, graphql, then routes. It installs SIGINT/SIGTERM graceful shutdown. server.ts calls .listen(); buildServer itself does not bind a port, which keeps server.inject() testing simple.

8.2 Configuration (config.ts)#

loadConfig(env) parses process.env with a Zod schema and fails fast on mis-configuration. The key variables and their defaults are:

PORT (3040), HOST (127.0.0.1), NODE_ENV (development), JWT_SECRET, JWT_ISSUER (hestia-api), JWT_ACCESS_TOKEN_TTL (900 s), JWT_REFRESH_TOKEN_TTL (604800 s), DATABASE_URL, DB_POOL_MIN (2), DB_POOL_MAX (10), REDIS_URL, RATE_LIMIT_MAX (100), RATE_LIMIT_WINDOW_MS (60000), LOG_LEVEL (info), METRICS_PORT (9094), CORS_ORIGIN (*), AI_API_KEY, AI_MODEL (gpt-4), SESSION_MAX_PER_USER (10). Cross-field rules: in production the default JWT_SECRET is rejected, and DB_POOL_MIN must not exceed DB_POOL_MAX. The result is the typed AppConfig (src/types.ts).

8.3 Shared API types (types.ts)#

The types file augments Fastify's request/server instances and defines the shared shapes that every route handler and plugin uses. The HestiaPermission union is the complete list of fine-grained permissions enforced throughout the API.

AuthenticatedUser (id, email, roles[], permissions[]), RequestContext (requestId, correlationId, startTime), CacheHelper (typed JSON cache over Redis), HealthCheckResponse (HealthStatus = ok/degraded/unhealthy), ApiErrorResponse ({ error: { code, message, details?, requestId? } }), ApiInfoResponse, PaginatedResponse<T>, Session, ApiKey, RefreshTokenRecord. HestiaRole is owner | admin | contributor | viewer; HestiaPermission is a 19-value union (recipe:read/write/delete/publish, ingredient:read/write, meal_plan:read/write, shopping:read/write, pantry:read/write, nutrition:read, cooking:read/write, social:read/write, ai:use, admin:manage). Fastify is augmented with request.ctx, fastify.db, fastify.dbPool, fastify.redis, fastify.cache, and fastify.authenticate.

8.4 REST surface#

registerRoutes (src/routes/index.ts) mounts health probes unprefixed and everything else under /v1. GET /v1/info (authenticated) returns API metadata listing the 10 functional domains.

Health (/health*, no auth) — GET /health (liveness), GET /health/ready (readiness), GET /health/startup (startup probe).

Auth (/v1/auth) — POST /register, POST /login, POST /refresh (refresh-token rotation, RefreshTokenRecord family tracking), POST /logout, GET /sessions (list active sessions), POST /api-keys, GET /api-keys, DELETE /api-keys/:id. Passwords are hashed with bcryptjs; access/refresh JWTs use the configured TTLs.

Recipes (/v1/recipes) — GET / (list own recipes, paginated, filterable by cuisine/mealType/difficulty/status), POST / (create), GET /search (text + cuisine/mealType/maxCookTime/dietary/ingredients), GET /:id, PUT /:id (author only; bumps version), DELETE /:id (author only), POST /import (from url or text), POST /:id/scale (linear ingredient scaling), GET /:id/nutrition (category-keyword nutrition estimate). Request bodies are validated by Zod schemas; the RecipeRecord shape mirrors the hestia_recipes columns. Errors use ApiErrorResponse codes such as RECIPE_NOT_FOUND, FORBIDDEN, IMPORT_SOURCE_REQUIRED.

Ingredients (/v1/ingredients) — GET /search, GET /seasonal, GET /:id, GET /:id/substitutions.

Meal plans (/v1/meal-plans) — GET /, POST /, POST /generate (weekly plan), GET /current-week, GET /:id, PUT /:id, DELETE /:id, GET /:id/shopping-list.

Shopping (/v1/shopping) — GET /, POST /, POST /generate (from a meal plan), GET /:id, DELETE /:id, PATCH /:id/items/... (toggle purchased), POST /:id/share.

Pantry (/v1/pantry) — GET / (inventory), POST / (add item), PATCH /:id (update quantity), DELETE /:id, GET /expiring, GET /recipe-suggestions.

Nutrition (/v1/nutrition) — POST /calculate (nutrition for an ingredient list), GET /daily (daily summary), POST /log (log a meal), GET /goals, PUT /goals.

Cooking (/v1/cooking) — POST /sessions (start a session), GET /sessions (list), GET /sessions/:id (status), PATCH /sessions/:id/step (advance step), POST /sessions/:id/timer (add timer, ≤ 24 h), PATCH /sessions/:id/complete (rating 1–5 + feedback).

Preferences (/v1/preferences) — GET/PUT / (food preferences), GET/PUT /allergies, GET/PUT /dietary-restrictions.

Social (/v1/social) — POST /recipes/:id/rate, POST /recipes/:id/review, GET /recipes/:id/reviews, POST /collections, GET /collections, GET /collections/:id, POST /collections/:id/recipes, DELETE /collections/:id/recipes/:recipeId, DELETE /collections/:id.

AI (/v1/ai) — POST /generate-recipe (from ingredients), POST /substitutions, POST /meal-plan (AI meal plan), POST /chat (culinary assistant chat).

8.5 Cooking-session state machine (REST)#

The cooking-session routes drive a four-state lifecycle. The state transitions are:

1. POST /sessions — creates a session directly in in_progress, materialises one step record per recipe step, and starts step 1.
2. PATCH /sessions/:id/step — requires status === 'in_progress', marks the current step completed, advances currentStep, and stamps the next step's startedAt.
3. PATCH /sessions/:id/complete — records the final rating (1–5) and feedback, then transitions to completed.
4. Any step or timer mutation on a non-active session returns SESSION_NOT_ACTIVE.

The full state machine on CookingSessionRecord.status: planned → in_progress → completed / cancelled.

8.6 GraphQL API#

The GraphQL plugin (src/graphql/index.ts) serves a GraphQL Yoga endpoint at a single URL alongside the REST API. The schema is defined in src/graphql/schema.ts with resolvers organized by domain under src/graphql/resolvers/ (recipe, ingredient, meal-plan, pantry, nutrition, cooking-session).

Scalars — DateTime, JSON.

Enums — MealType, Difficulty, CookingMethod (35 values), MeasurementUnit (24 values), DietaryRestriction (20 values), Allergen (14 values), RecipeStatus, Visibility, IngredientCategory, InventoryStatus, SessionStatus, ShoppingItemStatus.

Object types — Recipe (with RecipeIngredient, RecipeStep), Ingredient (with FlavorProfile, NutritionalData), NutritionAnalysis (with NutritionPerServing, IngredientNutrition, DailyValuePercentages), MealPlan / MealPlanMeal, PantryItem, ShoppingList / ShoppingItem, CookingSession, UserPreferences, FlavorCompound, IngredientPairing.

Pagination — Relay-style PageInfo, RecipeConnection/RecipeEdge, IngredientConnection/IngredientEdge. Result helper types DeleteResult, BatchResult/BatchError, GeneratedShoppingList.

Input types — RecipeFilter, IngredientFilter, PantryFilter, PaginationInput, CreateRecipeInput/UpdateRecipeInput, RecipeIngredientInput/RecipeStepInput, CreateMealPlanInput/ UpdateMealPlanInput/MealPlanMealInput, AddPantryItemInput/ UpdatePantryItemInput, CreateShoppingListInput/ShoppingItemInput, BatchDeleteInput.

Query — recipe, recipes, searchRecipes, ingredient, ingredients, mealPlan, mealPlans, pantryItems, shoppingLists, shoppingList, cookingSession, activeCookingSessions, nutritionAnalysis, ingredientPairings, flavorCompounds, userPreferences.

Mutation — recipe CRUD + batchDeleteRecipes; meal-plan CRUD + generateShoppingListFromMealPlan; pantry addToPantry/updatePantryItem/ removePantryItem; shopping createShoppingList/checkShoppingItem/ uncheckShoppingItem/deleteShoppingList; cooking-session startCookingSession/advanceCookingStep/completeCookingSession/ cancelCookingSession.

Subscription — cookingSessionUpdated(sessionId) → CookingSessionUpdate; pantryItemExpiring(userId) → PantryExpirationAlert.

8.7 GraphQL authorization (graphql/permissions.ts)#

The GraphQL authorization layer enforces the same domain rules as @hestia/core/auth.ts but at the resolver level, translating them into GraphQL-specific patterns. Public recipe visibility is an important special case: published-public recipes are visible to unauthenticated users, which is intentional for SEO and sharing.

A PERMISSIONS constant defines 16 permission strings (recipe:read/write/ delete/publish, ingredient:read/write, meal_plan:read/write, shopping:read/write, pantry:read/write, nutrition:read, cooking:read/write, admin:manage). canViewRecipe makes published-public recipes visible to everyone, requires authentication otherwise, grants admins and authors full visibility, and exposes published-household recipes to any authenticated user. assertCanModifyRecipe, assertCanDeleteRecipe, assertCanPublishRecipe enforce author-or-admin ownership; assertCanModifyIngredient restricts shared-ingredient writes to admins; assertCanAccessMealPlan / …PantryItem / …ShoppingList / …CookingSession enforce owner-or-admin access on user-owned resources via requireOwnership.

9. Web Application (apps/hestia/web)#

@hestia/web is a Next.js (App Router) application; project tags ["scope:hestia", "type:app", "platform:web"]. It runs on port 3011 and depends on @hestia/core, @tanstack/react-query, zustand, next, react, lucide-react, tailwind-merge, and date-fns.

The web application uses Next.js route groups to cleanly separate unauthenticated pages (login, register) from the authenticated application, which spans recipe management, meal planning, cooking, and a full admin console.

• Route groups — (auth) holds login and register; (app) holds the authenticated application. App routes cover recipes (list, new, import, bulk, collections, analytics, and per-recipe view/edit/print/ versions), meal-plans (calendar plus auto-plan, budget, events, household, nutrition, prep, slots, templates), pantry (alerts, budget, bulk, equipment, expiration, reports), shopping (compare, history), cooking, nutrition, learn (courses, lessons, quizzes, skills, progress, certificates, bookmarks, discussions, instructor), community (challenges, connections, events, messages, moderation, notifications, reviews, report, per-user profiles), an admin console (analytics, api-keys, audit, config, features, health, ingredients, moderation, nutrition, users), and settings.
• Data layer — src/lib/api-client.ts, src/lib/query-client.ts, and feature hooks under src/hooks/ (useAuth, useCooking, useMealPlans, useNutrition, usePantry, useRecipes, useShopping). Client state lives in Zustand stores (app-store, auth-store, cooking-store).
• Testing — Vitest component/integration tests under src/__tests__/ and Playwright end-to-end specs under e2e/ (auth, community, cooking, meal-plans, navigation, recipes, search, shopping).

10. Mobile Application (apps/hestia/mobile)#

@hestia/mobile is an Expo / React Native application named "Hestia — Culinary Intelligence Mobile App". It depends on expo, react-native, React Navigation (native-stack + bottom-tabs), @tanstack/react-query, zustand, expo-notifications, expo-secure-store, and @react-native-async-storage/ async-storage.

The mobile app covers all the same functional areas as the web app, organized into native screens. A notable mobile-specific feature is the offline layer (OfflineManager + OfflineIndicator), which is essential given that mobile cooks may be in kitchens with poor connectivity.

• Screens — auth (Login, Register); recipes (List, Detail, Editor, Search, Collections); cooking (CookingSession, StepByStep, Timer); camera (IngredientIdentify, RecipeScan); meal-plan (Week, Day, Generate); nutrition (Dashboard, Daily, Goals); shopping (ShoppingList, Pantry, ExpiringItems); iot (SmartKitchen); social (SocialFeed, Reviews, SharedCollections); settings (Settings, Preferences, Allergies, About).
• Data layer — src/api/client.ts, src/api/queryClient.ts, and hooks under src/api/hooks/ (useAuth, useCooking, useMealPlans, useNutrition, usePantry, useRecipes, useShopping). Zustand stores (appStore, authStore). An offline layer (src/services/offline/, OfflineManager + OfflineIndicator) supports disconnected use.
• Navigation and theme — AppNavigator plus deep-link linking configuration; a shared UI component set (Button, Card, Input, Modal, BottomSheet, etc.) and a theme/ (colors, spacing, typography).

11. Build and Tooling#

The build configuration is consistent across all Hestia components. Libraries use tsc directly (no bundler) and ship ESM. The API uses tsx watch for development and node dist/server.js in production. The web app uses Next.js dev/build scripts via Nx run-commands wrappers on port 3011.

• Libraries — @nx/js:tsc build, @nx/eslint:lint lint, @nx/vite:test (Vitest) test; "type": "module" ESM; tags ["scope:hestia", "layer:domain", "type:lib"].
• API — Nx nx:run-commands targets: build (tsc), dev (tsx watch src/server.ts), start (node dist/server.js, depends on build), lint, test (vitest run), typecheck (tsc --noEmit).
• Web — Nx nx:run-commands targets wrapping next dev/next build (port 3011), plus Vitest and Playwright.
• Mobile — Expo scripts (expo start and platform variants), jest / jest-expo for tests.

12. Integration Points#

12.1 Internal dependencies#

The web and mobile clients do not import feature libraries directly — they consume the API over HTTP. This keeps client bundles lean, centralizes authorization in the API, and lets the mobile offline layer cache API responses rather than managing library state directly.

12.2 Infrastructure and external systems#

13. V2 Cross-Domain Contract#

13.1 V2 Recipe-As-Mini-Game-Script Embedding Surface#

The V2 Recipe-As-Mini-Game-Script Embedding Surface lets the separate V2 (fighting-game) program embed Hestia recipe intelligence as a cooking mini-game without duplicating any recipe, ingredient, or pantry logic. The adapter is published as @v2/hestia-cooking-minigame-bridge (apps/v2/hestia-cooking-minigame-bridge) and composes six Hestia libraries at workspace:*: @hestia/ai-ml (recipe generation via generateFromIngredients), @hestia/cooking (GuidedCookingSession and getWalkthroughByDifficulty), @hestia/education, @hestia/ingredients (the IngredientDatabase), @hestia/pantry (the PantryInventory and getKitchenByType), and @hestia/core.

The bridge emits a hestia.recipe-as-mini-game-script manifest — a recipe compiled into the script a V2 cooking mini-game runs — targeting the V2Mode_Cooking runtime and surfacing in the V2Mode_BattleHub cabinet. The manifest is built from real ingredient match ratios and pantry sourcing; recipe generation with no candidates, a poor ingredient match ratio, or incomplete pantry sourcing produce explicit manifest failures rather than fabricated scripts.

This surface is off rollback. Hestia remains the source of truth for recipe, ingredient, and pantry data, and the bridge guards every call with a calledFromLiveCookingFrame check (rejectsLiveCookingFrameRpc: true, mayInfluenceRollback: false): it must never run inside a deterministic combat or cooking simulation frame, and it must never feed rollback inputs. The integration contract is specified in full at V2/docs/integration/hestia-cooking-minigame-bridge.md.