TreeTable Stock Ledger & Variant Tracking Guide

The Store Management ledger in TRAX POS delivers an enterprise-grade, real-time stock ledger built on a hierarchical tree-table architecture (p-treeTable). Unlike standard flat stock lists, the TreeTable automatically establishes parent-child relationships between primary catalog items and their downstream variations (flavors, package sizes, or multipacks). Every single receipt, hold order, return, and checkout transaction dynamically updates the ledger in real time without requiring manual page reloads.

---

1. Architectural Overview & Data Hierarchy #

TRAX POS organizes physical inventory into an expandable ledger node tree (inventoryNodes):

• Primary Products (P): Master root catalog items (isMain: true) representing the primary base commodity (e.g., standard retail products or base packaging).
• Sub-Products / Variants (S): Child items linked directly through parentId, representing size variants, flavors, multipacks, or distinct wholesale units.

Display Indexing Standard

• Root Items: Assigned sequential integer display numbers: 1, 2, 3, etc.
• Child Variations: Inherit the parent number joined by a sub-index: 1-1, 1-2, 2-1, ensuring instant visual grouping during rapid stock audits.

---

2. TreeTable Ledger Column Specifications #

The inventory ledger table displays nine specialized telemetry columns:

Column Header	Data Field	Description & Real-Time Behavior
#	displayIndex	Hierarchical position indicator (1, 1-1, 1-2).
Product Name	productName	Product title equipped with tree toggler chevron (p-treeTableToggler) and dynamic reservation status indicator dots.
Barcode	barcode	Scannable GTIN, EAN, or internal warehouse tracking barcode.
Store	stock	Total baseline physical quantity initially received into the warehouse, formatted with unit badge (Pcs, Kg, Box).
Reserved	reservedStock	Quantity currently locked in active cashier POS shopping carts or on-hold suspended orders.
Sold	soldStock	Net quantity confirmed sold across finalized customer invoices (automatically reduced by resalable returned units).
Rest	Computed	Real-time available free stock ready for sale on the checkout counters.
Level (50% Store)	reorderLevel	Benchmark reorder safety threshold, automatically set to exactly 50% of the initial received store stock ($0.5\times \text{Store}$0.5×Store).
Status	p-tag	Live health badge: In Stock (Green), Low Stock (Blue/Info), or Out of Stock (Red).

---

3. Real-Time Balance Formula & Stock Math #

The live available stock balance (Rest) is calculated in real time using the following continuous equation:

Rest = Store − Sold− Reserved

Where:

• Store: Physical opening/counted stock stored in IndexedDB.
• Sold: Net sales calculated via $\sum \text{Invoice Quantities}-\sum \text{Resalable Customer Returns}$∑Invoice Quantities−∑Resalable Customer Returns.
• Reserved: Sum of stock currently held across all registers in active checkout sessions and held tickets.

Stock Status Thresholds

• In Stock (success / Green): Rest>Reorder Level
• Low Stock (info / Blue): 0<Rest≤Reorder Level
• Out of Stock (danger / Red): Rest≤0

---

4. Visual Reservation Status Dots #

Next to each product name in the TreeTable, TRAX displays visual glowing indicator dots that communicate active cart and hold locks without opening the hold orders tab:

• 🔴 Red Dot (dot-red): Stock reservation exists on the Primary Product itself.
• 🔵 Blue Dot (dot-blue): Stock reservation exists on one or more child Sub-Product Variations.
• 🟠 Orange Dot (dot-orange): Stock reservations exist simultaneously on Both the primary product and its child variants. Hovering reveals a detailed tooltip showing the exact reserved quantity breakdown.

Visual Reference: TreeTable Stock Ledger & Variant Tracking

(Upload and insert the generated store_inventory_treetable_ui image here)

---

5. Live Search & Auto-Expansion Engine #

The inventory search bar (p-iconfield) enables unified searching across both parent and child tiers:

1. Multi-Field Matching: Evaluates queries against Product Name, Barcode, and Sub-product variants.
2. Auto-Expansion: When a search query matches any child variant, the parent tree node expands automatically (expanded: true), ensuring cashiers never miss associated variations.
3. Responsive Pagination: The ledger dynamically computes rows per page based on current monitor viewport height (calculateRowsPerPage()), preventing vertical page cutoff on touch terminals.

---

6. Daily Operational Procedures #

Performing a Stock Verification Check

1. Navigate to Dashboard ➔ Store from the main navigation sidebar.
2. Ensure the Inventory tab is active (Tab 0).
3. View the top summary counter pill:
   • Displays total primary products (XP) and total sub-products (YS).
   • Displays aggregate primary and secondary reserved quantities with tooltip badges.
4. Locate the desired product by typing its barcode or name into the search field.
5. Click the chevron toggler (>) next to the primary item to inspect individual variant rest levels.
6. Verify that Rest accurately reflects shelves minus un-finalized customer baskets.