Engineering inside Stockroom /

Interface and interaction architecture

The public UI preview is a React inventory workspace. The private app includes a ZXing camera scanner, typed-SKU fallback, server-side inventory rules and an offline movement queue.

Movements explain the balance

Receiving and dispatch create signed ledger deltas; counts create reasoned corrections. Allocations separately reserve stock, allowing on-hand, reserved and available quantities to remain distinct. Releasing a reservation does not create physical stock. Domain checks reject negative receiving and prevent concurrent allocations from reserving more units than the bin can supply.

Counts carry an observed version

A count submits the movement version returned with the balance that the operator saw. The server rejects stale or missing versions before changing stock. This protects intervening movements from being overwritten by a delayed count. Counts also cannot reduce on-hand below existing reservations, and whole-unit validation rejects fractional or negative values.

Queued work needs acknowledgement

The browser keeps pending operations in a local queue and sends an idempotent operation when connectivity returns. The interface exposes pending and acknowledged states instead of treating a click as a completed receipt. Server-side replay handling prevents a repeated accepted command from creating another movement. The browser acceptance test exercised an actual disconnected network context.

Persistence belongs to each product

The current service uses its own D1 database binding and workspace-scoped records, with authenticated commands, origin checks and CSRF protection. Record changes and event snapshots are committed through the service transaction layer. CSV export reads the recorded ledger. An ordinary reload test proves saved state retrieval; process recovery and backup restoration require their own evidence.

Operating the product

Start with the public interface to explore the design using example records. These interactions stay in the current view. Open the private workspace from the interface to use the existing account, storage and product workflows.

Use a traceable reference for each receipt, pick and physical count.

After a stale-count conflict, reload the current movement state and physically recount before submitting another correction.

After reconnecting, inspect pending operations and acknowledged ledger entries before entering the same receipt again.

Release a pick that will not ship; use dispatch only for units that actually leave the bin.

Keep scheduled record backups and verify restoration in an isolated installation before relying on a deployed service.

Independent by construction

Stockroom has its own application source, build configuration, local server, database, object store and session cookie. The fifteen applications reuse copies of a common foundation, but their operational data and credentials are independent. A shared dependency cache on this Mac saves disk space; each product includes a lockfile and a command to install its own dependencies.

Mutations validate the workspace and current record version. Approval binds the reviewed content digest; an idempotency key prevents an identical retry from becoming a second action. These controls are implemented in the server, alongside the product-specific rules described above.