RetailOS

Omnichannel retail demo: online shop + in-store POS + admin inventory/promos + support chatbot/tickets, with SQLite, React, Python (FastAPI), and OpenAI.

Workshop note: This repo intentionally contains insecure patterns and code smells for training / review exercises. Do not deploy to production.

Workshop activity

Hand out docs/RetailOS_Workshop_Participant_Guide.pdf or docs/RetailOS_Workshop_Participant_Guide.docx.

Source text: WORKSHOP.md · Facilitator spoilers: WORKSHOP_FACILITATOR.md

Flow: understand product → manual hunt by team → Snyk showcase → share-out.

Requirements: Node.js 18+, Python 3.11–3.13 (setup prefers 3.13 via the Windows py launcher)

git clone <this-repo-url>
cd productionworkshop
npm run setup
npm start

Then open:

• Storefront / apps: http://localhost:5173
• API docs: http://localhost:8000/docs

npm start (same as npm run dev) runs backend + frontend together.

Demo logins

Role	Email	Password
Customer	customer@retailos.local	customer123
Cashier	cashier@retailos.local	cashier123
Admin	admin@retailos.local	admin123

Enable OpenAI (recommended)

Add your key to .env and backend/.env:

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini

Without a key, every AI feature still works via heuristic fallbacks. With a key you get live OpenAI for:

Feature	Where in UI	API
Product “you may also like”	Shop (after Add to cart)	GET /api/recommendations/{id}
Cart upsells	Cart page	GET /api/recommendations/cart/upsells
Receipt recommendations	Orders / POS after sale	created on checkout; POST /api/receipts/{order_id}/regenerate-recommendations
Smart list	Smart List page	GET /api/smart-list
Support chatbot	Support → AI chatbot	POST /api/support/chat
FAQ AI search	Support → “AI ranked”	GET /api/support/faq/ai?q=
Ticket AI summaries	Support / Admin tickets	auto on ticket create/reply
AI status badge	Most pages	GET /api/ai/status

Useful commands

npm run setup     # install deps, create venv, seed DB
npm start         # frontend + backend
npm run seed      # re-seed demo data
npm run backend   # API only
npm run frontend  # Vite only

What’s included

• Customer: product list/search, cart, promo codes, checkout, order history + receipts, smart list, support FAQ/chat/tickets
• Cashier: barcode/POS sale, tender, receipt with recommendations, recent POS orders
• Admin: inventory CRUD, promo codes, stats, ticket resolve, (intentionally unsafe) debug SQL

Promo demos: SAVE10, COFFEE5, POSONLY

Stack

• Frontend: React + Vite
• Backend: FastAPI + SQLAlchemy
• DB: SQLite (backend/retailos.db)
• LLM: OpenAI (gpt-4o-mini by default)

Intentional issues (workshop)

This app is built with deliberate flaws for code/security review practice, including:

• SQL injection in product + FAQ search
• Auth bypass via X-User-Id / X-Role headers
• Weak default JWT secret; long-lived tokens
• Plaintext customer passwords; /api/auth/users dumps credentials
• IDOR on orders, cart items, tickets
• Open CORS; debug headers echoing Authorization
• Unauthenticated /api/admin/debug/query (raw SQL)
• Path traversal on receipt file download
• Stored XSS via product description + dangerouslySetInnerHTML
• Self-register as admin; cashier treated as admin in some checks
• POS total_override without supervisor approval
• Negative stock / over-discount edge cases

Do not deploy as-is.

productionworkshop