Intake & Approval Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• app/api/inventory/intake/approve/route.ts
• app/api/inventory/intake/route.ts
• app/(app)/inventory/intake/page.tsx
• app/(app)/admin/approvals/page.tsx
• test-inventory-intake.sh
• README.md

The Intake & Approval Workflow is a critical component of the DRX CRM inventory management system. It provides a structured process for bringing new stock into the business while ensuring financial accuracy through cost tracking and manager oversight. The system distinguishes between standard restocking and unusual cost scenarios, triggering a mandatory approval queue when specific thresholds are met.

This workflow ensures that every addition to the inventory is logged with its associated costs (product and delivery), supplier information, and calculated unit costs. This data feeds into the business's Sales Analytics and COGS (Cost of Goods Sold) reporting, maintaining a complete audit trail for compliance.
Sources: [README.md:143-148], [app/api/inventory/intake/route.ts:111-125]

Workflow Architecture

The system utilizes a multi-stage pipeline that begins with a user submission, undergoes automated risk assessment, and ends in either automatic processing or a manual manager review.

1. Intake Submission

Users enter stock details via the mobile-optimized intake interface. The system captures the inventory item, total cost, weight or unit count, and optional delivery fees.
Sources: [app/(app)/inventory/intake/page.tsx:142-230]

2. Automated Risk Assessment

The backend evaluates the submitted cost against a 90-day historical average for that specific product. If the calculated cost per unit deviates by more than 50% from the historical average, the system flags the intake for manager approval.
Sources: [app/api/inventory/intake/route.ts:88-108], [test-inventory-intake.sh:84-115]

3. Approval Processing

Pending intakes are routed to the Approval Inbox. Managers can approve the request as-is, reject it with a reason, or apply "Override Values" to correct data entry errors before finalizing.
Sources: [app/(app)/admin/approvals/page.tsx:125-175], [app/api/inventory/intake/approve/route.ts:107-151]

The following diagram illustrates the logical flow from submission to inventory update:

Data Processing & Calculations

The workflow relies on high-precision calculations to maintain financial integrity, especially for fractional quantities common in retail.

Unit Cost Derivation

The system derives the calculated_cost_per_gram (or per unit) by dividing the total_cost by the total_weight_grams. Delivery costs are tracked separately and are not factored into the base unit cost to ensure consistent COGS tracking.
Sources: [app/api/inventory/intake/route.ts:74-75], [app/(app)/inventory/intake/page.tsx:71-78]

Impact on Inventory

When an intake is finalized (either auto-approved or manually approved), the system performs three concurrent actions:

1. Inventory Update: Increments quantity_on_hand and updates the unit_cost.
2. Cost History: Inserts a record into cost_history for trend analysis.
3. Inventory Log: Creates an audit entry of type intake and an optional entry for delivery_cost.
   Sources: [app/api/inventory/intake/approve/route.ts:178-245]

Field	Type	Description
inventory_id	UUID	Reference to the product being restocked.
total_cost	Numeric	The purchase price of the goods.
total_weight_grams	Numeric	The quantity received (min 0.01).
delivery_cost	Numeric	Optional shipping fees.
calculated_cost_per_gram	Numeric	Derived unit cost (total_cost / quantity).
status	Enum	pending, approved, or rejected.
Sources: [app/api/inventory/intake/route.ts:5-12], [app/api/inventory/intake/approve/route.ts:5-15]

API Endpoints

POST /api/inventory/intake

Initial submission point for new stock.

• Permissions: inventory.manage
• Logic: Performs cost deviation check. Returns requires_approval: true if cost is unusual.
  Sources: [app/api/inventory/intake/route.ts:16-35], [app/(app)/inventory/intake/page.tsx:112-115]

POST /api/inventory/intake/approve

Handles manager actions on pending requests.

• Permissions: is_manager RPC check.
• Actions: approve, reject.
• Overrides: Allows updating total_cost, total_weight_grams, delivery_cost, and supplier during approval.
  Sources: [app/api/inventory/intake/approve/route.ts:18-80]

The sequence below details the interaction during a manual approval:

Security & Compliance

The workflow is protected by multiple layers of security:

• Permission Guards: The UI restricts access to the intake page based on inventory.manage permissions.
• Server-Side Auth: APIs verify the user's session using Supabase Auth.
• Manager Verification: The is_manager RPC is called server-side to ensure only authorized personnel can move an intake from pending to approved.
• Immutable Logs: Once processed, inventory logs and cost history entries provide an permanent audit trail that cannot be deleted.
  Sources: [app/(app)/inventory/intake/page.tsx:112-127], [app/api/inventory/intake/approve/route.ts:70-80], [README.md:167-172]

The Intake & Approval Workflow provides a robust gatekeeping mechanism, ensuring that inventory data remains accurate and that significant financial variances are reviewed before they impact the business's bottom line.