StockSense

Inventory tracking and demand forecasting for small shops. Owners and staff record stock and sales; StockSense forecasts the next 14 days of demand for every product and lists what to reorder before it runs out.

Live demo: https://stocksense-phi-tan.vercel.app — tap Try the live demo (no sign-up), or log in with:

Email	Password
[email protected]	stocksense-demo-2026

The demo is a sample kirana shop with a year of synthetic sales. It resets every night, so feel free to record sales, count stock or import a CSV.

Reorder list	Stock count	On a phone

What it does

• Record sales and stock in seconds (stock is a ledger; a sale lowers it automatically), or count the shelf and save only the differences.
• Import a year of sales from a CSV. It is validated in the browser, again on the server and again in SQL; bad rows are listed, good rows are imported (the database inserts 10,000 rows in under a second).
• Forecast the next 14 days per product with a LightGBM model that knows weekdays, recent demand and festivals.
• Reorder list: Order now / Order soon / Enough stock, with days of stock left, supplier lead time and a suggested quantity.
• Teams: owners invite staff by email; staff can record sales and stock but not change products, imports or the team.

Architecture

flowchart LR
    U(["Shop owner or staff<br/>browser or phone"]) --> W

    subgraph Vercel
      W["Next.js 16 web app<br/>React 19, Server Actions"]
    end

    subgraph Supabase
      A[Auth]
      D[("Postgres + row-level security<br/>shops, products, sales, stock,<br/>forecasts")]
    end

    subgraph GitHub Actions
      N["Nightly job, about 02:11 IST<br/>LightGBM per shop"]
    end

    R["FastAPI on Render<br/>/health, /me, JWT verification<br/>(deployed, not called by the app yet)"]

    W -- "sign-in, queries, RPCs" --> A
    W -- "reads and writes as the user" --> D
    N -- "reads daily_sales" --> D
    N -- "writes 14-day forecasts" --> D

Part	Tech	Folder
Web app	Next.js 16, React 19, TypeScript, Tailwind CSS 4	apps/web
Auth and database	Supabase (Auth, Postgres, row-level security)	supabase
Forecasting	Python 3.12, pandas, LightGBM — see ml/README.md	ml
API service	Python 3.12, FastAPI, PyJWT. Verifies Supabase tokens; deployed but not used by the web app yet (forecasts do not go through it)	services/api
CI/CD	GitHub Actions (lint, tests, build, backtest, end-to-end tests, nightly forecast, screenshots), Vercel, Render	.github/workflows
End-to-end tests	Playwright (Python), pytest	e2e

Why forecasts run nightly in GitHub Actions and not on the API: a training run peaks at about 270 MB, the free Render instance has 512 MB, sleeps when idle and has no disk. Precomputing once a night costs nothing and keeps the dashboard instant.

Security notes

• Sessions use Supabase's HTTP-only cookies, refreshed on every request by src/proxy.ts; protected pages are checked on the server with getUser(), never the cookie alone.
• Every table has row-level security, so a user can only read or write data for shops they belong to (tested, see below). The nightly job's secret key lives only in GitHub secrets.
• The API verifies Supabase access tokens itself (JWKS for ES256/RS256), checking signature, issuer, audience and expiry. alg: none and unknown algorithms are rejected.
• Login redirects only accept same-site paths. Sign-up and forgot-password show the same message whether or not an email is registered.
• All input is validated on the server with Zod; users see plain-language errors, never internal ones.

Forecast quality

Rolling-origin backtest: at each of 8 weekly origins the model is retrained on what was known that day only and scored on the next 14 days for every product. WAPE = total absolute error / total units sold (lower is better). The "best simple rule" is the best of four baselines: last day, same weekday last week, 7-day and 28-day averages.

Data	Series × days	Forecasts scored	Best simple rule	LightGBM	Improvement
Kaggle Store Item Demand (public benchmark)	500 × 1,826	56,000	18.3% (7-day avg)	11.1%	39.2%
Sample shop, 1 year (synthetic)	30 × 365	3,360	26.5% (28-day avg)	24.5%	7.6%
Synthetic shop, 3 years	30 × 1,029	3,360	25.3% (28-day avg)	21.0%	17.1%

On the Kaggle data (10 stores × 50 items, 2013–2017) the model is also almost unbiased (+0.4% vs +5% or more for the baselines) and stays between 10% and 12.5% WAPE from 1 to 14 days ahead. Reports: ml/reports-kaggle/metrics.md (run by the Real-data benchmark workflow; the Kaggle data is never committed) and ml/reports/metrics.md (make train, also in CI). A test corrupts the future to prove no feature leaks it.

Honest caveat: the Kaggle set is a public practice dataset that is much cleaner and more regular than a small Indian shop's sales, and the other two are generated. Together they show the model reliably beats simple rules; how accurate it is for a particular shop is only known once that shop has a few months of real history.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗