LockVentory Blueprint

Page State Persistence ✅ Done

Cameron's words: "First and foremost, this app should not drop the page that you are on when you leave the app and come back to it a minute later."

Every navigation saves the current page to sessionStorage. When you re-open the app (or switch back from another app), it restores exactly where you were. Works in both browser and PWA standalone mode.

Admin Account + Permissions System ✅ Done

Cameron's words: "If several team members are linked to one company, there should be at least 1 admin account. The admin account should be able to set their permissions for if individual team members should be able to add folders and items to the inventory."

• Every org requires at least one admin — the last admin cannot be demoted.
• Admins can toggle Can Add Folders and Can Add Items per member from the Team page.
• The API enforces these permissions server-side — a member can't bypass them by calling the API directly.
• The frontend hides or disables Add Folder / Add Item controls for members without the permission.

Team Stock Isolation ✅ Done

Cameron's words: "Team members should not be able to edit the stock of other team members."

All quantity write operations verify the requesting user owns that stock row. The API returns a 403 if the user_id on the record doesn't match the authenticated user. The frontend never shows +/− controls on another member's stock — Team Stock view is read-only for everyone else.

Toast Notification System ✅ Done

Cameron's words: "A small notification should show up at the bottom of the screen that confirms most changes."

Every write action (qty change, item add/edit/delete, folder change, order action, invite sent) fires a toast at the bottom of the screen. Auto-dismisses in ~2.5 seconds. Multiple toasts stack cleanly. Orange for success, red for error.

Folder Navigation + Breadcrumbs ✅ Done

Inventory is organized in a folder tree. You navigate into folders the same way you'd browse files on a phone. The breadcrumb bar at the top always shows HOME › Folder › Subfolder — tap any crumb to jump back up. Folders with the dropdown option set render as collapsible sections instead of a new page.

Checkboxes let you toggle Show Item Count and Show Quantities on folder rows.

My Stock / Team Stock Tabs ✅ Done

Two tabs on the Inventory toolbar. My Stock shows your personal quantities. Team Stock shows every team member's quantity for every item in the current folder — the killer feature Cameron designed the whole app around.

Search & Filter ✅ Done

The search button opens a search box with:

• Scope dropdown: search all folders or current folder only
• Field filters: name, description, tags (any combination)
• Results show the folder path so you know exactly where each item lives
• Updates live as you type

Add Folder ✅ Done

Opens a sheet with: folder name (required), optional description, color picker (preset palette), icon picker (preset icons or photo from camera/gallery), and a toggle to show this folder's subfolders as dropdowns instead of navigating to a new page.

Add Item ✅ Done

Opens a multi-step sheet with:

• Item name + optional description
• Icon picker (preset icons or photo from camera/gallery)
• Quantity type: use a numeric quantity + minimum reorder threshold, or use Low/Med/High stock indicators
• Supplier URL field (link directly to the item on a supplier's website)
• Name merge check: if another item in any folder has the same name, the app warns you and shows its unique ID so you can decide whether to merge
• Auto-generates a unique ID in the format LV-XXXXXX (no ambiguous characters)
• Auto-generates a QR code encoding that unique ID — with a print option

Note: "Recommended autofill" (AI that fills in item details from the name) was deferred by Cameron — "we'll get into that later." The field is stubbed in the UI.

Item Row Popup + Item Detail Sheet ✅ Done

Tapping an item in a folder opens a quick popup with:

• View — opens the full item detail sheet
• ⧉ — duplicates the item instantly into the same folder
• + / − buttons for quantity items
• Low / Med / High toggle for stock level items

The item detail sheet shows all data about the item (name, ID, QR code, description, icon/photo, supplier link, your quantity, team quantities) with options to edit or change qty via manual entry or +/−. There's also an "Add to To Be Ordered" button that sends the item straight to the Restock tab.

Run Inventory Mode ✅ Done

Cameron's words: "This shows your entire inventory as a series of dropdown folders, and + or − or low/med/high — which allows you to manually adjust quickly your entire inventory."

Tapping Run Inventory opens a full-screen mode showing every folder and item in the org. Folders are collapsible. Each item shows its current quantity or stock level with inline +/− or L/M/H controls. Changes save immediately (debounced). A toast confirms each save. Exit button returns to normal view.

Edit Mode — Reorder, Duplicate, Move, Delete ✅ Done

Cameron's words: "Edit mode button — allows reorganizing of folder (3 dots on the left), allows selection of items or folder — delete selection, move selection."

• ⠿ drag handle on the left of every row — press and hold to drag, placeholder shows where it will land, saves automatically on release
• Checkboxes on every row for multi-select (mix of items and folders)
• Action bar appears when items are selected:
  • Duplicate — copies all selected items/folders in place with "(Copy)" suffix and new unique IDs
  • Move — opens the full folder tree picker, moves everything at once
  • Delete — confirm prompt, removes items permanently, re-parents folder contents so nothing inside is lost

Inventory Changelog ✅ Done

The Changelog button on the Inventory toolbar opens a live audit log of every quantity change, item creation, and deletion — showing who made the change, what changed, old value → new value, and when. Filterable by team member and entity type. Paginated.

Low Stock Tab ✅ Done

Shows all items that are at or below their minimum reorder quantity, or at Low/Medium stock level. Each row has:

• + button to add to the To Be Ordered list (with optional manual qty entry)
• Inline quantity adjust
• Checkmark indicator when the item has already been added to To Be Ordered

Manual refresh button and a Changelog button scoped to quantity changes.

To Be Ordered Tab ✅ Done

Your running order list. Items are grouped by supplier. Each supplier group shows:

• Every item assigned to that supplier, with quantity and price (if set)
• Out of stock badge when a supplier has marked the item OOS
• 🛒 Add to Cart button (see workaround note in Section 4)
• ✓ Ordered button — marks the group as placed, removes from list, saves to Order History

Clicking an item opens a supplier dropdown showing all linked suppliers for that item with their prices. Clicking a supplier moves the item under that supplier's group in the Order List.

Suppliers System ✅ Done ⚠️ Caveat

Cameron's words: "Shows a list of preset suppliers — lets you add your suppliers and login to accounts with them, without closing the app, have it run it on top."

• Preset suppliers built in: IDN Hardware, HPC Inc, Major Lock, Medeco, Schlage, Kwikset, Corbin Russwin, Arrow Lock
• Add custom suppliers (name + URL) any time
• ↗ Open button slides up a full-screen in-app browser panel so you can log in and shop without leaving LockVentory
• If a supplier's site blocks the in-app browser (a security header some sites use), a "Open in browser" fallback appears
• Closing the panel returns you to exactly where you were

Optimize Order ✅ Done ⚠️ Caveat

Cameron's words: "AI reads the prices on the sites, does the math, and then moves all items to the Order List with recommended sites to order from based on the items."

The ✨ Optimize button automatically assigns the cheapest in-stock supplier to every item in the order list and groups them accordingly. A toast shows how many items were matched and how many had no supplier linked.

Order History ✅ Done

Every time you mark a supplier group as Ordered, a snapshot is saved — which items, which supplier, what qty, who placed it, and when. Order History button shows a paginated log of all past orders.

Service Calls ✅ Done

Log service calls with job type, status, notes, and the parts used on each call. Part usage deducts from your personal stock. Calls are listed with filter and sort; each call has a full detail view.

Parts Catalog ✅ Done

A searchable, filterable view of all parts in the org — separate from the folder-based inventory. Useful for looking something up quickly without navigating the folder tree.

Team Management ✅ Done

Admin-only Team page shows all members with their role, join date, and permission toggles. Invite new members via a unique link. Remove members. Enforce minimum 1 admin rule.

Help Documentation ✅ Done

Full in-app help guide at /help. Covers every feature with step-by-step instructions, callout boxes, a glossary of locksmith terms, and a permissions reference table. Sticky sidebar navigation on desktop, scrollable on mobile.

PWA — Install, Offline, Pull-to-Refresh ✅ Done

LockVentory installs to your home screen on iOS and Android. A service worker caches the shell so the app opens even without signal. Pull down on any page to refresh (the only way to refresh in standalone mode — there's no browser toolbar). App icon: orange lock on dark background.