# Hestia — Systems Deep Dive

> The `libs/hestia/` area: fourteen Nx libraries that implement **Hestia, the
> culinary-intelligence platform** — from a shared domain core through
> ingredient science, nutrition, recipes, an Epicure-style embedding engine, and
> the kitchen/social/education surfaces built on top.

## What this area is

Hestia (named for the Greek goddess of the hearth) is Oshun's culinary domain,
and `libs/hestia/` is where its logic lives — not as one package but as
**fourteen separate Nx libraries**, each tagged `scope:hestia`, `layer:domain`,
`type:lib`. Every project is a `@nx/js:tsc`-built TypeScript library with its
own `src/index.ts` barrel, its own `vitest.config.ts`, and a co-located
`*.spec.ts` beside every module. These are substantial, fully-implemented
libraries (the larger ones — `ai-ml`, `education`, `social`, `professional`,
`sustainability` — run to 22–25k lines of source-plus-tests each); none of the
fourteen is an empty scaffold.

The area is layered. `@hestia/core` sits at the bottom as the shared foundation:
measurement/temperature conversions (`types.ts`, volume anchored on ml, weight
on grams), the pure-TypeScript domain schemas and validators (`schemas.ts`, no
Zod runtime), a Drizzle ORM PostgreSQL schema of ~20 tables (`db-schema.ts`), a
domain-event system with an `EventStore`/`EventBus`/projections/upcasters
(`events.ts`), and the authorization model (`auth.ts`). The other thirteen
libraries import their domain types from `@hestia/core` — for example
`@hestia/recipes` imports `Recipe`/`RecipeIngredient`, `@hestia/nutrition`
imports `NutritionInfo`/`MineralProfile`, and `@hestia/pantry` imports
`IngredientCategory`.

On top of that core sit two tiers: a **data-and-intelligence tier**
(`ingredients`, `nutrition`, `recipes`, `ai-ml`) that owns the heavy domain
modelling, and a **experience tier** (`cooking`, `meal-planning`, `pantry`,
`smart-kitchen`, `professional`, `social`, `education`, `heritage`,
`sustainability`) that builds user- and operator-facing features on top of the
data tier. The standout node is `@hestia/ai-ml`, which implements an
Epicure-style ingredient-embedding pipeline (typed heterograph → metapath2vec
random walks → skip-gram with negative sampling → orthogonal-Procrustes
alignment to sensory axes → WEAT bias tests) in pure TypeScript.

## How it fits the wider system

The dependency edges inside the area are deliberately one-directional and mostly
flow through `@hestia/core`. Where a cross-library dependency would otherwise be
heavy — notably between `@hestia/ingredients` and `@hestia/ai-ml` — the code
uses a **structural (duck-typed) interface** instead of a package import:
`@hestia/ingredients/src/pairing.ts` declares a `VectorSimilarityLookup`
interface that `ai-ml`'s `EmbeddingStore` happens to satisfy, so `pairing.ts`
and `substitution.ts` can consume trained embeddings without `ingredients/`
taking a hard dependency on `ai-ml/`. That keeps the intelligence engine
optional: the pairing and substitution engines work from curated rules alone and
gain embedding-powered recall only when a trained model is injected.

Consumers outside the area import the public barrel of whichever capability they
need — `@hestia/recipes` for recipe modelling and scaling, `@hestia/nutrition`
for analysis and allergen handling, `@hestia/professional` for
commercial-kitchen HACCP/menu-costing, and so on. Walk the "used by" edges on
any node below to see exactly who depends on it.

## Entity reference

### @hestia/core

The shared foundation every other Hestia library builds on
(`libs/hestia/core/src`). It bundles five modules behind one barrel:
`schemas.ts` (pure-TypeScript domain interfaces, enums like `MeasurementUnit`,
and validation functions — deliberately _no_ Zod runtime dependency), `types.ts`
(the measurement and temperature conversion system, anchored on millilitres for
volume and grams for weight, plus equipment/user/household types),
`db-schema.ts` (Drizzle ORM PostgreSQL definitions — roughly 20 `pgTable`s with
enums, indexes, and relations), `events.ts` (a `DomainEvent` base with an
`EventStore`, `EventBus`, projections, versioned upcasters, and notifications),
and `auth.ts` (`RecipeVisibility`, roles, permissions, household sharing, and
API-key scopes). Most other libraries in the area import their domain types from
here.

### @hestia/ingredients

The ingredient-intelligence library (`libs/hestia/ingredients/src`). Its modules
cover a `master-database`, per-ingredient `nutrition`, a `flavor-compounds`
database that models Maillard products, fermentation products, and compound
interactions (synergy/suppression/enhancement) with detection thresholds in ppm,
a `pairing` engine scoring from traditional cuisine pairings plus
flavor-compound overlap, a `substitution` engine
(allergen/dietary/budget/functional subs), `seasonality`, and a `multilingual`
lexicon with a deterministic `canonicalization` pipeline modelled on Epicure's
LLM-assisted normalization. Both `pairing.ts` and `substitution.ts` accept an
optional `VectorSimilarityLookup` (duck-typed to `@hestia/ai-ml`'s
`EmbeddingStore`) to add embedding-based similarity, k-NN, and bridge-ingredient
discovery without a hard dependency on the ML library.

### @hestia/nutrition

Nutrition analysis and dietary management (`libs/hestia/nutrition/src`), built
on `@hestia/core`'s `NutritionInfo`/`MineralProfile`/`VitaminProfile` types. It
exposes `analysis`, a `bioavailability` model (absorption factors with
enhancers/inhibitors, cooking-retention factors, nutrient–nutrient interactions,
and personalized adjustments by age/sex/condition), `dietary` management, an
`allergen` system (detection, hidden-allergen flagging, cross-contamination
warnings, severity from mild to anaphylactic, multi-person tracking),
`medical-diet` support, and personalized `goals`.

### @hestia/recipes

Recipe management (`libs/hestia/recipes/src`), built on the `Recipe`/
`RecipeIngredient`/`Instruction` types from `@hestia/core`. Modules: a
`recipe-model`, a `parsing` engine (ingredient-line parsing with a large
unit-alias normalization map, plus quantity/prep/instruction/time/temperature/
equipment extraction), `import-export`, a `scaling` engine with category-aware
rules (linear for most ingredients, sublinear `factor^0.7` power-law for spices,
`factor^0.8` for leavening, plus cooking-time/temperature and pan-size
adjustments), `versioning`, `search`, and `collections`.

### @hestia/ai-ml

The machine-learning engine and the most algorithm-dense node in the area
(`libs/hestia/ai-ml/src`). Alongside `recipe-generation`, `flavor-pairing`,
`image-recognition`, `recommendations`, `nlp`, and `predictive-analytics`, it
implements a full **Epicure-style ingredient-embedding pipeline** in pure
TypeScript: `rng` (deterministic seeded RNG), `embeddings` (vectors +
cosine/similarity primitives), `heterograph` (a typed graph with CHEM / CHEM_CAT
/ COOC metapaths), `metapath2vec` (typed random walks feeding skip-gram with
negative sampling), `procrustes` (closed-form orthogonal-Procrustes alignment of
the embedding space to sensory axes via Jacobi-rotation SVD), `bias-evaluation`
(WEAT effect size plus a non-parametric permutation-test p-value), and
`epicure`, which orchestrates these into a trained model holding three lenses —
Chem, Cooc, and Core — supporting similarity, nearest-neighbor, bridge
discovery, and Mikolov-style 3CosAdd analogy. The module comments tie each piece
back to the Epicure paper's method and ablation tables.

### @hestia/cooking

The active-cooking surface (`libs/hestia/cooking/src`): `guided-cooking`
(step-by-step sessions), `timers`, a `voice` interface (command parsing for
next/previous/repeat/timer/quantity/substitute intents, TTS formatting, and
eight-language support — en/es/fr/de/it/ja/zh/ko), `doneness` guides
(temperature ranges, visual cues, and touch tests across
meat/bread/egg/vegetable/sauce/ caramel/dough/emulsion categories),
`techniques`, and a `session-log`.

### @hestia/meal-planning

Meal-planning and household coordination (`libs/hestia/meal-planning/src`):
`calendar`, `household`, recipe `suggestions`, a `budget` optimizer (cost
estimation, spending tracking, bulk-buying, coupon management, budget-friendly
substitutions, and budgeted-vs-actual comparison), `batch-cooking`, and an
`events` module. It imports `Recipe` from `@hestia/core`.

### @hestia/pantry

Pantry and inventory management (`libs/hestia/pantry/src`): `inventory`,
barcode/receipt `scanning`, `expiration` management (tiered alerts
info→warning→urgent→expired, FIFO ordering, waste tracking by reason, and recipe
suggestions for expiring items), `shopping`, `grocery-store` integration, and
`equipment`. It imports `IngredientCategory` from `@hestia/core`.

### @hestia/smart-kitchen

The IoT / connected-appliance layer (`libs/hestia/smart-kitchen/src`): a generic
`devices` model, `cooking-devices`, `sensors`, `smart-appliances`, `automation`
workflows, and an `orchestration` module that schedules a multi-device cooking
plan (building an `ExecutionPlan` of timed per-device steps, tracking
`CookingProgress`, and powering a kitchen dashboard).

### @hestia/professional

The commercial-kitchen / foodservice library (`libs/hestia/professional/src`):
`menu-costing` (ingredient cost database with price history, recipe costing,
food cost %, pricing suggestions, margin analysis, supplier comparison, and menu
engineering), `kitchen-workflow`, `inventory-management`, a `food-safety` module
implementing HACCP (plan builder, critical-control-point tracking, temperature
logging, corrective actions, sanitization verification, audit trails, and health
inspector reports), `catering-events`, and `recipe-development`.

### @hestia/social

The culinary social network (`libs/hestia/social/src`): `recipe-sharing`,
`profiles-following`, `ratings-reviews` (1–5 ratings with optional sub-scores
for taste/difficulty/presentation/value/accuracy, photo reviews, helpful votes,
moderation, review responses, aggregation, and verification),
`cook-alongs-events`, `family-cookbook`, and `community-challenges`.

### @hestia/education

The culinary-education platform (`libs/hestia/education/src`): a `techniques`
library, a gamified `progression` system (skill trees, XP, badges with rarity
tiers, challenges with weighted criteria, assessments, and personalized learning
paths across the novice→apprentice→journeyman→expert→master skill levels), a
`food-science` curriculum (courses on the Maillard reaction, caramelization,
protein denaturation, starch gelatinization, emulsions, gluten, fermentation,
etc., with diagrams and temperature-curve data), world-`cuisine` deep-dives,
`certifications`, and `interactive` learning features.

### @hestia/heritage

The cultural-heritage preservation library (`libs/hestia/heritage/src`):
`family-recipes` digitization, an `oral-history` module (audio/video recording
configs, transcription engines including whisper, guided interviews,
story-to-recipe linking, timeline visualization, geographic-origin and migration
tracking, language preservation, and cross-generation sharing), a
`regional-archive`, `food-history` research, and a `community` contribution
surface.

### @hestia/sustainability

The environmental-impact library (`libs/hestia/sustainability/src`): a
`carbon-footprint` calculator (a `FoodCategory` enum from meat through processed
foods, a `TransportMode` enum, and supply-chain modelling), `food-waste`
tracking, `ethical-sourcing`, `seasonal-local` guidance, and `composting`.