fieldlens-deploy/README.md

FieldLens

FieldLens is the Arrowstack-hosted production application around the reusable, local-first FieldLens Core.

Repository boundary

• apps/web owns Arrowstack browser authentication, sync, station/device status and the production PWA shell.
• apps/api owns JWT/RBAC, sync ingestion, PostgreSQL, device/station registration and server-side provider adapters.
• packages/contracts is the versioned network contract shared by the browser and API.
• packages/fieldlens-core is a pinned vendor copy of the public reusable core.
• migrations contains versioned PostgreSQL schema changes.

The public source of truth is dmparrow/feildlens-core (spelling intentional). The initial vendor import is pinned to commit:

90d38751eea2bed79f4c9f54c75687ea9aba350a

The private prototype dmparrow/net is not a production dependency and is not modified by this repository.

Local-first invariant

Capture writes to IndexedDB first. Remote authentication, API availability, PostgreSQL availability and reference-data availability are not prerequisites for scanner, EAN pallet, OCR/conformity or local review workflows.

Configuration

See the root and app-specific .env.example files. Never commit production secrets.

Validation

npm install
npm run verify
docker build -t fieldlens .

For Arrowstack database-per-tenant deployments, the restricted application runtime identity owns DDL inside its dedicated database. The API applies versioned migrations at startup under a PostgreSQL advisory lock before it begins listening; applied migration filenames and checksums are recorded so startup is idempotent and changed historical migrations fail closed.

FieldLens Print desktop companion

apps/print is a Tauri desktop companion that turns an outgoing print stream into FieldLens scan events without requiring a physical barcode scan.

Capture routes:

• RAW 9100 proxy — listen locally (default 127.0.0.1:9100), extract supported barcode fields from ZPL, and forward the original bytes unchanged to the real printer.
• Spool / virtual-printer folder — watch a local folder for .zpl, .raw, .prn, or .spl jobs produced by a print-to-file or virtual-printer route. Parsed jobs can also be forwarded to the physical printer.
• Both — run both adapters at the same time.

The first parser handles ZPL barcode commands for Code 128, Code 39, Code 93, EAN-8/13, UPC-A/E, ITF, QR, Data Matrix, and PDF417. Non-ZPL raster/EMF/XPS rendering is intentionally a later fallback; unsupported jobs are retained in recent-job diagnostics instead of being treated as successful scans.

Authentication uses Keycloak OAuth Device Authorization Grant with the public fieldlens-print client. No client secret is embedded in the desktop executable. Access and refresh tokens are kept in memory only; unsynced barcode events are stored locally under the Tauri app-data directory.

Development

npm install
npm run build --workspace @fieldlens/print
npm run tauri --workspace @fieldlens/print -- dev

The Windows NSIS bundle is configured for currentUser installation, so installing FieldLens Print itself does not require elevation. Configuring or changing a Windows printer queue/port may still require IT/admin rights depending on machine policy.

Desktop release artifacts

The .gitea/workflows/desktop-release.yml workflow packages FieldLens Print on changes to the desktop app, on main, and on fieldlens-print-v* tags.

Artifacts:

• Windows x64: NSIS current-user installer from apps/print/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/nsis/*-setup.exe
• Linux x64: Debian package from apps/print/src-tauri/target/release/bundle/deb/*.deb

After a successful Gitea Actions run, download the corresponding fieldlens-print-windows-x64 or fieldlens-print-linux-x64-deb artifact from the workflow run.

Local packaging commands:

npm run bundle:windows --workspace @fieldlens/print
npm run bundle:deb --workspace @fieldlens/print

The Windows package is cross-compiled with cargo-xwin and bundled with NSIS. MSI packaging is intentionally not part of the Linux runner workflow because WiX/MSI bundling requires Windows.