Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.laportenard.com/llms.txt

Use this file to discover all available pages before exploring further.

The Kitchen Display System (KDS) replaces paper tickets with a real-time screen in the kitchen. Orders appear as ticket cards when sent from the POS, and kitchen staff bump items or full orders as they finish them. Bump state syncs back to POS terminals so servers see a “ready” badge on the floor plan.

​
Prerequisites

  • Hub sync enabled (nu_hub_enabled on nu.pos.config) — KDS requires real-time order snapshots via WebSocket
  • At least two POS terminals configured under the same shared config: one for order-taking, one for the kitchen display

​
Setup

1

Configure the KDS terminal in Odoo

Go to Point of Sale > Configuration > Point of Sale and open the terminal you want to designate as a kitchen display.Under the Configuracion NU POS tab, find the Modo de Terminal radio group and select Pantalla de Cocina (KDS).
2

Open a POS session on the KDS terminal

Log in to the POS on the KDS terminal and open a session as usual. The app detects nu_terminal_mode = "kds" from the bootstrap config and auto-redirects to /kds/.
3

Start taking orders on POS terminals

On regular POS terminals, create orders and send them to the kitchen (the “Send” button that transitions status to sent). Orders appear on the KDS within seconds via the hub.
The KDS terminal must be under the same nu.pos.config shared configuration as the order-taking terminals so they share the same hub and see the same orders.

​
How it works

​
Ticket lifecycle

Orders appear on the KDS when their kitchen status is sent or changed and they have not been bumped (kitchenBumpedAt is null). The flow:
  1. Order sent — POS terminal sends order to kitchen. Items are stamped with kitchenItemStatus: "pending". Order appears as a ticket card on the KDS.
  2. Item bump — Kitchen staff taps an individual item to mark it done (green checkmark). The bump counter on the ticket updates.
  3. Order bump — Kitchen staff taps the “BUMP” button at the bottom of the ticket. The order is stamped with kitchenBumpedAt and moves to the recall strip.
  4. Recall — Bumped orders appear in a bottom strip for 30 seconds. Tapping recalls them back to the grid (clears kitchenBumpedAt).
  5. Sync back — Bump state flows through the hub snapshot pipeline back to all POS terminals. A green checkmark badge appears on the table in the floor plan.

​
Ticket urgency

Tickets change color based on elapsed time since the order was sent:
Elapsed timeUrgencyVisual
< 5 minutesNormalGreen timer, standard border
5–10 minutesWarningAmber timer, amber border with glow
> 10 minutesCriticalRed timer, red border with pulse animation

​
Change detection

When a POS terminal modifies a sent order (adds/removes items, changes quantities), the order status flips to changed and:
  • The ticket gets a MOD badge and an amber ring highlight
  • kitchenBumpedAt is cleared, so bumped orders reappear on the grid
  • Added items show a green left border
  • Changed quantities show the old and new values

​
Ready badge on floor plan

When an order is bumped on the KDS, POS terminals show a green checkmark badge on the corresponding table in the floor plan. The badge:
  • Appears when kitchenBumpedAt is set on the order
  • Can be dismissed by tapping it (local state only, does not affect the order)
  • Auto-resets when the order is modified (the badge reappears after the next bump)

​
Audio alerts

The KDS plays audio cues for two events:
EventSoundBehavior
New order arrivesnew-order.mp3Plays once per new order (not on initial page load)
First order goes criticaloverdue.mp3Plays once, resets when all orders drop below critical
Audio files are at nu_pos_react/public/sounds/. Replace the placeholder files with actual notification sounds.

​
Data flow

KDS reuses the existing hub sync pipeline — no new protocol message types. Two fields carry bump state:
FieldLevelTypePurpose
kitchenItemStatusOrder item"pending" | "done"Individual item bump state
kitchenBumpedAtOrdernumber (timestamp)When the full order was bumped
These fields flow through:
  • Sync protocol — Zod schemas in nu_pos_sync_protocol (validated, not stripped)
  • Hub snapshots — ORDER_SNAPSHOT and SYNC_INIT messages
  • Backend — Persisted as nu_kitchen_item_status (Selection) and nu_kitchen_bumped_at (Datetime) on Odoo models
  • Direct API — Included in order create/update payloads for non-hub setups

​
Odoo configuration reference

FieldModelTypePurpose
nu_terminal_modepos.configSelection"standard" (default) or "kds"
nu_kitchen_item_statuspos.order.lineSelection"pending" or "done"
nu_kitchen_bumped_atpos.orderDatetimeTimestamp of last order bump

​
Source files

# Domain
src/domain/kds/constants.ts          # Urgency thresholds, recall duration
src/domain/kds/models.ts             # KDSTicket, RecalledTicket types
src/domain/kds/selectors.ts          # filterKDSOrders, computeTicketUrgency
src/domain/kds/selectors.test.ts     # 10 tests

# UI components
src/features/kds/screens/KDSScreen.tsx           # Main screen
src/features/kds/components/ticket-grid.tsx       # Horizontal ticket grid
src/features/kds/components/ticket-card.tsx       # Individual ticket card
src/features/kds/components/ticket-item.tsx       # Item row within a ticket
src/features/kds/components/recall-strip.tsx      # Bottom recall strip
src/features/kds/components/kds-header.tsx        # Header with stats and clock
src/features/kds/hooks/useKDSAudio.ts             # Audio alert hook
src/features/kds/hooks/useTicketDiff.ts           # Change diff detection

# Route
src/app/kds/page.tsx                 # Next.js /kds route

# Backend
nu_restaurant_pos/models/pos_config.py            # nu_terminal_mode field
nu_restaurant_pos/models/pos_order.py             # nu_kitchen_bumped_at field
nu_restaurant_pos/models/pos_order_line.py        # nu_kitchen_item_status field
nu_restaurant_pos/models/pos_bootstrap_data.py    # Bootstrap payload