ShopOS

Know what is selling, what is expiring, and what to do next.

ShopOS is a mobile-friendly retail workspace for small kirana and general stores. This first milestone is a functional frontend prototype: receiving a purchase, making a sale, and recording stock loss all update the same batch inventory ledger and derived business metrics.

Try the demo

1. Open Overview for sales, estimated gross profit, expiry alerts, and low stock.
2. Open Sales, add 20 units of Amul Taaza Milk, choose a payment method, and complete the sale. This spans two batches, demonstrating FEFO and cost allocation.
3. Open Inventory → Amul Taaza Milk. The early batch is depleted; the later batch retains 10 units. The movement history records both deductions.
4. Add a purchase for milk with a unit cost and an expiry on or after 7 September 2026. It creates a separate batch.
5. Open Expiry center → Already expired, review Amul Masti Dahi, and record a six-unit expiry loss against batch B-114.
6. Ask Insights what to reorder or what is expiring. Answers are computed from the current demo state.

The clock is deliberately fixed to 7 September 2026 so the demo is reproducible. It includes 12 products, 14 batches, 540 synthetic historical sales, and a reconciled stock ledger. Synthetic history demonstrates behavior; it is not a real store's financial record. Changes live in memory and reset on refresh. The deployed demo is owner-private until its audience is explicitly changed.

Implemented

Area	Behavior
Overview	Derived daily sales, batch-based COGS and gross profit, items sold, inventory cost, 7/30-day chart, recent sales and top products
Billing	Search by product or SKU, category filters, cart quantities, stock validation, payment-method recording, receipt
Inventory	Search, category and stock filters, sellable vs physical stock, batch details, CSV export, product creation
Purchasing	Product/supplier entry, positive whole quantities, exact unit cost, expiry validation and receipt into a new batch
Expiry	Today/7/30-day and expired batch windows, value at cost, earliest-expiry allocation, expired-stock exclusion
Audit	Append-only movement records for opening stock, purchases, sales and stock losses; balances reconcile with the ledger
Insights	Deterministic answers using current sales, costs, expiry and seven completed days of demand
UI	Responsive layouts, accessible component primitives, keyboard-operable dialogs, validation, feedback and reset confirmation

Deliberate limits

• No database or multi-user authentication. The prototype has no durable store data or tenant isolation. Hosting access control is separate from app-owned authentication.
• No payment collection. Cash, UPI and Card are recorded labels only.
• No live LLM or OCR. Insights use rules; invoice scanning is clearly labeled as a preview and leads to manual purchase entry.
• No GST calculation or filing. Receipts are demo receipts, not tax invoices.
• Gross profit is not net profit. Operating expenses and tax adjustments are excluded. Stock write-offs are ledger events and do not rewrite historical sales COGS.
• Whole retail units only. Fractional weights, discounts, returns, cancellations, supplier lead times, and price editing are future work.
• No concurrent checkout or retry guarantees. Atomic in-memory state transitions demonstrate the model. Production requires transactional database locks, idempotency, and server-side validation.

Stack

TypeScript, React 19, Next.js App Router conventions through Vinext, Tailwind CSS 4, shadcn/Radix components, Lucide icons, and a Cloudflare-compatible Worker build. There are no AI API keys or database credentials in this prototype.

Vinext is used by the supplied hosting environment. The planned FastAPI/PostgreSQL service from the product brief is a future milestone, not an implemented backend. The domain logic is separate from React to make that transition reviewable.

Run locally

Use Node.js 24 (Node 22.13+ is supported by the scaffold) and npm.

npm ci
npm run dev

Open the address reported by the development server.

# Business invariants, without a full build
node --experimental-strip-types --testtests/shop.test.mjs

# Production build and the repository test suite
npm test

# Type checking, including generated Worker runtime declarations
npx tsc --noEmit --incremental false

The committed generated Worker declarations can be regenerated after a build:

npx wrangler types --config dist/server/wrangler.json worker-configuration.d.ts

Architecture and decisions

File	Responsibility
app/page.tsx	Retail screens, forms, and session state
app/shop.css	Responsive product theme and layouts
app/globals.css	Shared semantic theme tokens
lib/shop.ts	Pure stock, sale, purchase, and analytics operations
worker/index.ts	Hosting entrypoint
tests/shop.test.mjs	Business invariant tests

Money uses integer paise. Display formatting is a boundary concern; every sale snapshots selling price and exact allocation costs. Later purchases never rewrite old profit.

Product and batch are distinct. FEFO orders sellable batches by expiry, then received date and ID. Undated batches follow dated batches. A batch is sellable through its expiry date; earlier dates are excluded. Physical stock includes expired goods until a loss is recorded.

Validate the whole cart before mutation. Duplicate product lines are aggregated before checking stock. Successful operations return new state; rejected operations leave the prior state intact. Every batch quantity must equal its summed ledger movements.

Forecasting is explicit and simple. Stock cover is sellable quantity divided by daily sales velocity over the last seven completed days. No history means no reliable coverage estimate. Reorder suggestions target seven days and are only a starting point; they do not model lead time, perishability, seasonality, or open orders.

Insights cite their inputs. The demo explains calculations and refuses to invent causal claims about profit changes. Production LLM responses should use store-scoped tools rather than receive unrestricted database dumps.

Verification

Business tests cover ledger reconciliation, FEFO spanning costs, gross-profit deltas, expired inventory, duplicate-line overselling, atomic rejection, purchases preserving historical cost, invalid expiry dates, stock-loss auditability, and SKU uniqueness. A production Worker render test checks the dashboard and demo disclosures. The scaffold also retains its component contract tests. Browser and device testing have not yet been performed.

Next milestones

1. Validate this frontend workflow with real shop owners; improve keyboard billing and mobile checkout based on feedback.
2. Add PostgreSQL and FastAPI, authenticated store context, tenant-scoped queries, transactional stock allocation, idempotent sale submission, and migrations.
3. Add returns, discounts, tax-aware accounting, durable audit trails, and concurrency/authorization integration tests.
4. Add invoice extraction with correction and confirmation, then a tool-grounded shop assistant with source provenance.
5. Add demand-aware reorder planning, supplier price monitoring, and measured wastage analytics.

GitHub showcase

Keep this README, domain tests, and lockfile with the repository. Include screenshots or a short walkthrough after reviewing the UI. Publish only synthetic data and clearly distinguish the prototype from production capabilities. The .openai/hosting.json file identifies this hosted instance; preserve it for this project, and remove its instance identity when creating an independent template.