Shelf Sense

InspirationShelfSense AI — Project Summary

1) Inspiration Perishable grocery retailers lose 15–25% of revenue to spoilage because they lack real-time visibility into batch-level expiry, demand velocity, and margin-safe markdown timing. Existing tools are either enterprise ERPs (too complex/expensive) or manual spreadsheets (error-prone). We built ShelfSense to give independent grocers an AI co-pilot that thinks like a seasoned store manager — tracking every batch, forecasting sell-through, and recommending actions that prevent waste without sacrificing margin.

2) What It Does ShelfSense is a full-stack inventory intelligence platform for perishable retail:

Module Capability Dashboard Morning briefing with urgent batch alerts, priority queue, cost exposure Inventory Batches CRUD for batch lots with use-by/best-before labels, auto cutoff calc, FEFO sorting Risk & Forecasts FEFO demand simulation → projects unsold units at cutoff → financial exposure Smart Markdowns Dynamic discount recommendations bounded by configurable gross margin floor Analytics 14/30/60-day sales trends, waste by category, recommendation completion, risk distribution Settings Store policy config (margin floor, safety stock, warning/urgent windows, timezone) AI Assistant Conversational retail co-pilot grounded in live data (Gemini 3.8 Flash + Nebius fallback) 3) How We Built It Frontend: React 19 + TypeScript + Vite + Tailwind CSS 4 + shadcn/ui (Radix primitives) Backend: Express.js + TypeScript (tsx) — REST API under /api/* Database: In-memory JSON store (data/shelfsense.db.json) with atomic writes — zero external deps AI Layer: NebiusClient with 3-tier fallback — Gemini 3.8 Flash → Nebius (Nemotron) → Conversational Retail Engine (rule-based, zero-hallucination) Risk Engine: FEFO simulation using 14-day trailing sales velocity, label-date cutoffs, demand forecasts per SKU UI/UX: Custom design system (forest green/amber palette), staggered card entrances, Material ripple buttons, animated modals/toasts 4) Challenges We Ran Into Challenge Solution Hallucination risk in AI answers 3-tier architecture: live LLM only when API keys present; otherwise deterministic conversational engine grounded 100% in verified store data Batch-level granularity vs. performance In-memory cache with 2.5s TTL; invalidated on every write — sub-ms reads for 100s of batches Margin-safe markdown math Built pricing engine that solves max discount s.t. selling_price ≥ cost / (1 - margin_floor) per batch Date/timezone bugs Store timezone enforced everywhere; all cutoff calculations use offsetDateString with configurable buffer GitHub secret scanning blocking push Sanitized .env.example — replaced real key with placeholder 5) Accomplishments We're Proud Of Zero-hallucination AI Assistant — every number in responses traces to a live batch record Margin floor enforcement at the engine level — impossible to suggest a money-losing discount Conversational retail expertise — handles FIFO/FEFO education, vendor credit strategy, cold-chain discipline, not just data queries Staggered entrance animations + ripple buttons + modal/toast system — polished, tactile UX without external animation libraries Single-command dev (npm run dev) — frontend + backend + hot reload in one process 6) What We Learned Grounding > model size — a small rule-based engine with perfect data beats a large LLM with hallucinations for domain tasks FEFO is not FIFO — most retailers confuse them; the simulation engine made the difference visible in dollars Margin floor is a hard constraint, not a suggestion — encoding it in the pricing engine prevents "well, just this once" decisions In-memory JSON + atomic writes is sufficient for single-store scale — no Postgres/SQLite needed until multi-tenancy Tailwind 4 + CSS variables enables a complete custom design system with zero config files 7) What's Next for ShelfSense Phase Target Multi-store / org support Shared policy templates, centralized analytics, role-based access Supplier integration Auto-fetch delivery schedules, push return-claim requests via EDI/API Mobile PWA Offline-capable batch scanning (camera → barcode → batch CRUD) Predictive ordering ML demand model (LightGBM on 90-day history) → suggested PO quantities Voice assistant "Hey ShelfSense, what's expiring today?" via Web Speech API Plugin marketplace Custom risk rules, report templates, POS integrations (Square, Toast, Shopify) Live Demo: http://localhost:3000/ (dev) Repo: https://github.com/tejaskumarg06-ctrl/Shelf-Sense-AI- Deploy: Ready for Vercel/Railway/Render — add env vars and go.

Built With

• antigravity
• composio
• nemotron