/api/...`. [System overview](../architecture/overview.md#the-server-app-is-a-filtered-proxy-not-a-second-api) owns that boundary model; this section is the allowlist. Twenty-five routes in total, thirteen of which forward: | Method | Path | Forwards to | | ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------- | | `GET` | `/api/categories` | `GET /api/categories` | | `GET` | `/api/products` | `GET /api/products` | | `GET` | `/api/products/:id/image` | `GET /api/products/:id/image` | | `GET` | `/api/tables` | `GET /api/tables` | | `POST` | `/api/tables/:id/move-order` | `POST /api/tables/:id/move-order` | | `GET` | `/api/orders` | `GET /api/orders` | | `POST` | `/api/orders` | `POST /api/orders` | | `POST` | `/api/orders/:id/items` | `POST /api/orders/:id/items` | | `GET` | `/api/customers-search` | `GET /api/customers-search` | | `GET` | `/api/crm/lookup` | `GET /api/crm/lookup` | | `POST` | `/api/customers` | `POST /api/customers` | | `POST` | `/api/printers/print-kot` | `POST /api/printers/print-kot` | | `POST` | `/api/printers/print-bill` | `POST /api/printers/print-bill` (`403` `BILL_PRINTING_DISABLED` when `server_app_bill_printing_enabled` is off) | Adding a route to `3001` does not expose it on `3003`. A path becomes reachable from the Server App only when a forwarding route is added to `main/server-app.ts`. The eleven routes that are not forwards: | Method | Path | Authorization | Response | | ------ | --------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/api/health` | none | `{ status, service, version, timestamp }` | | `GET` | `/api/server-app/info` | none | `{ language, country, currency, currency_symbol, currency_position, currency_fraction_digits, kds_enabled, category_sort, item_sort }`. `404` when the feature is disabled; `409` with `error: "regional_not_configured"` when the regional snapshot cannot be resolved. | | `POST` | `/api/auth/login` | none, `loginAuthRateLimit` + shared failed-login limiter | Body `email`, `password`, `remember_me`. `{ access_token, user: { id, name, email, role, has_pin, permission_ids, authorization_revision } }`; 24 hours, or 10 days with `remember_me`. `401` on bad credentials with `attempts_remaining`; `429` after 5 failed attempts across local login listeners; `403` for a role outside `ROLE_ACCESS.serverApp`. | | `GET` | `/api/auth/pin-users` | none, auth limiter (600 per window) | `{ users: [ { id, name, role } ] }` for active users with a PIN configured who hold `server-app.use`. `404` when the feature is disabled. | | `POST` | `/api/auth/pin-login` | none, auth limiter (600 failed per window) + per-(client IP, user) failed-login limiter | Body `user_id`, `pin`, `remember_me` (or `rememberMe`). `{ access_token, user: { id, name, email, role, has_pin, permission_ids, authorization_revision } }`; 24 hours, or 10 days with remember. `404` when disabled; `400` when `user_id` or `pin` is missing; `401` on bad credentials with `attempts_remaining`; `429` after 5 failed attempts; `403` without `server-app.use`. | | `GET` | `/api/auth/me` | `ROLE_ACCESS.serverApp` | `{ user: { id, name, email, role, has_pin, permission_ids, authorization_revision } }` | | `POST` | `/api/auth/password/change` | `ROLE_ACCESS.serverApp` + auth limiter | Body `current_password`, `password`. `{ message, token }`; self-service password change with the same validation and 5-attempt lockout as `POST /api/auth/password/change` on `3001`, returning a fresh Server App token (`404` when the feature is disabled). | | `POST` | `/api/auth/pin/change` | `ROLE_ACCESS.serverApp` + auth limiter | Body `pin`, plus `current_pin` or `current_password`. `{ message, has_pin: true, token }`; self-service PIN setup or update with the same validation and 5-attempt lockout as `POST /api/auth/pin/change` on `3001`, returning a fresh Server App token (`404` when the feature is disabled). | | `POST` | `/api/auth/logout` | `ROLE_ACCESS.serverApp` | `{ success: true }`, revoking the token | | `GET` | `/` | none | Redirect to `/server-standalone` | | `GET` | `/*splat` | none | Static bundle, falling back to the `/server-standalone` page | When the frontend export is missing, the `GET /` redirect is replaced by a placeholder page instead, so `GET /` is two mutually exclusive registrations rather than two routes. `requireServerAppAuth` is applied to every route except `/api/health`, `/api/server-app/info`, and `/api/products/:id/image`, and it runs the feature check **before** the token check. Behaviour by condition: - Feature disabled: `404` with `{ error: "Not found" }`, so the surface is not advertised. - Main API unreachable: `502` with `{ error: "Could not reach the local POS API" }` from the forwarding layer. - Request aborted by shutdown: `503` with an empty body. The forwarder relays the upstream status, content type, and body verbatim, and passes the method, query string, `Authorization` header, `Idempotency-Key`, and JSON body upstream. Three limiters on `3003` run **before** authentication: 150 requests per minute across `/api`, 150 per minute on `POST /api/customers`, and 30 per minute shared by the two print forwarders. Each returns `429` when exceeded. ## KDS WebSocket (`/kds`) One connection contract, implemented once in [`main/services/kds.ts`](../../main/services/kds.ts) and served on both `:3001` and `:3002`. ### Connecting Open `ws://:/kds` on `3001` or `3002`. The upgrade handler answers before the upgrade completes: | Condition | Response | | ----------------------------------------- | ----------------------------------------------------- | | Path is not `/kds` | `404`, socket destroyed | | Database maintenance in progress | `503`, socket destroyed | | KDS disabled (`kds_enabled` off) | `404`, socket destroyed | | Disallowed `Origin` header | `403`, socket destroyed | | Total or pending connection limit reached | `429`, socket destroyed | | Otherwise | upgraded, and a `connected` frame is sent immediately | ### Handshake 1. On connect the server sends `connected`. 2. The client sends `auth` with a bearer JWT. A display must authenticate within `KDS_AUTH_TIMEOUT_MS`, 5 seconds; otherwise the server sends `auth_error` and closes with code `1008`. 3. On success the server sends `auth_success`, then sends `initial_data` as a **separate frame**. `auth_success` carries a `user` object and nothing else: ```json { "type": "auth_success", "user": { "id": "chef-1", "name": "Chef One", "role": "chef", "categoryIds": ["cat-1", "cat-2"], "stationIds": ["station-1"] } } ``` It does not carry `orders` or `counts`. A client that waits for the order list on this frame waits forever. ### Frames the server sends | Type | Carries | When | | ---------------- | ------------------------- | -------------------------------------------------------------- | | `connected` | `message`, `timestamp` | Immediately on connect | | `auth_success` | `user` (see above) | After a successful `auth` | | `initial_data` | `orders`, `counts` | After `auth_success`, and on every subsequent broadcast | | `status_updated` | `order_item_id`, `status` | After the requesting client's own `status_update` succeeds | | `pong` | `timestamp` | In reply to a `ping` | | `error` | `message` | A rejected client message or a rejected status update | | `auth_error` | `message` | Before the server closes an unauthenticated or revoked session | ### Frames the server accepts The message switch in `handleMessage` accepts exactly three types. Anything else gets `{ "type": "error", "message": "Unknown message type" }`. | Type | Fields | Notes | | --------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auth` | `token` | Only accepted before authentication. Any other type before auth closes the connection. | | `status_update` | `order_item_id`, `status`, optional `expected_status` | `status` must be one of `pending`, `preparing`, `ready`, `served`; reconciles active parent `orders.status` in the same transaction (see [Order lifecycle](../architecture/order-lifecycle.md#order-status)). | | `ping` | none | Answered with `pong`. | `expected_status` turns the write into a compare-and-set. Without it the update excludes the terminal statuses in its `WHERE` clause. With it, a row whose status has changed returns `Item status changed; refresh and try again`. ### Every update is a full snapshot There is no incremental order event. `notifyKdsUpdate` and `broadcastOrderUpdate` both call `sendActiveOrders`, which recomputes the caller's visible orders and counts and sends the result as a complete `initial_data`. A client must replace its board wholesale on every `initial_data` frame. The `status_updated` frame is an acknowledgement for the requesting client only; other displays learn about the change through their own `initial_data`. Broadcasts are coalesced: a burst of `notifyKdsUpdate` calls within one microtask produces one snapshot per client. ### Errors a display must handle | `error` message | Cause | | ---------------------------------------------------------- | ------------------------------------------------- | | `Unknown message type` | A client frame the switch does not accept | | `order_item_id and status required` | A `status_update` missing either field | | `Invalid status. Use: pending, preparing, ready, served` | A `status_update` outside the allowed set | | `Invalid expected status. Use: ...` | A malformed `expected_status` | | `Item not found` | Unknown `order_item_id` | | `This item has been voided and can no longer be updated` | The item was voided | | `This bill adjustment cannot be updated from KDS` | The item is a `void_adjustment` row | | `This terminal item cannot be updated from KDS` | `completed`, `cancelled`, or `refunded` | | `Not authorized to update this station` | Outside the caller's station scope | | `Not authorized to update this item` | Outside the caller's category scope | | `Item status changed; refresh and try again` | The compare-and-set lost | | `Scheduled order has not been released to the kitchen yet` | The item belongs to an unreleased scheduled order | | `Could not update item status` | The write threw | `auth_error` precedes a close on: `Authentication required` (no `auth` in time, or any non-`auth` frame before authenticating), `Invalid or revoked token`, `User not found`, `Only kitchen staff can access KDS`, `No active kitchen station is assigned to this user`, and `Could not load station permissions`. The 30-second heartbeat also closes a session with `Session expired or revoked` when the token or role stops being valid, and with `KDS is disabled` or `Database maintenance in progress` when the store setting changes under a live connection. ### Connection limits - 100 connected clients (`MAX_KDS_CLIENTS`), at most 25 pending (unauthenticated) clients globally (`MAX_UNAUTHENTICATED_KDS_CLIENTS`), and at most 5 pending clients per normalized IP (`MAX_UNAUTHENTICATED_KDS_CLIENTS_PER_IP`). Once a socket authenticates, it stops consuming the pending budget; closing and closed sockets are pruned before each admission check. Requests with no `Origin` header or a local/LAN/Tailscale `Origin` (`isAllowedOrigin`) are admitted; a direct `connection` event that fails admission closes with `1008` (disallowed `Origin`) or `1013` (capacity reached). - A client whose `bufferedAmount` exceeds 1 MB at send time is closed with `1013` as too slow. - The server sends a WebSocket ping every 30 seconds and terminates a client that misses one. - A client is re-sent a fresh `initial_data` without any change of its own when its category or station assignment changes, or when the voided-item expiry marker moves. ## KDS category and station scoping Two independent narrowing axes decide what a chef sees. Both are resolved at connect time and re-resolved on every broadcast, and both are re-checked inside the write transaction for a `status_update`. **Categories.** `categoryIds` is the empty list for `owner` and `manager`, which means unrestricted, and the parsed `users.category_ids` expanded with non-deleted child subcategories (`expandCategoryIdsWithSubcategories`) for everyone else. When the list is non-empty, an item is visible only if its product's category is in the expanded list. **Stations.** `stationIds` comes from `getUserKdsStationIds`. When a user has station assignments configured but none active, authentication is refused with `No active kitchen station is assigned to this user` rather than silently showing an empty board. `getKdsStationCategoryIds` and `getKdsStationRoutingScope` resolve each assigned station's `category_ids` (expanded with non-deleted child subcategories except child subcategories explicitly assigned to another active kitchen station) into a set of categories, plus a separate set for orders on tables with no `kitchen_station_id`, and report whether any assigned station is unrestricted (empty `category_ids`). An order is in scope when its table's `kitchen_station_id` is one of the caller's stations, or when the table has no station and the order contains an item in a tableless routing category, or when the caller has an unrestricted station. An item is then in scope when `isKdsStationItemAllowed` passes for that station and category set, and the category filter above also passes. The `counts` map is computed with the same scope, so it always matches the orders it accompanies. Three statuses are hidden from every KDS surface: `void_adjustment` rows (the mirrored line a void writes, which is a bill adjustment rather than a kitchen item), and `completed`, `cancelled`, and `refunded` items. A `voided` item stays visible for `KDS_VOIDED_ITEM_VISIBILITY_MS` after its `voided_at` timestamp and then ages off the board; the 30-second heartbeat notices the change and pushes a fresh snapshot. `projectKdsOrder` and `projectKdsItem` receive a `restrictedPayload` flag, true for `chef` and for anyone with a non-empty category or station scope, false for an unrestricted `owner` or `manager`. Unrestricted sessions receive the fuller row. The same two axes are applied by `GET /api/kds/orders`, `GET /api/kitchen/orders`, `PATCH /api/order-items/:id/status`, `PATCH /api/orders/:id/status`, and `PATCH /api/kds/items/:id/status` on `:3001` and `:3002`. See [KDS station and category narrowing](../architecture/authentication-and-authorization.md#kds-station-and-category-narrowing) for the authorization framing. ## Refunds Refund eligibility, approval tiers, the Staff Approval PIN rules, and how refund amounts are stored belong to [product invariants](product-invariants.md#refunds-and-staff-approval-pins). This page documents only the two routes. ## Cross-references | Subject | Page | | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Which processes run, on which ports, and the port retry ladder | [System overview](../architecture/overview.md) | | Token issuance, verification, revocation, staleness, Master PIN, audit attribution | [Authentication and authorization](../architecture/authentication-and-authorization.md) | | What each role sees in the interface | [Roles and permissions](roles-and-permissions.md) | | Refund approval rules and refund amount storage | [Product invariants](product-invariants.md) | | Daily sales export accounting and reconciliation contract | [Daily sales export](daily-sales-export.md) | | Merchant print template payload and offline transfer format | [Merchant print templates](merchant-print-templates.md) | | Business dates, day boundaries, and timestamp storage | [Business time](../architecture/business-time.md) | | Printer drivers, ESC/POS, and print routing | [Printing architecture](../architecture/printing.md) | | Device Master PIN second factor | [`main/middleware/master-pin.ts`](../../main/middleware/master-pin.ts) | ## Coverage This page lists 323 HTTP route registrations across 322 distinct rows, and one WebSocket contract: - `285` on the main API: 277 router registrations, 7 inline registrations in `main/routes/index.ts`, and `GET /api/health` in `main/server.ts`. - `13` REST routes on the KDS server, plus 3 static handlers. - `25` route registrations on the Server App, of which 13 forward to the main API. Two of those 25 are mutually exclusive `GET /` handlers under one path, which is why 25 registrations render as 24 rows. Every one of the 322 rows is listed with its method, path, authorization gate, and the parameters its handler reads. The **Response** column carries a note for 187 of them: 150 main-API endpoints, all 13 KDS-server routes, and the 24 Server App routes. The remaining 135 main-API endpoints are listed with method, path, gate, and parameters only, and this page asserts nothing about what they return. Those rows are complete as a route inventory and silent as a contract; the handler in `main/routes/` is authoritative for them. A `-` in the Response column means that, not that the endpoint does nothing. The route inventory is maintained by hand against the route files, not generated. The role groups, parameters, and rate limiters in the tables were read out of the route registrations themselves, but a route added after this page was last checked will not appear until someone adds it here.