Eve library

Annapurna — Systems Deep Dive

Guide

Revision 1

On this page

The libs/annapurna/ area: twenty-one Nx libraries implementing the autonomous restaurant and culinary operations domain — a @annapurna/core foundation of primitives plus a fan of domain engines for kitchens, menus, delivery, finance, safety, and more.

What this area is#

Annapurna is the food-service / restaurant-operations domain of the Oshun monorepo. Every library here is tagged scope:annapurna, layer:domain, type:lib, and is published under the @annapurna/* npm scope. The area is organised as one foundation package plus twenty domain packages, each owning a slice of running a restaurant: forecasting, recipes and flavor science, menu engineering, front- and back-of-house, robotics, delivery, supply, finance, staff, safety, sustainability, multi-unit chains, ghost kitchens, and the cross-domain integration hub.

@annapurna/core (libs/annapurna/core) is the shared substrate the rest build on. It is unusual in the area: instead of an engines.ts, it carries branded ID types with runtime-validated constructors (src/ids.ts), the domain's enums and union types (src/types.ts, ~1000 lines), Zod schemas (src/schemas.ts), a 6500-line culturally-grounded cuisine taxonomy (src/taxonomy.ts, opening with West African, Ghanaian Ashanti, and Sicilian profiles), a Postgres table catalog (src/db-schema.ts) backed by a real Drizzle migration (drizzle/0001_annapurna_foundation.sql enabling postgis, timescaledb, and vector), and the REST + GraphQL API surface (src/api.ts). The domain engines import from it (e.g. @annapurna/core's FlavorProfile and Money are used across ai, culinary, supply).

The twenty domain packages share a consistent shape. Each src/index.ts exports a small capability registry (a typed ANNAPURNA_<NAME>_CAPABILITIES array with listAnnapurna<Name>Capabilities / hasAnnapurna<Name>Capability accessors) and then re-exports ./types and ./engines. The real work lives in src/engines.ts — pure, deterministic, domain-specific functions (demand forecasting with weather/event/holiday lift, aroma-chemistry flavor pairing, FEFO lot picking, prime-cost flash reports, HACCP plans) — with src/types.ts holding the input/output records and a co-located *.test.ts.

A note on the two thin nodes#

Two packages — @annapurna/boh and @annapurna/kitchen — are honest scaffolds. Each is ~45 lines: only the capability-registry boilerplate in src/index.ts declaring a single :foundation capability whose evidence is the project files themselves, with no engines.ts and no types.ts. They reserve the back-of-house and kitchen-design slots in the catalog but contain no implemented domain logic yet, and are labelled as such below rather than overclaimed.

How it fits the wider system#

Consumers compose these libraries the way a restaurant platform would: a service or app imports @annapurna/core for IDs, schemas, and the REST/GraphQL contract, then pulls the specific engine packages it needs (e.g. @annapurna/foh for POS and reservations, @annapurna/menu for pricing, @annapurna/delivery for last-mile). The engines are deliberately pure functions over typed inputs, so they are runtime-agnostic and easy to wire behind the REST/GraphQL operations catalogued in core/src/api.ts. @annapurna/integration is the seam to the rest of the monorepo: it adapts sibling domains (Hestia, Asase, Brigid, Oya, Seshat, Athena, Freya, Maat, Psyche) into Annapurna's restaurant model rather than letting each domain reach into the others directly. Walk the dependency edges on any node below to see exactly which packages it composes with.

Entity reference#

@annapurna/core#

The foundation package (libs/annapurna/core) and the only node without an engines.ts. It owns branded ID types and validating constructors (src/ids.ts, prefixes like rest, menu, ord), the domain enum/union vocabulary (src/types.ts — RestaurantConcept, KitchenStationName, DietaryTag, …), Zod schemas (src/schemas.ts), a 6500-line cuisine taxonomy with flavor profiles (src/taxonomy.ts), the Postgres table catalog (src/db-schema.ts) plus a real Drizzle migration enabling postgis / timescaledb / vector, and the REST endpoint list and GraphQL SDL (src/api.ts). Every other Annapurna engine imports its primitives.

@annapurna/ai#

The ML/analytics engine suite (libs/annapurna/ai/src/engines.ts, "AI and ML engine for forecasting, quality, and recommendations"). It implements real domain algorithms: forecastDemand (baseline covers adjusted by weather/event/holiday/promotion lift with a confidence interval and safety stock), assessPlateQuality, recommendCustomerMenuItems, optimizeDynamicPrice, optimizeKitchenEfficiency, analyzeReviewSentiment (keyword/sentiment lexicons per insight category), optimizeDeliveryRoutes, and predictFoodTrends. Inputs and outputs are fully typed in src/types.ts.

@annapurna/apps#

Customer-facing and operations app-state builders (libs/annapurna/apps, "Customer-facing and operations mobile/web app contracts"). The engines assemble view-model state for concrete app surfaces: buildCustomerMobileAppState, buildOrderTrackingState, bookReservationInApp, buildLoyaltyProgramInterface, buildArMenuPreview, buildKdsTabletApp, buildKitchenManagerDashboard, buildPrepManagementApp, buildDeliveryFleetDashboard, buildHumanCourierApp, and buildRobotRemoteOperationInterface. It is the presentation-contract layer over the other domains' engines.

@annapurna/boh#

Back-of-house slot — a thin scaffold. libs/annapurna/boh/src/index.ts is only the capability-registry boilerplate (ANNAPURNA_BOH_CAPABILITIES with a single boh:foundation entry whose evidence is the project files), with no engines.ts and no types.ts. The package description ("prep, cooking, plating, cleaning, and inventory") states the intended scope, but no domain logic is implemented here yet.

@annapurna/chain#

Multi-unit and franchise management (libs/annapurna/chain/src/engines.ts). Real engines: buildMultiUnitDashboard (aggregates per-location KPI inputs), enforceMenuConsistency, planCentralizedProcurement, manageFranchiseUnits, analyzeNewLocations, and createStoreOpeningPlaybook. It is the package for operating a brand across many physical units.

@annapurna/commissary#

Central-kitchen / commissary operations (libs/annapurna/commissary/src/engines.ts). Implements planCentralKitchenProduction, scaleBatchRecipe, planCommissaryDistribution, planCookChillProduction, and buildCommissaryHaccpPlan — the production-and-distribution backbone for a hub kitchen that supplies multiple outlets.

@annapurna/culinary#

Culinary intelligence and recipe/flavor science — one of the largest nodes (~2700 lines, libs/annapurna/culinary/src/engines.ts). It covers recipe lifecycle (scaleRecipe with DEFAULT_SCALING_RULES, standardizeRecipeForCommercialKitchen, createRecipeVersion, compareRecipeVersions), flavor science (predictFlavorPairings scoring shared aroma compounds and complementary taste dimensions, optimizeTasteBalance, optimizeMaillardReaction, planFermentation, planMolecularTechnique, formulateSpiceBlend, deriveSauce over a mother-sauce system), and nutrition (calculateRecipeNutrition, buildAllergenMatrix, optimizeRecipeMacros, suggestIngredientSubstitutions). It draws on @annapurna/core's flavor taxonomy.

@annapurna/customer#

Customer intelligence, loyalty, and CRM (libs/annapurna/customer/src/engines.ts). Implements buildCustomerDataPlatform, segmentCustomers, recommendMenuItems, predictChurnAndRetention, and calculateCustomerLifetimeValue — the CDP and retention-analytics layer over guest data.

@annapurna/delivery#

Delivery operations, autonomous vehicles, and last-mile logistics — a large node (libs/annapurna/delivery/src/engines.ts). It spans robot and drone hardware (specifyDeliveryRobot, createAutonomousNavigationStack, createOyaFoodDroneAdapter, calculateDroneDeliveryZone, manageDroneLandingPads, planDroneGroundHandoff), fleet and routing (planDeliveryRoute, manageRobotFleet, optimizeDeliveryDispatch, batchDeliveryOrders, estimateDeliveryTime), and operational concerns (manageThermalCompartments, planChargingInfrastructure, createDeliveryRobotSafetyPlan, adaptDeliveryForWeather, scoreDeliveryQuality, manageSurgeDeliveryDemand). The Oya adapter is its tie-in to the aerial-delivery domain.

@annapurna/finance#

Restaurant financial management and analytics (libs/annapurna/finance/src/engines.ts). Implements buildRestaurantProfitLoss, buildPrimeCostFlashReport, buildBreakEvenAnalysis, manageCashFlow, buildNewRestaurantFinancialModel, and analyzeDeliveryProfitability — the industry-standard prime-cost / break-even / pro-forma toolkit for food-service P&L.

@annapurna/foh#

Front-of-house operations (libs/annapurna/foh/src/engines.ts): POS, reservations, and guest experience. It implements createPosCheckSession, routeKitchenDisplayTickets, aggregateOrderChannels, throttleOrdersForKitchenCapacity, createTablesideOrderingSession, createSelfServiceKioskFlow, reservation/waitlist/floor-plan engines (createReservationBookingPlan, buildTableFloorPlan, manageWaitlist, optimizeTableTurns, configureDynamicTables), and guest-relations engines (buildGuestProfileBrief, collectGuestFeedback, calculateLoyaltyAccount, suggestUpsells, manageReviewWorkflow).

@annapurna/ghost#

Ghost / cloud-kitchen operations (libs/annapurna/ghost/src/engines.ts). Implements designGhostKitchenFacility, createVirtualBrand, analyzeVirtualBrandPerformance, optimizeSharedKitchenResources, optimizeGhostKitchenLocation, and createKitchenAsAServiceModel — the delivery-only, multi-brand-per-kitchen business model.

@annapurna/integration#

The cross-domain integration hub (libs/annapurna/integration). Beyond the standard capability registry it ships a full engines.ts of adapters that bridge sibling Oshun domains into Annapurna's restaurant model: Hestia recipe intelligence and meal planning, Asase farm-to-restaurant supply chain, Brigid kitchen automation / refrigeration / energy, Oya aerial and ground delivery, Seshat restaurant design, Athena furniture, Freya textiles, Maat business operations, and Psyche customer interaction. It is the seam that keeps the other domain packages from depending on each other directly.

@annapurna/kitchen#

Kitchen design/equipment slot — a thin scaffold, mirroring @annapurna/boh. libs/annapurna/kitchen/src/index.ts is only the capability-registry boilerplate (ANNAPURNA_KITCHEN_CAPABILITIES with a single kitchen:foundation entry), with no engines.ts and no types.ts. The description ("kitchen design, equipment, and workflow management") reserves the scope, but no logic is implemented here yet. (Note: physical kitchen-layout and equipment engines actually live today in @annapurna/restaurant.)

@annapurna/menu#

Menu engineering, pricing, and innovation (libs/annapurna/menu/src/engines.ts). Implements the classic menu-engineering matrix (classifyMenuEngineering → stars/plowhorses/etc., analyzeMenuMix), pricing (recommendMenuPrice, calculateDynamicPrice, costRecipePortion, analyzeMenuItemProfitability, trackFoodCostVariance), layout and copy (optimizeMenuLayout, generateMenuDescriptions), and lifecycle engines (planSeasonalRotation, engineerKidsMenuItem, engineerBeverageMenu, createPortionControlSpec, summarizeWaste).

@annapurna/restaurant#

Restaurant design, ambiance, and physical-space management (libs/annapurna/restaurant/src/engines.ts) — a broad node. It covers front-of-house design (designRestaurantConcept, optimizeDiningRoomLayout, designBiophilicRestaurant, designRestaurantLighting, designRestaurantAcoustics, designOpenKitchen, designBarLounge, designOutdoorDining, designRestaurantRestrooms, designFoodTruckOrPopup) and, notably, the commercial-kitchen engineering (planCommercialKitchenLayout, specifyKitchenEquipment, designKitchenVentilation, specifyRefrigeration, specifyPlumbing, planElectricalLoad, specifyKitchenFlooring, scheduleEquipmentMaintenance) that the @annapurna/kitchen scaffold does not.

@annapurna/robotics#

Kitchen automation and robotic cooking (libs/annapurna/robotics/src/engines.ts) — the largest engine surface by function count. It plans station controllers (createWokControllerPlan, createGrillPlanchaControllerPlan, createFryerControllerPlan, createPizzaAssemblyLinePlan, createSushiAssemblyPlan, createSaladBowlAssemblyPlan, createBeveragePreparationPlan, createPastryDessertAssemblyPlan), orchestrates multi-robot kitchens and prep (orchestrateMultiRobotKitchen, createRobotSanitizationCycle, createIngredientDispensingPlan, generatePrepListFromForecast), and provides computer-vision/IoT monitoring (inspectPlateQuality, monitorFoodSafetyVision, detectCookingCompletion, monitorKitchenEquipmentIot, monitorKitchenEnergy, monitorKitchenAirQuality, senseAutomatedInventory).

@annapurna/safety#

Food safety, HACCP, and health compliance (libs/annapurna/safety/src/engines.ts). Implements buildHaccpPlan, evaluateTemperatureMonitoring, buildInspectionReadinessReport, trackEmployeeHealthCompliance, buildAllergenManagementProtocol, scheduleCleaningAndSanitization, managePestControlProgram, and buildRecallResponsePlan — the regulatory and food-safety compliance toolkit.

@annapurna/staff#

Workforce management, scheduling, and training (libs/annapurna/staff/src/engines.ts). Implements planStaffSchedule, distributeTips, assignKitchenBrigade, manageTrainingProgram, calculateLaborCostAnalytics, and buildKitchenSkillsMatrix — labor scheduling, tip pooling, brigade assignment, and labor-cost analytics.

@annapurna/supply#

Food-service procurement and inventory (libs/annapurna/supply/src/engines.ts). Implements supplier management (buildFoodServiceSupplierDatabase, compareSupplierPrices, inspectReceivingDelivery, planFarmToTableSourcing), purchasing (generateParLevelPurchaseOrders), and real inventory algorithms (computePerpetualInventory, enforceFefo — first-expiry-first-out lot picking sorted by expiry with menu-special/staff-meal disposition, buildShelfLifeManagementPlan, buildWeeklyWasteReport, calculateFoodCostAccounting).

@annapurna/sustainability#

Food-waste reduction and sustainability tracking (libs/annapurna/sustainability/src/engines.ts). Implements trackFoodWasteReduction, calculateMenuItemCarbonFootprint, buildSustainableSourcingScorecard, trackEnergyEfficiency, planPackagingReduction, and trackWaterConservation — the environmental metrics layer over the operational domains.