Overview & design

POS Apps let a shop build its own apps (hand-written or vibe-coded with AI tools), upload them to Pancake POS and use them right inside the POS interface. An app only runs in the shop that installed it; it is never published publicly.

An app can:

• Add actions to existing action menus, for example "Push to ERP" in the order action menu.
• Attach to orders, products, purchases, exports and warehouse transfers with the same extension points and the same code shape.
• Insert blocks into existing screens, for example a "Customer debt" box in the order form.
• Add its own pages to the POS menu, for example a "Debt reconciliation" screen.
• Run hooks before or after an operation, for example blocking an order save when the customer exceeds a credit limit.
• Read and write shop data through the Open API, with exactly the permissions of the current user.

An app cannot modify, hide or replace existing POS UI or actions.

#Terminology

#Architecture

POS page (pos.pages.fm)                          App sandbox (separate domain)
┌──────────────────────────────────┐            ┌──────────────────────────────────┐
│ Extension points                 │ postMessage│ Hidden iframe                    │
│  ├─ Block / modal (Worker UI)    │◄──────────►│  └─ Web Worker                   │
│  │   drawn with POS components   │            │      ├─ App code + Preact        │
│  ├─ App page (iframe)            │            │      └─ POS runtime (pos, DOM)   │
│  └─ Hooks, display conditions    │            │ Page iframe: the app's SPA       │
│ Bridge: context data,            │            │      └─ SDK client (connect)     │
│ token, toasts, navigation        │            │  fetch ──► Open API (app token)  │
└──────────────────────────────────┘            └──────────────────────────────────┘

Principles:

1. App code never runs on the POS domain. Apps run in a web worker or an iframe on a sandbox domain dedicated to each app, so they cannot read the POS session, cookies or UI.
2. POS draws the UI; the app only describes it. For blocks and modals, the app builds a tree of pos-* elements. POS receives that description and renders it with its own components, so the UI matches POS exactly and the app never touches the page.
3. All data goes through the Open API, using an app token that carries the current user's permissions.
4. Targets, components and context data are a versioned contract (api_version in the manifest). POS keeps backward compatibility for the support period of each version.

#SDK

Apps do not implement the communication with POS themselves. It is split into two parts:

• POS runtime: POS loads it into the worker before the app's code. It provides the global pos object, the minimal DOM for Worker UI, the pos-* elements, the postMessage channel, app tokens and the Open API client. The runtime is not part of the app bundle, so POS can update or patch it without apps redeploying.
• SDK packages installed in the app project:

Package versions follow api_version (package 2026.1.x for 2026-01). pos-app check validates the manifest and catches mistakes AI tools often make (using the real DOM, plain HTML tags, undeclared methods or domains). Details: SDK & CLI.

#Choosing a presentation

Rule of thumb: inside a POS screen → Worker UI; a screen of its own → iframe; no UI → headless.

#How Worker UI works

A web worker has no DOM. The POS runtime loads a minimal DOM into the worker, just enough for Preact or plain JS to build a tree of pos-* elements. Whenever the tree changes, the runtime records the changes (nodes added or removed, properties or text changed) and sends them to POS as one batch per render pass. POS validates each element and draws it with real components. When the user clicks or types, POS sends the event into the worker and the app's code receives the value in event.detail.

Worker (app code)                                  POS
setState → Preact re-renders on the minimal DOM
         → runtime batches the changes ──────────► validate → draw with POS components
onChange(event.detail) ◄───────────────────────── user clicks, types

Consequences:

• State lives in the app's code (useState, variables…). POS only keeps the rendered UI, never the app's state.
• Each time an extension is shown it runs in its own worker. Closing the modal or leaving the screen stops the worker and its state is lost; persist anything long-lived through the Open API or the app's own server.
• Inputs stay responsive while the app is busy: POS shows what the user types immediately, then notifies the app.
• The runtime is built into the worker; apps install no extra library to talk to POS.
• Only elements from the component catalog can be used. Unknown elements are not rendered and the extension reports an error.
• There is no window, document.querySelector, localStorage, canvas or DOM measurement. Chart and third-party UI libraries do not run in the worker; use POS-provided components or move that part to an iframe page.

#Security model

#Data access

Apps use the existing Open API: same endpoints, format and pagination. The difference is the credential:

• No static API key in code. POS issues an app token automatically while the app runs.
• App permissions = the current user's permissions ∩ the limits the admin sets for the app (warehouses, hidden fields, read-only…).
• Every write is audited with the real user and the app.

Details: Data access.

#App lifecycle

1. A shop member with the configuration management permission uploads a bundle with the CLI. Each upload creates a version.
2. POS validates the manifest: valid targets, existing files, sizes within limits.
3. The admin reviews the data access and external domains the app requests, confirms the shop is responsible for the app, then activates the version on the Custom apps page.
4. By default every shop member sees the app; limiting it by department is not yet available on the management page.
5. The admin can roll back to an earlier version or disable the app at any time. Disabling revokes all app tokens in use.

#Limits

#Support scope

• POS web only. The mobile app does not run extensions yet.
• UI hooks only run when the operation happens on POS web, at the place where the hook is attached. Records created or changed through the Open API, the mobile app, bulk updates or marketplace sync do not go through hooks. Rules that must always hold belong on the server.
• Apps do not run in the background. Scheduled jobs and webhook processing need the shop's own backend (see Data access).

#Roadmap