Overview and Architecture

WPPosTill is a LAN-based point-of-sale stack for kitchen and retail operations. Three tiers work together:

┌─────────────────────┐     HTTP + WebSocket      ┌─────────────────────┐
│   Thin Client       │ ◄──────────────────────► │   Edge Server       │
│   (Electron/Android)│                           │   (Node.js + SQLite)│
└─────────────────────┘                           └──────────┬──────────┘
                                                             │
                                                    WooCommerce REST +
                                                    WordPress media API
                                                             │
                                                    ┌──────────▼──────────┐
                                                    │  Website / WooCommerce│
                                                    └─────────────────────┘

Design principle: Thin clients talk only to the Edge Server. WooCommerce credentials, printing, and SQLite data stay on the server. State mutations follow CQRS: commands via HTTP; local UI state updates from Socket.io broadcasts.

Platform Feature Matrix

Key Terms

Full glossary: CONTEXT.md

Operator Summary

What staff can do on the till, grouped by work area.

POS and Checkout

• Browse products on a category-tabbed grid with images, SKU, and price
• Refresh the catalog manually from the Edge Server
• Add simple products; adjust quantity with +/- controls
• Configure composite products (WOOCO bundles) via fulfillment picker
• Preview composite kit contents; edit composite lines in basket
• Attach a customer at checkout (create new or walk-in)
• Payment methods: CASH, CARD, OTH, Charity
• Apply preset discount percentages at checkout
• Submit checkout (permission-gated); basket clears on success
• Navigate to catalog, kitchen, EOD, settings (permission-gated)
• Switch user or log out; basket preserved across handoffs
• Real-time product image updates when catalog images finish downloading
• See a “No internet” banner when the Edge Server loses WAN connectivity (web orders and website sync may lag; local till sales continue)
• See “Internet restored” briefly when WAN recovers

Catalog Management

• Search and filter products by name or SKU; category accordion filter
• Create products via two-step wizard (simple or composite)
• Edit name, SKU, price, categories, visibility, advanced meta
• Mark products local-only; control website visibility
• Upload product photos; convert simple to composite
• Configure composite sections, groups, and pricing
• Meal-prep nutrition fields for Meal Preps category
• Print product labels with quantity selection
• Draft guards against losing unsaved changes
• Read-only mode when user lacks edit permission

Kitchen Board

• View active Till and Web orders on one board
• Source badges, line items, composite child lines
• Dismiss Till orders (Web orders dismiss via Woo status on server)
• Real-time order updates without manual refresh

End of Day

• Select business date; view sales summary report
• Review orders by source; view stored EOD records with drift warnings
• Enter declared totals: cash, Just Eat, Deliveroo, other, direct payments
• Close the day (settles orders, persists record, optional receipt print)
• Reprint EOD close receipt

Settings

• Printers — label and receipt host/port; test prints
• Store API keys — Woo credentials; test; sync status
• Website login — WordPress app password; test
• Users — CRUD till users; PIN and permissions
• Permission profiles — reusable presets; apply to users
• Developer — client functions console; rerun setup wizard

Printing

• Product labels (Brother); order receipts (ESC/POS); EOD close receipts
• Optional auto receipt on new orders (server config)
• Test prints from Settings; async jobs with status polling

Security and Sessions

• Boot PIN gate (four-digit); till session with 12-hour default TTL
• Switch user (basket preserved); logout with confirmation
• Lockout after 5 failed PIN attempts (15 minutes)
• Permission gating on routes, buttons, and server APIs
• Bootstrap mode when zero till users; empty permissions block sign-in

First-Run Setup

• Connect to Edge Server; configure Woo and website credentials
• Configure printers; create first till user (Manager profile)
• Writes setup.json on the client

Platform Features

Shared Thin Client

All operator features run on both Electron and Android via the same Vue app.

Electron (Windows Kiosk)

Android (Capacitor)

Edge Server

Infrastructure

• Express + Socket.io; SQLite WAL; health check (GET /api/health with LAN liveness + internet WAN snapshot); CLI setup wizard
• WAN reachability monitor — ICMP ping to google.com every 5 min while up, 20 s while down; logs [Internet] transitions; does not pause sync workers
• Outbound WAN failure detection — transport errors on public fetch URLs and WooCommerce HTTP 5xx mark WAN down (401/429 do not; LAN hosts ignored)
• Background daemons: sync, images, print queue, Woo poller, WAN monitor, bootstrap

Authentication and Admin

• Till PIN sessions; capability middleware; bootstrap mode bypass
• Admin settings; till user and permission profile CRUD

Catalog, Customers, Orders

• Full product CRUD; local-only; image upload and LAN serve
• Customer CRUD with async Woo push; repeat_orders metric
• Till checkout; Woo ingest; kitchen API; dual Till/Web identity

End of Day

• Live report; stored records; close day; reprint receipt

Printing

• Async job queue; Brother labels; ESC/POS receipts; EOD receipts
• Printer registry; category template resolver; test endpoints

Sync and Composites

• Bootstrap; re-bootstrap; push/pull reconcile; offline queue
• WOOCO composite definition, kit browser, materialized tables

Realtime

• Socket.io broadcasts: order_upserted, product_upserted, catalog_image_progress, catalog_images_ready, internet_status
• New Socket.io connections receive current WAN snapshot on connect

Key path: server/src/

Integrations (Edge Server Only)

Known Gaps and Placeholders

Appendix A — Vue Routes and Guards

Source: client/src/router.ts

Appendix B — API Endpoint Index

Base URL: http://<edge-server-ip>:3005

Health

Products and Catalog

Orders and Kitchen

End of Day

Customers

Sync

Printing

Authentication

Admin Settings and Users

Composites Admin, Images, Debug

Appendix C — Socket.io Events

internet_status payload: { ok: boolean, message?: string }. When ok: false, message is typically No internet — web orders and sync may be delayed.

Server source: server/src/services/RealtimeBroadcaster.ts
Client source: client/src/services/SocketService.ts, client/src/composables/useInternetStatus.ts

Appendix D — Permission Capability Matrix

Starter Profiles

Appendix E — Key File Index

Client — Stores and Services

• Cart/checkout: stores/useCartStore.ts, order/orderEdgeClient.ts
• Orders/kitchen: stores/useOrderStore.ts
• Catalog: stores/useCatalogStore.ts, services/catalogEdgeClient.ts
• EOD: services/eodEdgeClient.ts, services/eodCloseLogic.ts
• Print: services/printService.ts, services/printEdgeClient.ts
• Session: services/tillSessionClient.ts, services/tillCapabilities.ts
• WAN status: composables/useInternetStatus.ts, composables/internetStatusLogic.ts, layouts/TillAppShell.vue
• Realtime: services/SocketService.ts

Server — Routes and Services

• Entry: server/src/index.ts, routes/healthRoutes.ts
• WAN monitor: services/internetReachabilityMonitor.ts, services/internetReachabilityProbe.ts, services/outboundInternetFetchGuard.ts
• Auth: routes/tillAuthRoutes.ts
• Catalog: routes/catalogRoutes.ts, db/productRepository.ts
• Orders: routes/orderLanRoutes.ts, services/OrderIngestionService.ts
• EOD: routes/eodRoutes.ts, services/eodCloseService.ts
• Print: routes/printRoutes.ts, print/PrintJobQueue.ts
• Sync: services/OfflineSyncEngine.ts, CatalogBootstrapService.ts

Shared

• shared/wooco/ — Composite logic
• shared/permissions/ — RBAC
• shared/receipt/ — Receipt layout

Appendix F — Related Documentation

• CONTEXT.md — Domain glossary
• docs/ServerAPIRouter.md — API reference
• server/README.md — Edge ops
• docs/adr/ — Architecture decisions
• docs/prd/ — Product requirements
• client/ELECTRON_DEV.md — Electron dev