# 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 `MenuItem`s it was consumed in and the `RestaurantOrder`s 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.