System Purpose

The Inventory Management System tracks stock levels, deliveries, usage, and reorder workflows for Richter's Lawn Care (RLC) and GreenX (GX). It solves three problems:

1. Visibility — managers see real-time stock status (in-stock / low / out) across departments (Lawn, Tree, Pest, Fleet, General)
2. Accountability — every movement is logged as a transaction, creating a full audit trail
3. Compliance — weekly physical counts are tracked per company, with automated compliance checks and escalation tasks

Design Philosophy: Reference Model

TEOD (Truck End-of-Day) forms log what technicians used in the field, but this data is reference only. It does not change stock levels. The source of truth for inventory quantities is the weekly physical count submitted by managers.

This is intentional. Field usage data is approximate (generic labels like "Lawn Fertilizer (bags)" with no SKU). Actual stock is confirmed by a human walking the warehouse.

Data Flow

TEOD Form Submit
  └─→ logInventoryUsage()
        └─→ inventory_transactions (type = 'usage_reference', prev/new qty = 0)
             └─→ Reference only. Does NOT update current_quantity.

Weekly Physical Count
  └─→ POST /api/inventory/count
        ├─→ inventory_counts (count header record)
        ├─→ inventory_count_items (per-item counted vs. previous quantity)
        ├─→ inventory_transactions (type = 'count', records difference)
        └─→ UPDATE inventory_items.current_quantity = counted value  ← SOURCE OF TRUTH

Vendor Delivery (via PO Receive)
  └─→ POST /api/inventory/purchase-orders/:id/receive
        ├─→ UPDATE purchase_order_items.quantity_received
        ├─→ UPDATE inventory_items.current_quantity += received
        ├─→ inventory_transactions (type = 'delivery')
        └─→ PO status → 'partial' or 'complete'

Vendor Delivery (direct, no PO)
  └─→ POST /api/inventory/deliveries
        ├─→ inventory_deliveries + inventory_delivery_items
        ├─→ UPDATE inventory_items.current_quantity += received
        ├─→ inventory_transactions (type = 'delivery')
        └─→ Auto-resolves open low-stock tasks if stock exceeds threshold

Manual Transaction
  └─→ POST /api/inventory/transactions
        ├─→ inventory_transactions (type = 'use', 'receive', 'adjust', or 'return')
        └─→ UPDATE inventory_items.current_quantity  ← direct update

Key Tables

Role Permissions Matrix

Department Visibility (RBAC)

Non-leadership users see inventory scoped to their department plus General:

• Lawn / Lawn Care → Lawn + General
• Tree / Tree Care → Tree + General
• Pest / Pest Control → Pest + General
• Fleet / Mechanic → Fleet + General
• Office / Admin / Leadership → all departments

Multi-Tenant Scoping

Items have a company field: RLC, GX, or BOTH. Non-leadership users are automatically filtered to their company. Leadership sees everything. The BOTH value means the item is shared across brands (e.g., common supplies).

Automated Behaviors

1. Low-stock task creation — when a physical count puts an item at or below its reorder threshold, a task is auto-created and assigned to the company's manager with 48-hour due date
2. Low-stock alert cooldown — alerts respect a cooldown period (default 24 hours) to avoid spam
3. Compliance task auto-resolve — submitting a count auto-resolves any open inventory_compliance task for that company
4. Delivery auto-resolve — receiving a delivery that pushes stock above the reorder threshold auto-completes open low-stock tasks for that item
5. Reorder → PO conversion — approving a restock request with a vendor auto-creates a draft PO with line items

A practical guide for managers operating the Inventory Management System in The Yard portal.

Where to Go for What

Quick reference for common inventory tasks:

1. Running a Weekly Physical Count

Physical counts are the source of truth for inventory levels. TEOD usage logs are reference only — they do not change stock numbers.

How often: Weekly recommended, monthly minimum. The system tracks compliance per company (Richter's and GreenX separately) and creates escalation tasks if a count is overdue by more than 7 days.

Steps

1. Open the portal and navigate to the Inventory tab
2. Click Physical Counts (the Counts tab)
3. You'll see compliance cards at the top showing each company's count status (compliant = counted within 7 days)
4. Click Submit Count or use the Run Count button in the page header
5. This opens the inventory count form
6. Select your company (RLC or GX) and department
7. For each item, enter the quantity you physically counted
8. Add any notes if needed
9. Submit the count

What happens when you submit

• A count record is created with your name and the submission date
• For each item, the system:
  • Records the previous quantity and the counted quantity
  • Creates a count transaction in the transaction history
  • Updates current_quantity on the item to match what you counted
• If any item falls at or below its reorder threshold, a reorder task is auto-created and assigned to the manager
• If there was an open compliance task for your company, it is auto-resolved

2. Receiving a Delivery

There are two ways to receive deliveries: against a Purchase Order, or as a standalone delivery.

Receiving Against a Purchase Order

1. Navigate to Inventory → Purchase Orders tab
2. Find the PO with status Submitted or Partial
3. Click Receive Delivery on the PO
4. For each line item, enter the quantity received
5. Submit

Partial vs. Complete:

• If all line items are fully received (quantity_received ≥ quantity_ordered for every item), the PO status changes to Complete
• If some items are still short, the PO status changes to Partial — you can receive again later for the remaining items

What updates:

• Each item's current_quantity increases by the amount received
• A delivery transaction is logged per item with previous and new quantities
• The transaction notes reference the PO number

Standalone Delivery (No PO)

1. Click Receive Delivery in the Inventory page header
2. This opens the delivery receiving form
3. Enter: delivery date, supplier name, invoice number (optional), company
4. Add line items: select the inventory item, enter quantity received and unit cost
5. Submit

What updates:

• A delivery record is created with the supplier and invoice info
• Each item's current_quantity increases by the received amount
• delivery transactions are logged
• If the new stock level exceeds the reorder threshold, any open low-stock task for that item is auto-completed

3. Creating a Purchase Order

1. Navigate to Inventory → Purchase Orders tab
2. Click New PO
3. Select a vendor from the dropdown (vendors must be added first — see Section 5)
4. Add line items: pick inventory items, enter quantity to order and unit cost
5. Set an expected delivery date if known
6. Add notes if needed
7. Save — the PO is created in Draft status

Submitting the PO

1. Find your draft PO in the Purchase Orders list
2. Click Submit
3. Status changes from Draft to Submitted

PO Status Flow

Draft → Submitted → Partial → Complete
                  ↘ Cancelled

• Draft — created but not yet sent to vendor
• Submitted — order placed with vendor (manually, outside the system)
• Partial — some items received, others still outstanding
• Complete — all items fully received
• Cancelled — order cancelled (only draft or submitted POs can be cancelled)

PO Numbering

PO numbers are auto-generated: PO-2026-0001, PO-2026-0002, etc. The sequence resets each year.

4. Approving Reorder Requests

Lead Techs and others can submit reorder requests for existing items (restock) or request entirely new items.

Steps

1. Navigate to Inventory → Requests tab
2. A badge on the tab shows the count of pending requests
3. Review each pending request — you'll see:
   • Item name and current stock level
   • Requested quantity
   • Urgency level (critical, high, normal, low)
   • Who requested it and why
   • Suggested vendor (if provided)
4. For each request, choose:
   • Approve — if a vendor is specified, a draft PO is auto-created with the requested items. For new-item requests, the item must be added manually after approval.
   • Reject — enter a reason for the rejection

Urgency Levels

Requests are sorted by urgency:

Request Types

• Restock — an existing item needs more stock. Requires an item_id.
• New Item — a product we don't currently track. Requires item_name and description. After approval, Leadership adds it to the inventory catalog manually.

5. Managing Inventory Items

Adding a New Item

1. In the Items tab, click Add Item (visible to Manager and above)
2. Fill in:
   • Name — descriptive name (e.g., "24-0-11 Fertilizer 50lb")
   • SKU — unique identifier (required, must not duplicate)
   • Department — Lawn, Tree, Pest, Fleet, or General
   • Unit — bags, gallons, oz, each, etc.
   • Unit Size — optional (e.g., "50lb" for a 50lb bag)
   • Company — RLC, GX, or BOTH (shared item)
   • Reorder Threshold — when stock falls to this level, alerts trigger (default: 10)
   • Reorder Quantity — suggested quantity to order (default: 50)
   • Cost Per Unit — for value tracking
   • Supplier — free-text supplier name
   • Storage Location — where it's stored in the warehouse
3. Save — the item is created and a default low-stock alert is set up

Editing an Existing Item

1. Find the item in the Items tab
2. Click the edit action
3. You can update: name, SKU, department, unit, quantities, thresholds, supplier, vendor link, storage location, sort order, notes, and whether it requires counting

Deactivating an Item

• This is a soft delete — the item is marked is_active = 0 and hidden from the default view
• All transaction history is preserved
• Only Leadership can deactivate items
• Deactivated items can be shown by toggling the active filter

Setting Reorder Thresholds

• Each item has a reorder_threshold — when current_quantity drops to or below this number during a transaction, a low-stock alert fires
• Alerts have a cooldown (default 24 hours) to prevent notification spam
• Set thresholds based on how fast the item is consumed and how long delivery takes

Item Images

Managers can upload product photos (JPG, PNG, WebP, GIF — max 5MB). Images are stored in R2 and displayed in the item detail view.

6. Understanding the Dashboard

Summary Stats

At the top of the Inventory page, four cards show:

Department Filter

Use the department dropdown in the header to filter the entire view to one department. Your RBAC role may limit which departments you see.

Tabs

TEOD Usage Reference Transactions

In the Transactions tab, you may see entries with type usage_reference. These come from TEOD form submissions and show what technicians reported using in the field. Key points:

• These are reference only — they do not affect current_quantity
• They use generic labels (e.g., "Lawn Fertilizer (bags)") rather than specific SKUs
• The item_id is often REF_GENERIC (a placeholder, not a real item)
• Use this data to cross-reference against physical counts, but don't rely on it for stock accuracy

Transaction History Per Item

Click on any item to see its full transaction history, including deliveries, counts, usage references, and manual adjustments.

7. Photo Invoice Scanning (Phase 3)

When a delivery arrives, you can use your phone camera to speed up receiving:

1. Navigate to Inventory → Purchase Orders → find the submitted PO → Receive Delivery
2. Tap 📷 Choose / Take Photo at the top of the form
3. Point your camera at the packing slip — good lighting, hold steady, make sure all line items are visible
4. AI reads the document and pre-fills item quantities — matched fields are highlighted in green
5. Review each line carefully — adjust any quantities that look wrong
6. Hit Record Receipt to confirm — only then are stock levels updated

Tips for Best Results

• Flat surface, good lighting — avoid shadows and glare
• Include the full invoice in the frame (all line items, vendor name, invoice number)
• If the scan returns partial results, you can re-scan or fill remaining items manually
• The scanner also auto-fills the invoice number field if it can read it
• Works with packing slips, delivery tickets, and invoices from any vendor

For developers and Stan when debugging or extending the inventory system.

Source: functions/lib/inventory.ts (all API endpoints) and functions/lib/teod.ts (usage reference logger).

1. API Endpoints

All endpoints require authentication via session token (cookie, Authorization: Bearer, or X-Session-Token header). The inventory router is at handleRequest() in functions/lib/inventory.ts.

Items

Transactions

Bulk Use (TEOD Integration)

Physical Counts

Vendors

Purchase Orders

Reorder Requests

Dashboard / Digest / Stats

Deliveries (Direct)

Categories

Manual Orders (Legacy)

2. TEOD Bulk-Use Integration

logInventoryUsage() Helper

Location: functions/lib/teod.ts, lines 12–40

Signature:

async function logInventoryUsage(env: Env, data: {
  items: Array<{
    item_id: string | null;
    item_label: string;
    department: string;
    quantity: number;
    unit: string;
  }>;
  employee_id: string;
  employee_name: string;
  source_form: string;
  submission_id: string;
  company: string;
  submission_date: string;
}): Promise<void>

Behavior:

• Iterates over items, skipping any with quantity <= 0
• Inserts usage_reference transactions with previous_quantity = 0 and new_quantity = 0 (does NOT read or update the item's actual quantity)
• Uses item_id || 'REF_GENERIC' — most TEOD items pass null for item_id
• Notes format: "{item_label} ({quantity} {unit}) used on {submission_date}"
• Called with .catch(() => {}) — fire-and-forget, wrapped in try/catch, never blocks TEOD submission

What Each TEOD Type Logs

REF_GENERIC Placeholder

When item_id is null (which is the case for all TEOD usage logging), the transaction is recorded against the special ID REF_GENERIC. This is a placeholder row in inventory_items with is_active = 0. It exists solely as an FK target so usage_reference transactions don't violate foreign key constraints. It is never shown in the active inventory list.

Fire-and-Forget Pattern

All TEOD inventory logging follows this pattern:

try {
  // build usageItems array
  if (usageItems.length > 0) {
    logInventoryUsage(env, { ... }).catch(() => {});
  }
} catch (e) { /* never block TEOD on inventory errors */ }

The TEOD submission response is returned regardless of whether inventory logging succeeds.

3. Transaction Types

Transaction Record Fields

id, item_id, transaction_type, quantity, previous_quantity, new_quantity,
employee_id, employee_name, notes, source_form, source_submission_id, company, created_at

For usage_reference transactions, previous_quantity and new_quantity are always 0 — they're not meaningful since the transaction doesn't affect stock.

4. FK Cascade Notes

• FK enforcement is ON in D1
• inventory_items delete is soft (is_active = 0) — no cascade needed, transactions retain their item_id reference
• PO delete (Leadership only):
  1. Nullifies reorder_requests.po_id (nullable FK — keeps request history intact)
  2. Deletes purchase_order_items where po_id matches
  3. Deletes the purchase_orders record
• Count delete (Leadership only):
  1. Deletes inventory_count_items where count_id matches
  2. Deletes the inventory_counts record
  3. Does NOT roll back the quantity changes made when the count was submitted
• inventory_transactions.item_id: Uses REF_GENERIC for generic/null items (TEOD usage). This satisfies FK constraints without pointing to a real active item.
• Vendor delete is soft (is_active = 0). Items referencing the vendor via vendor_id are unaffected.

5. Known Limitations / Phase 3 Roadmap

By Design

• No SKU mapping for TEOD usage — TEOD logs use generic labels ("Lawn Fertilizer (bags)") with no item_id. This is intentional: weekly physical counts are the source of truth, not field estimates.
• No auto-email on PO submit — managers contact vendors manually. This avoids unintended orders from accidental submissions.
• Usage references don't affect stock — usage_reference transactions always record previous_quantity = 0, new_quantity = 0. If you want accurate real-time stock, look at physical counts and deliveries.
• Count delete doesn't roll back — deleting a count removes the record but the quantity update it made to inventory_items.current_quantity persists. To correct, submit a new count or use a manual adjustment.

Current Gaps

• No batch import — the UI has an Import CSV button but the backend endpoint is TBD
• Reorder request approval RBAC — the approve/reject endpoints don't enforce Leadership-only at the API level (the UI hides buttons for non-Leadership, but the API accepts any authenticated user)
• Vendor endpoints have no role check — any authenticated user can create/edit/delete vendors at the API level

Phase 3: Photo Invoice Scanning ✅ Live

Deployed 2026-03-16. Manager or Lead Tech photographs a packing slip, AI pre-fills quantities, human confirms before stock updates. See Section 7 in the Manager Guide for usage instructions.