---
name: stilldeep-pos-screen
description: Builds a point-of-sale screen (touch register, self-service kiosk, web shop, tablet) on the StillDeep engine through its public stilldeep.v1 gRPC contract. Use when the user wants to create or change a StillDeep POS client, mentions StillDeep or stilldeep.v1, or asks to vibe-code a register on a headless point of sale.
license: Proprietary
metadata:
  publisher: StillDeep
  version: "1.0"
---

# Build a StillDeep point-of-sale screen

StillDeep is a headless point of sale. The register engine already does the business logic (sales, taxes, discounts,
payments, refunds, reservations), the security, the reports and the communication (offline outbox, sync with the
business server). You build the screen only. Keep every business rule out of the client: the engine and the server
re-check everything anyway.

## Read first

- Documentation index: https://stilldeeppos.com/llms.txt. Every page also exists in Markdown: add `.md` to its path.
- Read-only docs over MCP: `https://stilldeeppos.com/mcp`.
  - Claude Code: `claude mcp add --transport http stilldeep https://stilldeeppos.com/mcp`
  - Codex (`~/.codex/config.toml`): `[mcp_servers.stilldeep]` then `url = "https://stilldeeppos.com/mcp"`
  - Tools: `search_docs`, `read_page`, `list_pages`, `get_contract`.
- The contract, one file at a time in plain text: `https://stilldeeppos.com/contracts/<file>.proto` (`sales.proto`, `catalog.proto`,
  `shift.proto`, `user.proto`, `events.proto`, ...). All files: https://stilldeeppos.com/downloads/stilldeep-contracts.zip.
- Step-by-step guide: https://stilldeeppos.com/docs/build-a-client.md

## Steps

1. Generate a gRPC client for package `stilldeep.v1` with the official tools of the language: TypeScript
   (`@grpc/grpc-js` with `ts-proto`), Python (`grpcio-tools`), Go (`protoc-gen-go`, `protoc-gen-go-grpc`), .NET, Java,
   Kotlin, Rust (official generators).
2. Connect to the register engine on the register itself: HTTP/2, `localhost:50051` by default. The screen never calls
   the business server; the register handles the proxy, the outbox and offline mode.
3. Sign the employee in with `UserService.Authenticate` (if `must_change_password` is true, show `ChangePassword`
   first), then open a shift with `ShiftService.OpenShift` (post, user, opening cash, idempotency key). Send the shift
   id as gRPC metadata `x-shift-id` on every following call.
4. Sell:
   - `SalesService.CreateCart`, then `AddItem` (find products with `CatalogService.GetProductByBarcode` or
     `SearchProducts`); quantities may be decimal for weighed goods.
   - Optional: `AssociateMember`, `ApplyDiscount`, `UpdateQuantity`, `RemoveLine`.
   - If the cart carries a pending question (`pending_interactions`), ask the cashier and answer with
     `ResolveInteraction`.
   - `BeginPayment` or `SelectPaymentMethod`, then `ProcessPayment` (call it several times to split a payment). If the
     response has a `refusal_guide`, let the cashier choose and call `ResolvePaymentRefusal`.
   - `FinalizeTransaction` once the payments cover the total, then print with `DeviceService.PrintReceipt`.
5. Subscribe once to `EventService.Subscribe`: availability of limited resources, chat messages, server decisions.
6. End of day: `ShiftService.CloseShift`; figures from `ReportService`.

## Rules

- Display what the cart returns. Never compute a price, a tax or a total in the screen.
- Money is `int64` cents, percentages are basis points, timestamps are UTC.
- Every refusal is a `google.rpc.Status` with a stable code (`shift_paused`, `stock_short`, ...). Map the code to a
  message for the cashier; never retry blindly. A refusal can arrive after the screen thought all was fine.
- Send an idempotency key on calls that create something, so a retried call never sells twice.
- The register keeps selling offline: never block the screen on network status. `SyncService.GetSyncStatus` tells the
  outbox state if you want to show it.
- Version 1 never receives a breaking change.

## Checklist before handing over

- [ ] Shift opened and `x-shift-id` sent on every call.
- [ ] A full sale works: cart, payment, finalize, receipt.
- [ ] Each refusal code shows a readable message.
- [ ] No business rule, price or tax computed in the client.