Annapurna Domain - Features

Planned Autonomous Restaurant and Culinary Operations Intelligence Platform (TODO Phase 68)

Annapurna is the planned Oshun domain for commercial food-service: menu engineering, kitchen automation, front-of-house, delivery and ghost kitchens, chains and franchises, commissaries, procurement, food safety, workforce, finance, customer intelligence, and sustainability. It is the operating system for restaurants that sell food, distinct from Hestia, which owns home cooking.

There are currently no apps/annapurna/* or libs/annapurna/* packages. This document specifies the planned Phase 68 scope: behavior, parameters, states, and acceptance criteria for each package area, so implementation can begin against a defined contract rather than a noun list.

The domain name comes from the Hindu goddess of nourishment — Annapurna (अन्नपूर्णा), "she who provides complete nourishment" — chosen because the platform aspires to close the entire commercial food loop, from raw ingredient lot to served guest.

Domain Foundation#

Three core domain objects anchor every package. They are defined below and are the contract every Phase 68 feature builds on.

The three objects were chosen because they represent the irreducible atoms of restaurant operations: something to sell (MenuItem), an act of selling it (RestaurantOrder), and the physical ingredient batch that makes it possible (IngredientLot). Every feature in every package ultimately reads or writes one of these three objects.

MenuItem — a sellable item with id, restaurantId, name, a category of appetizer | main | dessert | drink | special | bundle, a price and currency, an allergens string array, and an optional grossMarginPercent. grossMarginPercent is the field menu engineering reads and writes; it is derived from costed recipe ingredients against the current price, not entered by hand.

RestaurantOrder — an order with id, restaurantId, an items list of MenuItemId, a channel of dine_in | takeaway | delivery | catering | ghost_kitchen, and a status that advances through seven values: created → confirmed → in_prep → ready → served → delivered, with cancelled reachable from any non-terminal state. served is the terminal status for dine_in; delivered is terminal for delivery and ghost_kitchen. The channel determines which fulfilment path and which apps observe the order.

IngredientLot — a received batch of one ingredient with id, ingredientName, supplierId, receivedAt, an optional expiryDate, and a traceabilityStatus of pending | verified | hold | recalled. A lot enters pending on receipt, moves to verified once supplier documentation and a receiving temperature check pass, can be moved to hold by a manager or a failed inspection, and to recalled when a recall notice names its lot or supplier. hold and recalled lots may not be consumed by any order.

Hard Requirements#

Four platform requirements constrain every package and are non-negotiable. They exist because food-service operations carry real public-health and liability consequences — an incorrect allergen on a dish can injure a guest; a recalled ingredient that slips through to service can cause a food-safety incident; a robot station without a safety stop can injure staff. These four rules are the minimum floor the platform must maintain regardless of what any individual feature does.

1. Immutable food-safety records. Food-safety and allergen records — HACCP logs, temperature readings, sanitation checks, inspection results — become read-only the moment they are signed off. Corrections are appended as new records that reference the original; the original is never edited or deleted.
2. Lot-to-order traceability. Every IngredientLot must be linked forward to the MenuItems it was consumed in and the RestaurantOrders those items were served on. A recall must resolve, from a lot ID, to the exact list of affected orders and guests.
3. Versioned menu pricing. Every MenuItem price change retains the prior price, the cost assumptions in effect at the time, and the timestamp. grossMarginPercent is always reproducible for any historical date.
4. Robotic safety controls. Every robotic kitchen workflow exposes a safety-stop, a manual-override path, and an append-only incident log. A robot may not run a station without these wired.

@annapurna/core#

Foundation package: the primitives every other package depends on. This package is the single source of truth for entity types, ID brands, the order state machine, and the domain event contracts that other packages subscribe to.

• Entity models — restaurant, brand, location, kitchen, station, MenuItem, recipe, IngredientLot, supplier, RestaurantOrder, reservation, staff member, guest, table, inventory record, invoice, delivery, and compliance record. Each carries a stable ID type (RestaurantId, MenuItemId, OrderId, IngredientLotId, StaffMemberId).
• Event contracts — typed domain events (order.created, order.status_changed, lot.received, lot.recalled, menu.price_changed, incident.logged) that other packages and downstream domains subscribe to.
• Order state machine — the single authority for the seven-status RestaurantOrder transition graph. Rejects illegal transitions (e.g. created → served) and stamps each transition with actor and timestamp.
• Multi-tenancy — all entities are scoped by restaurantId; a brand groups restaurants for a chain. Queries are tenant-isolated by default.

@annapurna/culinary#

Culinary intelligence: turning recipes into executable, costed, allergen-aware production. This package is the domain's knowledge layer for the craft of cooking — flavor science, substitution logic, and nutritional rollups. It converts the recipe library into actionable prep plans the kitchen can execute.

• Recipe model and scaling — recipes hold ingredient quantities per yield; scaling recomputes quantities for a target cover count and rounds to practical pack sizes. Scaling tests verify a 4-portion recipe scaled to 50 produces correct totals within ingredient pack granularity.
• Flavor pairing and substitutions — a substitution graph proposes replacements when an ingredient lot is on hold or out of stock, ranked by flavor compatibility and allergen safety; a substitution that introduces a new allergen is rejected, not down-ranked.
• Allergen propagation — an item's allergens array is computed as the union of its recipe ingredients' allergens plus shared-equipment cross-contact risk; it is never narrower than the ingredient set.
• Nutrition and prep planning — per-portion nutrition is rolled up from ingredients; prep plans and mise-en-place lists are generated per station from the day's forecasted order mix.
• Batch cooking — groups recipes sharing prep steps into batches sized to equipment capacity and the forecasted demand window.

@annapurna/menu#

Menu engineering: deciding what to sell, at what price, and what to cut. The menu engineering matrix is the analytical core of this package — it turns raw sales and cost data into actionable quadrant classifications that tell operators which items to feature, re-engineer, reposition, or remove.

• Menu-engineering matrix — every MenuItem is classified each period on two axes, popularity (unit sales vs. menu average) and profitability (grossMarginPercent vs. menu average), into one of four quadrants: Stars (high popularity, high margin — protect and feature), Plowhorses (high popularity, low margin — re-engineer cost or raise price carefully), Puzzles (low popularity, high margin — reposition, rename, or re-plate), and Dogs (low popularity, low margin — candidates for removal).
• Price testing — a price test changes one item's price for a defined cohort or period and measures the unit-sales and margin delta against a control. A test holds the prior price as the control baseline and respects the versioned-pricing requirement so every test is reproducible.
• Contribution margin — per-item contribution (price minus plate cost) and menu-mix-weighted total contribution drive recommendations; recommendations cite the cost assumptions used.
• Seasonal and regional menus — items carry availability windows; regional localization swaps items and prices per location while preserving allergen and costing logic.
• Bundles — category: 'bundle' items compose other items; bundle margin is computed from component costs, and a bundle inherits the union of component allergens.

@annapurna/kitchen#

Commercial kitchen design, equipment, and workflow management. This package models the physical kitchen as an engineered system: equipment is specified from the menu's volume, the layout is optimized for the cooking workflow, and maintenance schedules are tracked for compliance.

• Workflow-based layout — the kitchen is laid out along the receiving → storage → prep → cooking → plating → service flow, with station adjacency optimized to minimize cross-traffic.
• Equipment, ventilation, and utilities — equipment is specified from the menu's volume; the package sizes Type I/Type II ventilation, refrigeration, plumbing, and electrical load for that equipment set.
• Maintenance scheduling — preventive maintenance is scheduled per equipment type and logged for compliance.

@annapurna/restaurant#

Restaurant and kitchen space intelligence. Where @annapurna/kitchen handles equipment and workflow, this package models the spatial constraints — how a dining room and kitchen are laid out to serve target cover counts safely and profitably.

• Kitchen layout — station placement is checked against safety clearances, equipment footprints, and traffic-flow lanes; the planner flags clearances below code minimums rather than silently accepting them.
• Dining-room layout — table mix and capacity are modeled against target cover counts; the planner reports seated capacity and turn potential per layout.
• Equipment dependencies — each station declares energy and water dependencies so layout changes surface utility-load and plumbing impacts.

@annapurna/robotics#

Kitchen automation and robotic cooking — governed by hard requirement 4. This package translates recipes into robot instruction sets, orchestrates multi-robot kitchen coordination, and enforces the safety prerequisites that must be in place before any robot station can operate.

• Recipe-to-robot translation — a recipe is compiled into an ordered robot instruction set for a station; instructions reference calibrated tool offsets and timings.
• Safety-stop — every robotic station exposes a safety-stop that halts motion immediately and transitions the station to a stopped state requiring explicit operator clearance to resume. A station with no wired safety-stop cannot be commissioned.
• Manual override — an operator can pre-empt a robot mid-cycle and complete the step by hand; the override is recorded with actor, station, and reason.
• Incident log — collisions, aborts, calibration failures, and overrides are written to an append-only incident log; entries are never edited.
• Calibration and cleaning cycles — stations run scheduled calibration and cleaning cycles; a robot may not start a food cycle while a calibration is overdue.
• Queueing and fallback — when robotic capacity is saturated or a station is stopped, orders fall back to a manual prep queue rather than stalling.

@annapurna/foh#

Front-of-house operations. This package manages everything that happens in the dining room and at the point of guest contact: reservations, seating, order pacing, and the shift-to-shift continuity that ensures guests have a consistent experience regardless of which server they interact with.

• Reservations and waitlist — reservations hold a party size, time, and table preference; the waitlist estimates wait from current table turns and promotes parties as tables free.
• Seating and host workflow — seating assigns parties to tables honoring server-section balance; the host view shows table status (open, seated, dirty, reserved).
• Service timing — order flow tracks course pacing per table; servers are alerted when a table's RestaurantOrder sits in in_prep or ready beyond a per-course threshold.
• Guest notes, complaints, tips, handoff — guest notes persist across visits; complaints are logged against an order; tips are attributed per server; shift handoff transfers open tables and notes to the incoming server.

@annapurna/boh#

Back-of-house operations — prep, cooking, plating, cleaning, and inventory. This package is the home for non-robotic back-of-house workflow; prep and batch cooking, cooking and cleaning automation, and inventory are handled in @annapurna/culinary, @annapurna/robotics, and @annapurna/supply respectively, and @annapurna/boh covers the manual back-of-house steps that sit between them.

@annapurna/delivery#

Delivery and last-mile operations for the delivery order channel. This package handles everything from the moment a delivery order is confirmed — packaging selection, route optimization, handoff confirmation, and quality logging — and integrates with the autonomous-vehicle fleet described in the phase-68 detail.

• Packaging — packaging is selected per item to hold temperature and structural integrity for the estimated transit time.
• Dispatch and routing — orders are dispatched to drivers and batched when drop-offs are geographically close and within a freshness window; routing optimizes the batched stop sequence.
• Last-mile timing — promised delivery time combines prep time, dispatch wait, and route ETA; the order advances to delivered only on confirmed handoff.
• Delivery quality — late, cold, or incomplete deliveries are logged and feed driver and packaging quality metrics.

@annapurna/ghost#

Ghost kitchen and cloud kitchen operations for the ghost_kitchen order channel. Ghost kitchens multiply revenue per square foot of kitchen by running several delivery-only brands out of one physical space; this package ensures that shared resources are fairly allocated and that brand separation is maintained at the order and menu level.

• Cloud-kitchen brands — one physical kitchen runs multiple delivery-only brands; each brand has its own menu, and orders carry the brand identity.
• Station allocation — shared stations are allocated across brands by forecasted demand to avoid one brand starving another at peak.
• Marketplace channels — orders arriving from third-party marketplaces are normalized into RestaurantOrder with channel: 'ghost_kitchen' and tracked through the standard status graph.

@annapurna/chain#

Multi-unit and franchise management. Chains and franchises share the challenge of maintaining brand consistency across many independently operated locations. This package provides the publishing, reporting, and expansion tooling that makes it possible to grow a brand without losing control of quality or compliance.

• Brand standards — recipes, menus, and procedures are published from the brand to member restaurants; per-location deviations are tracked as exceptions.
• Franchise reporting — sales, prime cost, and compliance roll up from each franchised location to the brand; franchisees see their own data, the franchisor sees the portfolio.
• Expansion playbooks — opening a new unit follows a templated checklist spanning layout, equipment, hiring, and menu localization.

@annapurna/commissary#

Central kitchen and commissary operations. A commissary centralizes production of high-volume components so that individual restaurants can maintain quality and consistency without each replicating the full production effort. This package manages that central production loop and the transfer of prepped goods to downstream restaurants — while preserving IngredientLot traceability across the hop.

• Central production — the commissary produces prepped components in bulk; production batches are sized to aggregate downstream restaurant demand.
• Transfer orders — prepped goods move to restaurants on transfer orders; each transfer carries IngredientLot references so traceability survives the hop from commissary to restaurant.
• Quality consistency — commissary output is QA-checked so every restaurant receives the same spec.

@annapurna/supply#

Procurement, inventory, and ingredient cost management. This package is the gateway for ingredients entering the system: every received IngredientLot begins here, and cost changes flowing out of this package are what make grossMarginPercent accurate across the rest of the domain.

• Procurement and vendor scoring — purchase plans are generated from par levels and forecasted demand; vendors are scored on price, fill rate, on-time delivery, and quality rejection rate.
• Receiving — received goods create IngredientLot records in pending; receiving captures quantity, temperature, and supplier documentation, which must pass before the lot moves to verified.
• Inventory and expiry — stock counts reconcile against system quantities; lots approaching expiryDate are surfaced for use-first or markdown, and expired lots are blocked from consumption.
• Costing — ingredient costs feed recipe plate costs and therefore grossMarginPercent; cost changes are versioned alongside menu prices.
• Traceability and waste — each lot's consumption is recorded against menu items and orders (hard requirement 2); waste is tracked by lot and reason.

@annapurna/safety#

Food safety, HACCP, and compliance — governed by hard requirement 1. This package is the owner of the IngredientLot traceabilityStatus lifecycle and the enforcer of immutability for all signed-off safety records. It is the compliance backbone of the domain.

• HACCP plans — hazard analysis and critical control points are modeled per recipe and process; each critical control point declares a monitored limit.
• traceabilityStatus lifecycle — the package owns the IngredientLot pending → verified → hold → recalled transitions: receipt creates pending; a passed receiving check and supplier documentation move it to verified; a manager action or failed inspection moves it to hold; a recall notice moves it to recalled. hold and recalled lots are barred from consumption.
• Temperature logs and thresholds — cold storage, hot holding, and cook temperatures are logged against thresholds (cold-chain at or below the safe ceiling, hot holding at or above the safe floor, cook temperature meeting the per-product minimum). A reading outside its threshold raises an alert and may trigger a hold.
• Immutability after signoff — once a HACCP log, temperature reading, sanitation check, or inspection result is signed off it is read-only; a correction is a new appended record referencing the original.
• Recalls — a recall names lots or suppliers, transitions matching lots to recalled, and resolves through lot-to-order traceability to the exact affected orders and guests.
• Allergen controls and audit trails — allergen handling procedures are tracked per station; every safety record carries an immutable audit trail of who recorded it and when.

@annapurna/staff#

Workforce management and labor planning. Labor is typically 30–35% of revenue in full-service restaurants; getting schedules right — matching demand, covering every station with qualified staff, and staying within budget — is one of the primary levers operators have on profitability.

• Scheduling — shifts are scheduled against forecasted demand and labor-cost targets; the scheduler respects skill coverage so every station has a qualified worker.
• Skills and training — staff carry skill and certification records; training completion gates assignment to skill-restricted stations.
• Labor cost — scheduled labor cost is projected and compared to the labor-cost-percentage target; overruns are flagged before the schedule is published.

@annapurna/finance#

Restaurant financial intelligence. This package translates operational data — ingredient costs, labor, sales — into the financial statements and reconciliation reports operators and investors use to evaluate restaurant health.

• COGS and prime cost — cost of goods sold is rolled up from consumed IngredientLot costs; prime cost combines COGS and labor and is reported against target.
• P&L and cash flow — per-location profit and loss and cash-flow projections are built from sales, prime cost, and operating expenses.
• Margin reconciliation — actual food cost is reconciled against theoretical cost derived from recipe costing, surfacing waste and shrinkage.

@annapurna/customer#

Guest CRM and analytics. Understanding guests — their preferences, allergens, visit cadence, and lifetime value — is what separates a reactive restaurant from one that can personalize service, anticipate demand, and retain guests over time.

• Guest profiles and loyalty — guest profiles carry visit history, preferences, and allergen flags; loyalty tracks points and rewards across visits and channels.
• Feedback — feedback and complaints are tied to orders and items, feeding menu-engineering and quality signals.
• Lifetime value and demand forecasting — guest lifetime value is computed from visit frequency and spend; aggregate guest behavior feeds the demand forecasts that drive scheduling, procurement, and batch cooking.

@annapurna/sustainability#

Waste, sourcing, and environmental signals. Food waste is both a financial and an environmental problem — a restaurant wasting 10% of its food is losing margin and generating unnecessary emissions. This package quantifies that waste, tracks sourcing attributes, and surfaces per-item environmental signals so operators can make informed menu and purchasing decisions.

• Food-waste reduction — waste logged by @annapurna/supply is analyzed by cause (spoilage, over-prep, plate waste) and feeds par-level and batch-size corrections.
• Sustainable sourcing — supplier and ingredient sourcing attributes (local, certified, seasonal) are tracked per IngredientLot.
• Carbon and water signals — per-menu-item carbon and water estimates are derived from ingredient sourcing and surfaced for menu decisions.

@annapurna/ai#

AI and ML engine supporting other packages — not a standalone product surface. This package provides the predictive models that make the rest of the domain proactive rather than reactive: demand forecasts feed scheduling and procurement before the shift starts, menu optimization surfaces recommendations before margins deteriorate.

• Demand forecasting — forecasts order volume and item mix per location and daypart; consumed by scheduling, procurement, and batch cooking.
• Menu optimization — recommends price, placement, and removal moves from the menu-engineering matrix and price-test results.
• Quality anomaly detection — flags anomalies in temperature logs, delivery timing, and food-cost variance for human review.

@annapurna/apps#

The application suite — three apps that surface the platform to the people who use it. All three are planned to live inside libs/annapurna/apps/ rather than as standalone apps/annapurna/* projects.

• Customer app — a guest-facing mobile app for menu browsing with allergen filtering, ordering and checkout, real-time order tracking, in-app reservation booking, and a loyalty interface.
• Kitchen Management app — the kitchen display system (KDS) tablet app, a kitchen-manager dashboard, and a prep-management app for station-level order flow, ticket timing, and prep tracking.
• Delivery Fleet app — a fleet-monitoring dashboard, a human-courier app, and a robot remote-operation interface for the delivery vehicle fleet.

@annapurna/integration#

Cross-domain integration hub. Annapurna does not duplicate facts owned elsewhere; it links to them. Each integration boundary below exists because the adjacent domain is the authoritative source for its subject — re-modeling those facts inside Annapurna would create two competing sources of truth.

• Hestia — consumer recipe and nutrition data feeds Annapurna menus; Annapurna operational data informs Hestia restaurant-grade techniques. The boundary is the point of sale: household cooking is Hestia, commercial food-service is Annapurna.
• Demeter and Asase — agriculture and ingredient supply-chain facts; Annapurna procurement links to them rather than re-modeling supply. Asase is the authoritative source for farm-level traceability; Annapurna picks up the chain at the receiving dock.
• Brigid — industrial kitchen automation equipment and maintenance; @annapurna/robotics integrates with Brigid for equipment-level concerns. Brigid owns the hardware layer; Annapurna owns the food-service-specific control and safety layer on top.
• Cybele — restaurant real estate and kitchen/facility construction; @annapurna/restaurant links space intelligence to Cybele. Cybele owns the built environment; Annapurna owns the operational use of that space.
• Maat — financial rollups; @annapurna/finance feeds Maat for cross-domain financial reporting. Annapurna owns restaurant-level financial intelligence; Maat consolidates across domains.

Relationship to Hestia#

Hestia owns consumer cooking, recipes, nutrition, meal planning, and smart-kitchen intelligence for the home. Annapurna owns commercial food-service and restaurant operations. The boundary is the point of sale: a household preparing a meal is Hestia; a business selling that meal is Annapurna. Hestia recipes and nutrition can feed Annapurna menus; Annapurna operational data can inform Hestia restaurant-grade techniques and sourcing.

Implementation Status#

There is no current apps/annapurna/* or libs/annapurna/* implementation; this document is planned-scope only. When packages are created, each section above becomes the acceptance contract for its package, and the domain's architecture and specification documents must be updated with concrete persistence schemas, service contracts, and test gates.