Hestia — Architecture

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

Hestia is the Oshun culinary intelligence platform. Where most recipe apps are essentially databases with search, Hestia is a full culinary operating system — connecting ingredient chemistry, nutritional science, kitchen IoT devices, and social cooking into a single coherent experience centered on the home kitchen. The domain takes its name from Hestia, the Greek goddess of the hearth, because the hearth — the fire at the center of domestic life — was historically the literal and symbolic heart of the household. In the same spirit, this domain treats cooking not as a chore to be optimized but as a practice that carries cultural memory, health consequences, and daily human meaning.

The platform is used directly by home cooks through web and mobile clients, and by other Oshun domains that need culinary data — @arete for nutrition goals, @demeter for seasonal ingredients, and @sophia for culinary knowledge. The 14 libraries in libs/hestia/ implement the domain logic, and three applications in apps/hestia/ expose that logic to users: a Fastify REST + GraphQL API, a Next.js web client, and an Expo / React Native mobile client.

1. Domain Summary#

Hestia is a culinary intelligence domain comprising 14 libraries and 3 applications. The 14 sibling libraries under libs/hestia/ carry the domain logic — spanning ingredient chemistry and nutritional science through smart kitchen device orchestration and social cooking experiences. Three applications under apps/hestia/ expose that logic: a Fastify REST + GraphQL API (apps/hestia/api), a Next.js web client (apps/hestia/web), and an Expo / React Native mobile client (apps/hestia/mobile). Other monorepo consumers may also import the library packages directly.

2. Component Topology#

The diagram below shows how the 14 libraries are organized into layers. Reading from the bottom up: @hestia/core is the foundation; the science layer sits above it; the cooking workflow layer above that; then planning; and finally the culture, intelligence, and social capabilities at the top. Arrows show dependency direction — each library depends on @hestia/core and on nothing else within the feature layer.

             @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)

3. Layer Architecture#

Hestia is organized into five conceptual layers. Libraries within a layer depend only on @hestia/core — they do not depend on each other horizontally. This means any pair of feature libraries can be used together without risking a version conflict, and the consuming application controls exactly which capabilities it assembles.

Layer 1 — Foundation#

@hestia/core (zero runtime dependencies)

Every other Hestia library is built on top of @hestia/core. It serves as the single source of truth for the domain model — type definitions, database schema, event system, and authorization rules all live here. Because it has zero runtime dependencies, it can be imported into any Node.js, browser, or edge context without risk.

• Pure TypeScript interfaces for the full domain model (no Zod runtime)
• Drizzle ORM database schema definitions for PostgreSQL
• Domain event type definitions
• Authentication utilities

Layer 2 — Science#

@hestia/ingredients and @hestia/nutrition

The science layer implements the deep domain knowledge that distinguishes Hestia from basic recipe apps. A typical recipe database knows that a dish "contains chicken," but Hestia knows the volatile compounds in every ingredient, how different cooking methods change nutrient bioavailability, and which hidden allergens are concealed under opaque ingredient names. This layer is the foundation for all the intelligent features above it.

• Ingredients: Master ingredient database with flavor compound analysis. Flavor pairing uses volatile compound overlap analysis across hundreds of flavor families (fruity, floral, earthy, umami, Maillard, sulfurous). Substitutions account for flavor profile, texture, and dietary restrictions.

• Nutrition: Bioavailability modeling goes beyond raw nutrient values to estimate actual absorption efficiency — accounting for nutrient interactions (vitamin C enhancing iron absorption, phytates inhibiting zinc uptake) and cooking method effects. Allergen detection operates at the molecular level including hidden allergens in processed ingredients.

Layer 3 — Cooking#

@hestia/recipes, @hestia/cooking, @hestia/smart-kitchen

The cooking layer handles the core kitchen workflow: knowing what to cook, doing the cooking, and connecting the smart devices in the kitchen. These three libraries work together at mealtime — @hestia/recipes supplies the plan, @hestia/cooking guides the execution step by step, and @hestia/smart-kitchen automates the hardware.

• Recipes: The data model and all operations on it. Parsing extracts structured data from unstructured text, URLs, and images. Versioning provides Git-like branching and merging for collaborative recipe development.

• Cooking: Step-by-step guided sessions with multi-recipe coordination, multiple concurrent timers with conflict detection, hands-free voice interface, USDA-referenced doneness guides, and complete session logging.

• Smart kitchen: IoT device orchestration spanning smart ovens, sous vide, sensors, and smart appliances. The automation rules engine enables event- driven workflows; the orchestration layer coordinates multi-device scenarios.

Layer 4 — Planning#

@hestia/meal-planning, @hestia/pantry, @hestia/sustainability

The planning layer manages the household food lifecycle at the weekly and monthly scale — what to buy, what is already in the kitchen, and what the environmental impact of those choices is. These libraries work together: the pantry drives the shopping list, the shopping list feeds the meal plan, and sustainability scores are applied across all three.

• Meal planning: Weekly and monthly calendar planning with household-member dietary profiles, budget tracking, batch cooking session planning, and event catering support.

• Pantry: Full inventory lifecycle from barcode-scan entry through expiration alerting, FIFO rotation, and automatic shopping list generation with store-aisle organization.

• Sustainability: Carbon footprint calculation, food waste tracking, ethical sourcing evaluation (fair trade, organic, animal welfare), and composting guidance.

Layer 5 — Culture and Intelligence#

@hestia/heritage, @hestia/education, @hestia/professional, @hestia/social, @hestia/ai-ml

The culture and intelligence layer provides the platform's differentiating capabilities. These libraries sit at the top of the dependency graph — they are the most consumer-facing and draw on all lower layers — but they remain flat siblings that do not depend on each other.

• Heritage: Digitizes family recipes, oral cooking histories, and regional cuisine traditions with community contribution workflows.

• Education: Structured skill progression from beginner techniques through food science (Maillard reaction, emulsification, fermentation) to certification programs.

• Professional: Commercial kitchen tooling — HACCP compliance, menu costing, kitchen workflow optimization, and catering event management.

• Social: Community platform with cook-along events, family cookbooks, competitive challenges, and recipe sharing with attribution.

• AI/ML: LLM-based recipe generation constrained by real domain data, ML-trained flavor pairing models, computer vision for food identification, collaborative and content-based filtering for recommendations.

4. Dependency Graph#

The flat-peer pattern is a deliberate architectural choice. By declaring @hestia/core as a peerDependency rather than a direct dependency, every feature library lets the consuming application control the exact version of core in the runtime, preventing duplicate installations and version mismatches. The consuming application assembles whichever libraries it needs; there is no "kitchen sink" bundle.

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

All feature libraries are flat siblings. There are no inter-library dependencies within the feature layer; coupling is managed entirely at the application layer by whichever consumer assembles the libraries.

Applications#

Three applications sit above the library layer. The web and mobile clients consume the API over HTTP rather than importing feature libraries directly — this keeps the client bundles lean and centralizes authorization logic in the API where it can be enforced.

@hestia/api      (Fastify REST + GraphQL Yoga; PostgreSQL/Drizzle + Redis)
  depends on: @hestia/core, @oshun/errors, @oshun/logging
@hestia/web      (Next.js App Router; TanStack Query + Zustand; port 3011)
  depends on: @hestia/core
@hestia/mobile   (Expo / React Native; React Navigation; TanStack Query + Zustand)
  depends on: the @hestia/api HTTP surface

@hestia/api is tagged ["scope:hestia", "type:app", "layer:service"]; @hestia/web is tagged ["scope:hestia", "type:app", "platform:web"].

5. Design Patterns#

Pure TypeScript Schemas#

Unlike most Oshun domains that use Zod for validation, @hestia/core defines domain types using pure TypeScript interfaces with validation functions. This eliminates Zod's runtime overhead from the critical data path. The trade- off is manual validation rather than schema-derived runtime validation.

Const Enum Objects#

All enumerable domains (measurement units, cooking methods, diet tags, etc.) are defined as const objects with derived type unions. This pattern provides both runtime value access (e.g., iterating over Object.values(CookingMethod) to populate a UI dropdown) and compile-time exhaustiveness checking in switch statements.

export const CookingMethod = {
  BAKE: 'bake',
  ROAST: 'roast',
  // ...
} as const;
export type CookingMethod = (typeof CookingMethod)[keyof typeof CookingMethod];

Flat Peer Dependency Architecture#

Every feature library declares @hestia/core as a peer dependency rather than a direct dependency. This allows the consuming application to control the exact version of core and prevents version conflicts when multiple Hestia libraries are used together.

6. Technology Stack#

The table below lists the technology choices for each component. The most notable choice is the deliberate avoidance of Zod in @hestia/core — the domain data path uses hand-written validation functions so that the library can be used in edge or browser contexts where Zod's bundle size matters. Zod is still used in the API layer for request validation, where it is only ever loaded on the server.

7. Project Configuration#

All Hestia libraries share a consistent Nx project configuration. The key settings are ESM module format (required for tree-shaking and compatibility with modern bundlers), the tsc build executor (no bundler — each library ships clean TypeScript output), and the scope:hestia tag that lets Nx target all domain libraries at once.

• Project tags: ["scope:hestia", "layer:domain", "type:lib"]
• Module format: ESM ("type": "module" in all package.json files)
• Build executor: @nx/js:tsc
• Test runner: @nx/vite:test with Vitest

Common Build Commands#

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

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

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

# Lint a library
pnpm nx lint @hestia/ingredients

8. Related Domains#

Hestia's boundaries are drawn around the home kitchen and consumer culinary experience. The boundaries with adjacent domains reflect real-world ownership distinctions — Hestia does not manage commercial food-service operations (Annapurna's territory), nor does it own the full creator economy or personal health goal system (Yemaya and Arete respectively). Data flows across these boundaries: Hestia can supply recipe, nutrition, and smart kitchen inputs to Annapurna; @hestia/nutrition surfaces goals that @arete tracks; and @hestia/education surfaces research content originally curated by @sophia.