Retail POS System

Part of the worlds-biggest-software-project initiative.

An AI-native, open-source cloud point-of-sale platform that gives independent and mid-market retailers enterprise-grade inventory sync, CRM, and offline resilience without enterprise-grade pricing.

A modern retail POS system that handles transaction processing, real-time multi-location inventory, customer relationship management, and omnichannel fulfilment. Built for independent retailers, specialty shops, and regional chains who need reliable offline operation and accurate cross-channel stock visibility but are priced out of platforms like Salesforce Commerce Cloud and locked in by proprietary hardware from vendors like Clover.

Why Retail POS System?

No cloud-native open-source option exists. The open-source POS landscape (Floreant, Chromis, uniCenta) is stuck on desktop Java with dated UIs and no cloud sync. Retailers who want open-source must accept 2010-era software.
Offline mode is still a pain point. Shopify POS limits offline transactions to short outages on its Pro tier. Square queues card swipes but little else. Lightspeed has acknowledged offline as a historical weak spot. Retailers in areas with unreliable connectivity have few good options.
Proprietary hardware lock-in inflates costs. Clover ties merchants to its own terminals; Square bundles its own readers. Switching POS provider often means replacing all store hardware.
AI-driven insights are gated behind enterprise pricing. Salesforce offers Einstein-powered recommendations and forecasting, but only at enterprise licence costs with SI partner implementation. SMB retailers get no access to demand forecasting, shrinkage detection, or personalised associate prompts.
Multi-location inventory sync remains fragile. Square's stock transfer features lag behind Lightspeed, while Shopify's multi-warehouse purchasing is weaker than vertical specialists. Phantom stock from sync lag causes real overselling problems.

Key Features

Transaction Processing & Payments

Barcode scanning, card and contactless payments, split tender, returns, exchanges, and store credit
Offline-first transaction queue with idempotent resync when connectivity returns
Integration with certified payment terminals (Stripe Terminal as default path) via public SDKs
Cash management with drawer counts, drops, payouts, and end-of-day reconciliation

Inventory & Supply Chain

Real-time stock levels by SKU and location with multi-store transfers and in-transit tracking
Purchase orders, supplier management, automated reorder thresholds
Matrix inventory support (size x colour) with bulk receiving
Ecommerce sync via documented connector spec (Shopify and WooCommerce as initial targets)

Customer & Loyalty

Customer directory with purchase history, notes, and store credit tracking
Built-in loyalty programme with points, tiers, expiry rules, and segmented promotions
Clienteling tools for associate-driven personalised selling
AI-powered next-best-action prompts: suggested upsells and loyalty redemptions at checkout

Reporting & Analytics

Daily Z-reports, margin analysis, sell-through rates, and ageing inventory views
Shrinkage and fraud anomaly detection from transaction-level patterns (voids, refunds, discount abuse)
Conversational reporting: natural-language queries like "How did socks sell vs last week in the Newtown store?"
Exportable data for accounting integration (Xero, QuickBooks)

Staff & Store Operations

Role-based access control, shift open/close, clock-in/out
Sales performance tracking per associate
AI-assisted onboarding and in-app coaching for new staff
Multi-store head-office vs store-level views for franchise and chain operations

AI-Native Advantage

Unlike incumbents that bolt AI onto legacy architectures or gate it behind enterprise tiers, this system is designed from the ground up with AI capabilities accessible to every retailer. Demand forecasting at the SKU/store level uses sales history, seasonality, and local signals to generate reorder suggestions -- functionality currently confined to Salesforce-tier pricing. Natural-language product search at the register lets associates find items conversationally ("the blue running shoes size 10") instead of navigating category trees. Transaction-pattern analysis surfaces shrinkage risks and anomalous void rates automatically, replacing manual end-of-day auditing.

Tech Stack & Deployment

Deployment: Cloud-native with self-hosted option; offline-first architecture stores full transaction capability locally and syncs without data loss on reconnection
Payments: Certified terminal integration via published public SDKs (Stripe Terminal, EMVCo-aligned interfaces); no re-implementation of payment cryptography; PCI DSS compliant by design
Hardware: Hardware-agnostic via abstraction layer supporting ESC/POS receipt printers, barcode scanners, cash drawers, and scales through OPOS, WebUSB, and Bluetooth
APIs: Public REST/GraphQL API with webhooks for orders, inventory, and refunds
Standards: IoT peripheral integration modelled on JavaPOS/OPOS standards; payment flows aligned with EMVCo specifications

Market Context

The global POS software market serves millions of retail locations, with cloud POS adoption accelerating through the mid-2020s. Incumbent pricing ranges from Square's transaction-fee model and Lightspeed's per-location subscriptions (mid-market) to Salesforce Commerce Cloud's enterprise licensing that typically requires a systems integrator. The primary buyers are independent retailers, specialty chains (apparel, sporting goods, home furnishings), and regional multi-store operators who need inventory accuracy and omnichannel capability but cannot justify enterprise POS costs.

Project Status

All ten phases of initial-research/development-plan.md are now implemented under target/: Phase 1 (Foundation — monorepo bootstrap, the Money/pricing/tax domain engine, and the cloud PostgreSQL + register SQLite schemas), Phase 2 (Sync Engine — Hybrid Logical Clock, CRDT merge primitives, the change log/merge dispatcher, and a transport-agnostic push/pull protocol), Phase 3 (Register Core — offline sale completion, catalogue lookup, manager-PIN-gated discounts, suspend/resume, and receipt generation), Phase 4 (Cloud API & Sync Gateway — the Fastify cloud API, JWT auth with per-request RLS scoping, rate limiting, an RFC 9457 error model, OpenAPI 3.1 generation, catalogue/inventory REST endpoints, the WebSocket/HTTP-batch sync gateway, and transactions/Z-report read APIs), Phase 5 (Payments & Hardware — a real Stripe Terminal PaymentProvider with server-side connection-token/PaymentIntent/refund minting, @pos/hardware driver interfaces for a receipt printer/cash drawer, barcode scanner, and scale, and a full returns/exchanges/store-credit flow with discount/tax-proportional refunds), Phase 6 (Customer, Loyalty & Digital Receipts — an offline-safe customer directory, a CRDT-based loyalty points engine, and consent-aware digital receipt delivery), Phase 7 (Inventory Operations — multi-store stock transfers with in-transit tracking, supplier/purchase-order management, and per-store reorder thresholds), Phase 8 (Public API, Webhooks & Ecommerce Connectors — a versioned OAuth 2.1 partner-app API, signed/retried outbound webhooks, and Shopify/WooCommerce connectors), Phase 9 (AI Co-Pilot & Analytics — an MCP tool surface, demand forecasting, conversational reporting, and shrinkage/anomaly detection), and Phase 10 (Hardening, Compliance & Deployment — PCI scope reduction, an authorization matrix, GDPR/CCPA-oriented privacy tooling, OpenTelemetry observability, and a real, verified self-hosted deployment path). See specs/001-foundation-domain-schemas/ through specs/010-hardening-compliance-deploy/ for each phase's spec, plan, and task breakdown.

Go-to-market collateral (a self-contained website, white papers, marketing/sales copy, user and technical documentation, and installation/integration guides) lives under /collateral, grounded entirely in the capabilities described above.

Phase 3 scope note: only the framework-free core (@pos/register-core, @pos/payments, @pos/hardware) is implemented and verified this pass, in Node/Vitest against real file-backed SQLite — a deliberate scope decision made with the project owner (see specs/003-register-core-offline-sale/plan.md and research.md), because this environment has no browser/Playwright runtime to build or verify a UI against honestly. Not yet built: the React 19 + Vite PWA shell (target/apps/register), an OPFS/wa-sqlite browser implementation of RegisterDb, and a Playwright E2E suite exercising context.setOffline. These remain explicit, tracked follow-up work, not a silently dropped requirement.

Phase 4 delivers the API only — no back-office UI consumes it yet, and the interactive OAuth 2.1 browser login flow is wired for production but not exercised end-to-end here, for the same no-browser-runtime reason as Phase 3 (see specs/004-cloud-api-sync-gateway/research.md).

Phase 5 proves the server-side payment lifecycle (connection-token minting, PaymentIntent create/capture/refund) against a real stripe-mock container — Stripe's own open-source test server — rather than a live Stripe account; the browser-only Stripe Terminal JS SDK's actual reader-discovery/card-collection flow, and real WebUSB/Bluetooth/Serial/ HID hardware, remain explicit tracked follow-up work for the same no-browser-runtime reason as Phase 3 (see specs/005-payments-hardware/research.md).

The scope notes above for Phases 3-5 (no-browser-runtime environment, honest tracked follow-up work) apply equally to the browser/UI-dependent and live-external-account-dependent surfaces of later phases — for example, Phase 9's AI features assume no live LLM account, and Phase 10's deployment validation covers the local self-hosted (compose) path with no live cloud/Kubernetes account, per each phase's own research.md. Contributions, feedback, and domain expertise are welcome.

Development

Application code lives entirely under target/ — the only directory the WBSP platform tracks and deploys (initial-research/ and this README stay outside it). It's a pnpm + Turborepo monorepo:

target/
├── packages/
│   ├── domain/         # @pos/domain — Money, currency, pricing/tax engine (framework-free)
│   ├── db-schema/      # @pos/db-schema — Drizzle schemas: cloud PostgreSQL + register SQLite
│   ├── sync/           # @pos/sync — HLC, CRDT merge primitives, change log, sync protocol (framework-free)
│   ├── register-core/  # @pos/register-core — RegisterDb, catalog lookup, basket, sale completion, receipt assembly (framework-free)
│   ├── payments/       # @pos/payments — PaymentProvider interface + MockProvider (framework-free)
│   ├── hardware/       # @pos/hardware — ESC/POS + HTML receipt rendering (framework-free)
│   └── cloud-core/     # @pos/cloud-core — auth, catalogue, inventory, sync gateway, transactions, Z-report (framework-free)
├── apps/
│   └── cloud-api/      # cloud-api — Fastify routes over @pos/cloud-core: auth/rate-limit/error-handler plugins, OpenAPI 3.1
└── docker-compose.yml

cd target
pnpm install

pnpm build       # turbo build across all packages
pnpm typecheck   # tsc --noEmit --strict across all packages
pnpm lint        # ESLint + Prettier
pnpm test        # Vitest — unit tests plus Testcontainers/better-sqlite3 integration tests (needs Docker running)
pnpm run verify  # all four, in order (NOTE: `pnpm ci` is a reserved pnpm command, not this script — always use `pnpm run verify`)

See specs/001-foundation-domain-schemas/quickstart.md for a walkthrough of what each package proves end-to-end.

Contributing

We welcome contributions from developers, domain experts, and potential users. See CONTRIBUTING.md for guidelines.

Important: All contributions must be your own original work or clearly attributed open-source material with a compatible licence. Copyright infringement and licence violations will not be tolerated and will result in immediate removal of the offending contribution. If you are unsure whether a piece of code, text, or other material is safe to contribute, open an issue and ask before submitting.

Licence

Licence to be determined. See discussion for context.

Note: The POS domain has specific IP considerations. Salesforce documents its POS offline mode as patented, so any offline architecture must be designed independently. Payment terminal SDKs from vendors like Verifone and Adyen may have NDA-bound terms restricting redistribution. Open-source predecessors that may inform design include Floreant POS (MPL 2.0) and Odoo POS Community (LGPLv3).

mccoy-POS