Point-of-sale platform for retail — rebuilt as version 2

Problem

The first version replaced notebooks in a small shop: sales, stock arrivals, customer debts and a weekly report. It worked, but the server-rendered monolith made every scan and page change slow, business rules were spread across views, and growing beyond one shop was not realistic.

Version 2 had to keep everything the shop relied on, remove the performance and structural limits, and become a product other shops could run.

Approach & architecture

• Documented the existing system first — business and functional requirements, data models, the API and a migration guide — then designed v2 from that spec instead of porting code.
• New architecture: a layered FastAPI backend (endpoints → services → CRUD → models) with permission-based access for admin, manager and seller roles, PostgreSQL, Redis caching and Celery for imports, reports and reminders.
• A lighter, faster interface: a React single-page app with no page reloads between scans, instant cart updates, timing-based barcode-scanner detection with per-scan dedupe and real-time updates over WebSocket.
• Money handled as a ledger: debts in an append-only, immutable ledger; shifts with X/Z reports and blind cash reconciliation; stocktakes with blind counting and variance reports; returns with per-line restock.
• Architecture ready for a two-tier setup — a server in the shop for offline-safe work and a cloud server receiving synced data — plus a Telegram bot with owner alerts and debt reminders.

Result

• v1 has been in use at the shop since 2024; v2 covers roughly 85–90% of its specification, with the core POS ready for single-store use.
• Four cart types, five payment methods, loyalty and cashback, analytics with 15+ metrics, a six-step onboarding wizard, and Russian and Uzbek interfaces.

What made it robust

• 280+ backend tests; CI runs linting, format checks, tests with coverage, migrations and a missing-migration check, and builds the Docker image.
• An independent review of v2 found 60+ issues — including a stock race condition and discount validation — which were fed into a remediation roadmap rather than left for users to discover.
• Idempotent operations, hardened auth with forced password change on first login, timeouts, backups and restore scripts.