WorQR

What is this?

WorQR is a high-speed QR code scanner for your browser that works even when you're offline.

Think of it as a "Dumb Scanner" for the web:

• You point your phone at items, and it automatically saves them to a local database.

Because it uses background synchronization, your scans can automatically show up on another device (like a laptop or tablet) instantly, without you having to "connect" or "pair" them manually.

Lovingly Crafted by Hand in 2014...

This repo is a "modernized" version of a high-performance scanning tool originally built in 2014.

It uses a "Postal" system where scanned data is treated like mail:

• The scanner puts it in a "Mailpouch" (a local database).
• Other apps can "join the channel" to see those scans in real-time.

It is designed for rapid-fire scanning in environments like warehouses or shops where speed and reliability are more important than fancy menus.†

    †"But you can have those too --- and we do --- down the wire."
        - Human Developer

---

---

Technical Assessment The following technical analysis was authored by an LLM (Gemini) in 2026. The author was explicitly instructed to provide a neutral, confirmable assessment of the engineering design without engaging in hyperbolic praise.

Architectural Design Analysis

WorQR is an offline-first QR scanning primitive designed as a decoupled edge node for distributed data capture. Originally developed in 2014 using early HTML5 draft specifications, it implements a "dumb scanner" pattern where the device acts as a hardware peripheral that persists data to a synchronized state layer.

1. The Edge Node Pattern

Unlike traditional web applications that integrate scanning logic directly into a monolithic UI, WorQR is architected as an autonomous data producer. It captures, decodes, and persists data without requiring local interaction UI, allowing "Console" devices (desktops, tablets) to consume the data stream asynchronously via database synchronization.

2. Passive Pairing via P2P Sync

Integration is handled at the data layer rather than the application layer. By leveraging PouchDB's synchronization protocol:

• Decoupling: The scanner has no knowledge of the consumer.
• Identity: A unique device fingerprint generates an isolated namespace (client.<fingerprint>.worqr), preventing collisions in multi-device environments.
• Passive Discovery: A consumer "pairs" with a scanner simply by subscribing to that device's specific PouchDB changes feed.

3. "Postal" Messaging & Persistence

The system implements a bridge between transient events and persistent storage:

• Event Bus: postal.js provides an in-memory message bus for real-time internal communication.
• The Mailpouch: mailpouch.js acts as a generic bridge, automatically persisting every message envelope from a specified Postal channel into a PouchDB instance. This ensures that the "Wire" (P2P sync) preserves full message metadata, including timestamps and origin topics.

Performance Engineering

Multi-Threaded Decoding

To maintain UI fluidity and support rapid continuous scanning, QR decoding is offloaded to a dedicated Web Worker.

Zero-Copy Buffer Transfers

The implementation utilizes Transferable Objects to hand off image data from the main thread to the worker. By transferring ownership of the ArrayBuffer rather than cloning it, the system minimizes garbage collection overhead and memory pressure—a critical optimization for 2014-era mobile hardware.

Back-Pressure Gating

The scanning loop uses a gated recursive pattern via requestAnimationFrame. A new frame is only captured and sent for decoding after the worker has signaled completion of the previous frame. This provides a natural back-pressure mechanism that:

• Prevents CPU exhaustion.
• Ensures the video preview remains fluid.
• Optimizes the scan rate for the highest possible throughput the hardware can support (measured at ~7 FPS on standard hardware).

State Management

The scanner lifecycle is managed via a Finite State Machine (FSM) using machina.js. This prevents race conditions during hardware initialization and ensures predictable transitions between startup, ready, and scanning states.

Modernization (2026 Updates)

The core logic has been updated to comply with finalized Web Standards:

• Media Devices: Migrated to navigator.mediaDevices.getUserMedia and enumerateDevices.
• ES6+: Refactored to native Class syntax and block-scoped variables.
• Build Pipeline: Replaced Grunt/Bower with a native npm and esbuild pipeline.

Getting Started

1. Install: npm install
2. Build: npm run build (Minifies performance-critical paths as required by the worker environment).
3. Test: npm test (Includes integration and load/throughput testing).
4. Run: npm start (Serves the application at http://localhost:9000).

License: Business Source License (BSL)

Copyright © 2026 GNOMATIX. All rights reserved.

This software is licensed under the Business Source License (BSL) version 1.1. Usage of this software is subject to the terms of the BSL. See the LICENSE file for details.