Hospitality Department Inventory

Problem

The department needed one record of who has which equipment and what has been sold, and returns had to separate good, damaged, and lost items without the stock count and the borrower's record drifting apart.

Constraints

• Returns must account for good, damaged, and lost quantities without breaking the stock count
• Barcode scanners act as keyboard input, so scan flows must work with ordinary form focus
• Web and API must agree on request shapes without duplicating validation
• A new developer should get the full stack running with one command

Key Decisions

1. One transaction per return

   A return changes stock and the borrower's record, and splits the quantity into good, damaged, and lost.

   Write all three counts, the stock change, and the borrower's record in one database transaction.

   Trade-off: Slightly more careful service code, but stock and the borrower's record can never disagree.
2. Shared Zod schemas

   The web app and the API both validate the same payloads, and drift between them causes silent bugs.

   Put the Zod schemas in a shared package that both sides import.

   Trade-off: One more package to keep in sync, but request shapes are defined exactly once.
3. Barcode-wedge scanners as keyboard input

   The department's scanners type the code into whatever field has focus.

   Treat scans as ordinary keyboard input and build the scan workflows around focused fields.

   Trade-off: Focus handling in the UI has to be careful, but no scanner SDK or special hardware integration is needed.