# 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. ```typescript 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. | Component | Technology | | ------------------ | -------------------------------------------------------------- | | Language | TypeScript (ESM modules) | | Runtime | Node.js | | Library build | Nx with `@nx/js:tsc` | | Library testing | Vitest | | Library validation | Pure TypeScript (no Zod runtime) in `@hestia/core` | | ORM | Drizzle ORM | | Database | PostgreSQL | | API framework | Fastify (REST under `/v1`) + GraphQL Yoga | | API validation | Zod (request bodies, environment configuration) | | API store/cache | PostgreSQL via `pg` + Drizzle; Redis via `ioredis` | | API auth | JWT (`@fastify/jwt`), `bcryptjs` password hashing, API keys | | Web app | Next.js (App Router), React, TanStack Query, Zustand, Tailwind | | Mobile app | Expo / React Native, React Navigation, TanStack Query, Zustand | | Food safety | HACCP, USDA temperature guidelines | | Nutrition data | USDA FoodData Central (FDC) | --- ## 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 ```bash # 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`. | Domain | Boundary and data flow | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Demeter | Shares seasonal ingredient concepts; preservation techniques overlap with `@demeter/preservation` | | Sophia | Culinary research and knowledge base can surface through `@hestia/education` | | Yemaya | Professional recipe development tools in `@hestia/professional` align with Yemaya creator tooling | | Arete | Nutrition goals in `@hestia/nutrition` complement personal health goals in `@arete/goals` | | Annapurna | Owns restaurant and commercial food-service operations; Hestia owns consumer/home culinary intelligence and may provide recipe, nutrition, and smart kitchen inputs to Annapurna |