SnapStock-AI

Small fruit and vegetable retailers still manage perishable stock largely by hand: staff count items visually, jot quantities in notebooks or spreadsheets, and judge freshness by eye. That process is slow, inconsistent between people, and easy to get wrong when shelves are crowded or lighting is poor. Over-ordering leads to spoilage and waste; under-counting leads to empty shelves and lost sales. Enterprise retail systems and sensor-heavy IoT setups exist, but they are expensive, complex to install, and poorly suited to a single neighbourhood greengrocer who already owns a smartphone. What was missing was a lightweight way to turn an ordinary shelf photo into usable stock and freshness insight without new hardware, ERP licences, or specialised training.

SnapStock-AI is a multi-tenant-oriented web SaaS prototype that turns smartphone or webcam images into produce counts and freshness scores. Vendors use a React dashboard to capture or upload a shelf photo; a Node.js/Express API authenticates the request, accepts the multipart image, and forwards it to a Python FastAPI AI microservice. That service runs YOLOv8 for object detection and counting, then MobileNet-based classification for freshness on each detected crop, and returns structured JSON (labels, bounding boxes, counts, confidence). Results are shown in the UI; authentication (register, email verification, login, password reset) is backed by PostgreSQL with bcrypt and JWT. Architecturally the system is a modular Express backend plus a separate AI microservice, so UI, business logic, and heavy ML inference stay independently maintainable. Docker Compose runs PostgreSQL for local development.

What we set out to build SnapStock-AI targets small-scale retailers who need better visibility into perishable inventory without adopting a full retail ERP. The product vision is a responsive web app where an owner or employee can scan a shelf, see what was detected and how fresh it looks, and eventually manage inventory, alerts, and analytics under a business tenant. The academic delivery window is a working prototype with clear architecture, not a production multi-region SaaS.

Methodology and architecture We separated the system into three deployable concerns:

Client (client/) — React 19, TypeScript, Vite, Tailwind. Landing pages, auth flows, and a dashboard including a camera/file scan experience. Auth state lives in React Context with JWT stored for protected routes.

API (server/) — Express modular monolith. Feature modules follow routes → controller → service → repository → entity. Auth is end-to-end: registration with bcrypt hashing, email verification and password-reset tokens via Nodemailer/SMTP, login that requires a verified email, and JWT issuance. Detection is a gateway: multer receives the image and axios proxies it to the AI service. TypeORM maps users and token tables; schema changes go through versioned migrations.

AI service (ai-service/) — FastAPI loads YOLO and MobileNet models at startup (with optional Hugging Face download), exposes /detect, /predict, and the combined /analyze pipeline (detect → crop → classify → aggregate). This isolation keeps TensorFlow/Ultralytics out of the Node process and allows AI to restart without taking down login.

Documentation follows an IEEE/RUP-style SRS and Software Architecture Document using Kruchten’s 4+1 views (use-case, logical, process, deployment, implementation), plus design diagrams for scan pipelines, sequences, and deployment.

Challenges and how we handled them Stack mismatch for ML — Running YOLO and TensorFlow inside Node is awkward. We extracted a FastAPI microservice and kept Express as the trusted boundary (clients never call AI or the database directly).

Model size and cold start — Weights are large. Models load once at FastAPI lifespan (and via cached loaders) rather than per request; first-run download from Hugging Face needs network and optional tokens.

Prototype vs full product — Dashboard pages for inventory, alerts, analytics, and shelves are largely UI-ready with mock or local state; scan history is not fully persisted yet. We document intended multi-tenancy (business_id, OWNER/EMPLOYEE) in migrations and design while focusing implementation on auth + AI scan first.

Security hardening in progress — bcrypt, JWT issuance, verification gates, and email-enumeration-safe messages are in place. JWT middleware exists but is not yet applied to all routes; Helmet/Zod hardening and full RBAC enforcement remain next steps.

Environment friction — AI dependencies need a supported Python (e.g. 3.10–3.12); newer runtimes may lack TensorFlow wheels. Local setup uses Docker for Postgres and separate processes for client, server, and AI.

Results so far Working auth: register → verify email → login → logout; forgot/reset password with expiring tokens. Working scan path: camera or upload → Express → /analyze → detections with counts and per-item freshness (good/bad in the current model). Clear module boundaries and repo layout that match the architecture story evaluators and employers expect. Design artefacts (SAD, process/deployment diagrams, pattern notes) that explain why the system is shaped the way it is. Future work Persist scans and detections; connect shelves and inventory to the database; auto-update stock from accepted scans. Wire JWT on protected APIs; send Authorization from the client; enforce tenant isolation and roles. Alerts for low stock and spoilage; real analytics; admin portal. Move freshness toward the planned Fresh / Medium / Spoiled classes if the model is retrained. Graceful degradation when AI is down; health checks; tests and production hardening.