> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0253 — Peripherals are Web-API first; native modules only on evidence; device presets

> Accepted · 2026-10-20

> [!NOTE]
>
> Clarifies [0235](/adr/0235-devices-and-iot-minimal-now-full-later): peripherals are the client's
> own hardware; devices are principals in identity.

## Context

Retail and attendance clients need local hardware: receipt printers, barcode scanners, cash drawers, card readers and QR kiosks. The owner accepted the defaults on 2026-10-20 night: browser device APIs first, no native modules on day one, and device presets for the first two kits.

## Decision

1. **Package.** `@stackra/peripherals` (experience category) provides the peripheral ports, and the thin browser implementations of them.
2. **Web APIs first.** Browser device APIs (WebUSB, WebHID, Web Bluetooth, Web NFC where available) are used first. No native module is added on day one.
3. **Native on evidence.** A native module is added only when a measured requirement is not met by the Web APIs, and each one needs its own ADR.
4. **Presets.** Device presets are profiles in `@stackra/peripherals`:
   * the POS kit for Retail OS: ESC/POS receipt printer, HID barcode scanner and cash drawer;
   * the attendance kit for Academorix: NFC or card reader and a QR scanner kiosk.
     More presets follow the same form.
5. **Separate from devices.** A peripheral is hardware the client uses. A device is a principal in identity (ADR 0235).

## Consequences

* A kiosk works in a browser before any installer exists.
* A new preset is a profile, not new code.

## Enforcement

planned — each preset has a test against a recorded device fixture; the validator rejects a native module added without an ADR reference.

## Supersedes and sources

Supersedes: none. Clarifies: [0235](/adr/0235-devices-and-iot-minimal-now-full-later). Sources: desktop and PWA owner decision (defaults and device presets, `stackra-decisions-2026-10-19.md` L954, 2026-10-20 night); plan section 2.3.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.