Product Requirements Document (PRD): ClearPath Inventory Optimizer

Status: Final Draft | Version: 1.0 (2026 Standard) | Owner: Senior Product Manager

1. Executive Summary

ClearPath Inventory Optimizer is a high-performance B2B SaaS platform designed for mid-to-large e-commerce retailers. It solves the critical problem of "deadstock"—unsold inventory that traps capital and occupies expensive warehouse space. By leveraging real-time FIFO (First-In-First-Out) aging logic and automated markdown optimization, ClearPath transforms stagnant inventory into liquidity through intelligent bundling and scheduled promotional runs.

2. Problem Statement

Retailers currently lose 12–18% of their annual revenue to inventory depreciation and storage costs. Manually identifying which SKUs are "dead" (stagnant for >90 days) is labor-intensive. When retailers do act, they often use "gut-feel" markdowns that either fail to move the stock or erode margins unnecessarily. There is no unified tool that identifies deadstock, calculates the optimal liquidation price, and executes the sale across multi-channel storefronts.

3. Goals & Success Metrics

Inventory Velocity: Increase inventory turnover rate by 20% within the first six months.
Capital Recovery: Target a 15% reduction in "Capital at Risk" for active users.
Efficiency: Reduce the time spent on markdown management from hours to minutes via automation.
Success Metric: $GMROI$ (Gross Margin Return on Investment) improvement across liquidated categories.

4. User Personas

5. User Stories

As an Inventory Manager, I want to sync my Shopify/WooCommerce store so that I can see a real-time list of all aging inventory.
As an Owner, I want to see "Capital at Risk" visualized so that I understand the financial urgency of clearing specific batches.
As a Merchandiser, I want the system to suggest "Pop-to-LT" (Popular to Long-Tail) bundles so that I can move deadstock without deep individual discounts.
As a Warehouse Supervisor, I want to receive Slack alerts when a specific SKU hits "Dead Status" (e.g., 120 days since last sale).

6. Functional Requirements

6.1. FIFO Inventory Aging Engine

Hybrid Ledger-State Model: Track InventoryBatches with remaining_quantity to avoid heavy historical recalculations.
Status Classification: Automatically tag items as Active, Slow-Moving (60-90 days), or Deadstock (90+ days).

6.2. Markdown Optimization & Bundling

Margin Protection: Users set "Floor Prices" (e.g., COGS + 5%) that the algorithm cannot cross.
Pop-to-LT Engine: Automated pairing of high-velocity "Anchor" products with stagnant "Add-ons."
Dynamic Elasticity: Algorithm calculates price drops where Sales Lift > Margin Loss.

6.3. Automated Promo Scheduler

Multi-Channel Sync: Push price updates to Shopify/WooCommerce via GraphQL/REST.
Flash Sale Logic: Schedule start/end dates for liquidations with automatic price reversion.

7. Technical Requirements

7.1. Tech Stack (2026 Stable Versions)

Frontend: Next.js v16.1.3 utilizing Turbopack, the new proxy.ts architecture for edge-side logic, and React 19 Compiler for auto-memoization.
Backend: NestJS v11.1.12 running on Express 5, utilizing built-in JSON logging and Cache Module v6 (Keyv-based).
Styling: Tailwind CSS v4.1.18 with the Rust-based Oxide engine and CSS-First configuration (no tailwind.config.js).
Database: PostgreSQL 17 with Declarative Partitioning and BRIN indexes for high-volume movement logs.
Background Jobs: BullMQ for handling 50k+ SKU syncs via addBulk() and Flow Producers.
Auth: Clerk with Organization Management for multi-tenant B2B isolation.

7.2. Integrations

Shopify Admin API (2026-01): Utilizing bulkOperationRunMutation for large catalog updates.
Universal Commerce Protocol (UCP): Implementation of /.well-known/ucp-capabilities for AI-agent discovery.
Klaviyo: API integration to trigger "Back in Stock" or "Liquidation Alert" email flows.

8. Data Model

Entity: `Organization`

id: UUID (Primary Key)
clerk_org_id: String (Unique Index)
settings: JSONB (Markdown thresholds, currency)

Entity: `ProductRecord`

id: UUID
org_id: UUID (FK)
sku: String
unit_cost_encrypted: BYTEA (AES-256-GCM)
total_stock: Integer

Entity: `InventoryBatch` (FIFO Logic)

id: UUID
product_id: UUID (FK)
acquisition_date: Timestamp
initial_quantity: Integer
remaining_quantity: Integer (Indexed for > 0)

9. API Specification (Key Endpoints)

POST /v1/sync/trigger: Initiates a BullMQ background job to pull catalog data.
GET /v1/inventory/deadstock: Returns prioritized list of SKUs filtered by capital_at_risk.
POST /v1/promos/schedule:
- Request: { bundle_id: UUID, discount_pct: 20, start_date: ISO8601 }
- Response: { status: "scheduled", job_id: String }

10. UI/UX Requirements

The Bento Grid Dashboard: Modular tiles for "Top Deadstock," "Warehouse Space Saved," and "Recovered Capital."
Capital at Risk Visual: Neon-glow Area Charts (Recharts) using SVG filters to highlight volatility.
Glassmorphism UI: Translucent cards with backdrop-filter: blur(10px) for a modern enterprise feel.
Action Proximity: Every chart showing a "Slow Mover" must have an immediate "Bundle" or "Discount" action button attached.

11. Non-Functional Requirements

Performance: Background syncs for 50k SKUs must complete in < 5 minutes via job sharding.
Security: COGS data must be encrypted using AES-256-GCM with unique IVs stored per-row.
Availability: 99.9% uptime using AWS ECS (Fargate) for the NestJS API.

12. Out of Scope

Physical warehouse management (WMS) features like bin-tracking or forklift routing.
Direct shipping label generation (handled by third-party integrations).
Returns management and reverse logistics processing.

13. Risks & Mitigations

Risk: API Rate Limiting by Shopify/WooCommerce during bulk sync.
- Mitigation: Implement BullMQ's built-in limiter and Shopify’s bulkOperationRunMutation.
Risk: Data Leakage between multi-tenant organizations.
- Mitigation: Strict RLS (Row Level Security) in PostgreSQL using the Clerk orgId as a session variable.

14. Implementation Tasks

Phase 1: Project Architecture & Setup

[ ] Initialize Next.js 16.1.3 project with Turbopack and Proxy API.
[ ] Set up Tailwind CSS 4.1.18 using @theme blocks in CSS (CSS-First config).
[ ] Configure NestJS 11.1.12 with PostgreSQL and TypeORM/Prisma.
[ ] Initialize Clerk multi-tenant middleware and organization logic.

Phase 2: Inventory Sync Engine

[ ] Create PostgreSQL schema for FIFO Batch tracking (Hybrid Ledger-State).
[ ] Implement Shopify OAuth flow for tenant store connection.
[ ] Build BullMQ workers with addBulk() logic for 50k+ SKU ingestion.
[ ] Implement AES-256-GCM encryption service for sensitive COGS fields.

Phase 3: Analytics & Identification

[ ] Build the "Capital at Risk" identification logic using FIFO aging.
[ ] Develop Recharts dashboard with Bento Grid layout and Neon-glow filters.
[ ] Create "Bundling Engine" API using Pop-to-LT pairing algorithms.

Phase 4: Promo Execution

[ ] Build the Promo Scheduler UI with calendar integration.
[ ] Implement Shopify GraphQL bulk mutation service for price updates.
[ ] Create Slack Webhook integration for automated deadstock alerts.

Phase 5: Hardening & Compliance

[ ] Perform security audit on AES key management (Envelope Encryption).
[ ] Implement partial indexing on remaining_quantity > 0 for query optimization.
[ ] Configure Vercel/AWS deployment pipeline with environment-specific secrets.