The
libs/annapurna/area: twenty-one Nx libraries implementing the autonomous restaurant and culinary operations domain — a@annapurna/corefoundation 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.