Vaultli

v20260625_61

Welcome to the Vaultli Master Reference. This synthesized manual covers operational instructions and under-the-hood technical mechanics for all core workflows.

1. The Dynamic Metadata & Collection Customization Workflow

A. Step-by-Step Operations

  1. Navigate to the Settings Pane: Locate the main navigation bar at the top or side of the screen and click on Settings.
  2. Access Category Configurations: Under the settings navigation, click on the Collection Categories tab.
  3. Customize Active Fields: Scroll to your chosen category (e.g., Guitars & Basses). Under the field list, check the boxes:
    • Show in Grid (Tile View): Check this box to display this specific field directly on the inventory cards in the Grid view.
    • Show in Table (List View): Check this box to display this field as a dedicated column in the spreadsheet-like List view.
  4. Hiding a Category: Click the Hide switch/icon next to any category to remove it from sidebar links, creation forms, and category list filters.
  5. Deleting a Category: Click the red trash icon next to a category to delete it from active customization.
  6. Restoring Category Defaults: Click the Restore Defaults button to display a selection checklist of default categories. Check the boxes of categories you want to recover and save.
Data Perpetuity Guardrail: Hiding or deleting a category ONLY alters display settings and layout flags. It NEVER deletes your actual inventory records or underlying Supabase database rows. Toggling category visibility back on or restoring deleted default categories instantly restores and re-hydrates all associated inventory items with their full specification histories.

2. The Mobile Barcode & QR Scanning Workflow

A. Step-by-Step Operations

  1. Open a Collection Group: From the dashboard or sidebar, select the collection group or category where you want to add or edit an item.
  2. Launch the Scanner Viewport:
    • Click Add Item to open the modal form (or open an existing item card).
    • Scroll down to the Serial Number / Unique ID / SKU input field.
    • Click the camera/barcode icon next to the input field.
  3. Position the Camera:
    • The system automatically triggers your device's macro-rear lens with autofocus.
    • Center the physical barcode or QR code inside the red surgical Region of Interest (ROI) box displayed on the screen.
  4. Scan Execution: Hold the camera steady at a distance of 6–8 inches. Ensure the barcode is well-lit and free of specular glare or deep shadows.
  5. Automated Metadata Hydration: Once decoded, the scanner automatically populates the input field with the scanned barcode and queries the database/server.
  6. Confirm Payload: Verify the hydrated metadata payload shown in the input and click Save on the form.

System Mechanics: Optimized Scanner Pipeline

  • Autofocus Constraint: Enforces focusMode: "continuous" using Media Stream Track capabilities to bypass manual focusing.
  • Camera Targeting: Enforces facingMode: "environment" to select the mobile rear-facing camera.
  • Resolution & Downscaling: Targets a speed-optimized 1280x720 stream and downscales the target viewport to a Canvas context buffer, allowing the barcode reader to process compact pixel grids instantly.

3. The Persistent View & Cross-Device Sync Workflow

A. Step-by-Step Operations

  1. Work within a View: Navigate to any specific view (e.g., Acoustic Guitars category, or filtered search result list).
  2. Execute a Safe Browser Refresh: Refresh your desktop or mobile browser.
    • Result: The app reads localStorage and URL parameters to immediately reload the exact category, filters, and modals you had open, rather than forcing you back to the home dashboard.
  3. Cross-Device Sync Operations:
    • Log into your Vaultli account on a mobile phone (e.g., to scan items in your storage room) and on your desktop computer (placed on your workstation desk).
    • Scan an item or alter a category layout on your mobile phone.
    • Trigger Refresh: Refresh your desktop browser or let the auto-sync run.
    • Result: Your desktop computer instantly mirrors the newly scanned items and customized settings.

System Mechanics: State Serialization & Hydration

Whenever you navigate, navigateTo(viewId) writes the view state to localStorage under vaultli_current_view and updates the URL via window.history.replaceState (e.g. ?view=category-guitar). Upon app initialization, finishInit() reads the URL parameters and hydrates the UI instantly.

4. The Trade-In Creation & Purchase Linkage Workflow

A. Step-by-Step Operations

  1. Open the Purchased Item Card: Open the form modal for the newly acquired equipment or item you are purchasing (or editing).
  2. Enable the Linkage Checkbox: Scroll down to the purchase details area and select the checkbox option labeled "Link to a Trade-In Item".
  3. Select and Filter the Traded Asset (Single-Sided Entry):
    • Selecting the checkbox immediately displays a real-time search filter and a selection dropdown list of trade candidates.
    • Type in the search box to filter the collection in real-time (matching against Brand, Model, Category, and Serial Number).
    • The dropdown is strictly filtered to show only inventory items with status 'Traded-In' where linked_to_purchase is false (or currently linked to this item when editing). Select the traded asset from this list.
  4. Input the Trade-In Allowance: Enter the Trade-In Date and the Trade-In Amount (Allowance) inside the revealed fields on the purchase card.
  5. Review Automated Calculations:
    • The purchase details area will dynamically display two clear, read-only layout rows below the cost field:
    • Trade-In Credit: Displays the credit value of the traded asset.
    • Net Cash Outlay: The net cost calculated as Purchase Cost Each - Trade-In Credit.
  6. Save Locked Relational Link: Click Save.
    • Result: The system handles all relational side-effects automatically:
    • Transitions the traded asset's status to 'Traded-In'.
    • Completely hides the "This Purchase Involved a Trade-In" checkbox and other purchase adjustment tools on the traded asset's form layout to prevent structural confusion.
    • Locks down the traded asset's fields (Trade-In Date, Trade-In Amount, and Recipient) as disabled Read-Only values inherited from the purchase transaction.
    • Renders a reciprocal Link Badge on the traded asset's form pointing back directly to the newly saved purchase item.

5. The Tablet & Mobile Landscape Viewport Scroll Correction Workflow

A. Step-by-Step Operations

  1. Rotate Device to Landscape Mode: On an iPad, tablet, or mobile phone, rotate your device sideways to view the form layouts in landscape mode.
  2. Open the Item Modal Form: Click Add Equipment or edit an existing item to trigger the modal overlay drawer.
  3. Automatic Low-Height Override:
    • The system media query (@media (max-height: 600px) and (orientation: landscape)) automatically intercepts the viewport height.
    • It clears rigid heights and sets the modal container wrapper to max-height: 90vh to ensure it fits completely within the tablet screen boundaries.
  4. Enforce Scrollability:
    • The form body enables active scrollability (overflow-y: auto).
    • Swipe up to scroll down through the form categories, fields, and options.
  5. Clear Action Buttons (Padding Buffer):
    • Scroll to the bottom of the form to access the action buttons (Cancel, Delete, and Save Equipment).
    • An explicit padding override (padding-bottom: 100px) at the bottom of the form container forces the action buttons to scroll completely past the hardware screen edges, preventing them from being cut off.
  6. Click Action Buttons: Click the fully visible and interactive action buttons to complete your transaction save.

6. The Referential Integrity Deletion Blocking Workflow

A. Step-by-Step Operations

  1. Trigger Deletion Attempt: Open either a linked purchase record or a linked traded-in record in edit mode, and click the red Delete button.
  2. Active Linkage Intercept: Before executing any deletion sequence, the system intercepts the command and checks if the item is part of a trade-in link.
  3. Hard Block Warning: If linked, the deletion halts instantly. The system displays a clean, visible warning modal stating:
    • "This item is locked in an active trade-in transaction. You must unlink these records to make them independent before either can be deleted."
  4. Navigate to the Purchase Card: Open the purchase card associated with the trade-in transaction.
  5. Unlink the Records:
    • Scroll to the purchase details section.
    • Uncheck the "Link to a Trade-In Item" checkbox.
    • Click Save. This decouples both records, nullifying linked_item_id and setting linked_to_purchase to false.
  6. Safely Delete Independent Records: Open either decoupled item in edit mode and click Delete. The delete query will now process successfully.

7. General Inventory Actions Workflow

A. Manual Record Creation

  1. Click the Add Equipment button at the top of the collection grid.
  2. Select the Category from the dropdown menu.
  3. Enter required fields: Brand, Model, Year, and Condition.

B. Uploading Photos

  1. Under the photo upload area in the creation/edit modal, click Upload Image or drag-and-drop your image file.
  2. Up to 5 images can be loaded per item. The first non-PDF image is selected as the primary thumbnail.

C. Altering Specialized Condition Grades

  1. Locate condition dropdowns (e.g., Sleeve Condition or Media Condition for vinyl records).
  2. Select the appropriate rating (e.g., Near Mint, Very Good Plus).

D. Filtering Lists

  1. In the search bar at the top of the inventory page, type a query to filter by name, brand, or model.
  2. Toggle the Category and Status filters to isolate specific collection groups.

E. Switching View Modes

  1. Locate the view layout icons at the top right of your inventory grid.
  2. Click the Grid (Tile) icon for cards with thumbnails, or the Table (List) icon for a spreadsheet-like row layout.

F. Localized CSV/Excel Export

  1. Under Settings -> Import/Export, or from the Report Builder page, select your active filters.
  2. Click Export CSV to download a localized spreadsheet file containing all item fields and custom specs.

8. Cloud Database Synchronization & Row-Level Security

A. Operations & Security

9. Dropdown Options Management

A. Operations

10. Backup & Fuzzy CSV Import

A. Operations