# Annapurna — Systems Deep Dive

> 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.