1. Overview & System Architecture

Hospitality POS is a modular, extensible WordPress-based POS system designed for hospitality environments. It integrates deeply with WooCommerce while supporting advanced front-of-house workflows:

• Lightning-fast POS UI (Tailwind, jQuery)
• Table Management (status, timers, assignment)
• Loyalty customer search + points
• Staff PIN login + terminal sessions
• Multi-terminal live sync
• HTML Receipts + ESC/POS printer integration
• Menu Builder (categories, colours)
• WooCommerce-backed stock & products

[WordPress] → Loader
               │
               ├── Frontend UI (POS)
               ├── Admin Settings
               └── REST API
                     │
                     ├── Product Source (Woo)
                     ├── POS Engine
                     ├── Loyalty Engine
                     ├── Staff Sessions
                     ├── Table Manager
                     ├── Receipts
                     ├── Payments
                     └── Analytics
    

2. Product Integration Layer

The POS loads all products via a unified adapter interface. WooCommerce is automatically detected.

interface HPOS_Product_Source_Interface {
    public function get_products();
    public function get_product( $id );
    public function search_products( $query );
}
    

The output is normalised into POS-ready data for fast rendering.

3. Folder Structure

pos-plugin/
│
├── includes/
│   ├── class-api.php
│   ├── class-pos-engine.php
│   ├── class-product-source.php
│   ├── class-loyalty.php
│   ├── class-tables.php
│   ├── class-auth.php
│   ├── class-receipts.php
│   ├── class-terminals.php
│   ├── class-analytics.php
│   └── ...
│
├── templates/
│   ├── pos-screen.php
│   ├── pos-table-actions.php
│   └── receipt-template.php
│
└── assets/
    ├── js/pos.js
    ├── css/pos.css
    └── images/
    

4. Core Classes

5. Table Management System

Tables are fully integrated into the POS order flow. Each table stores:

• Status: free, seated, dining, bill, cleaning
• Area (optional)
• Elapsed minutes since seating
• Assigned running order

Selecting a table in the POS sets:

payload.table_id
payload.table_label
    

POS automatically applies colour-coding in the modal.

6. Loyalty System

• Live customer search (phone/email/name)
• Add points on order completion
• Redeem points (discount)
• Transaction history stored

POS captures:

payload.loyalty_customer_id
    

7. Staff PIN Login & Sessions

• PIN validation
• Clock-in & session creation
• Terminal ID binding
• Session recovery on reload

8. Receipt Engine

Two output formats:

• HTML receipt (browser printing)
• ESC/POS raw commands (thermal printers)

Receipt endpoint:

GET /wp-json/pos/v1/receipt/html?order_id=123
    

9. Front-end POS JS Architecture (NEW)

The entire POS is powered by assets/js/pos.js — a unified, modular script handling:

• Product loading
• Category filtering
• Cart management
• Table modal logic
• Loyalty modal & search
• Staff login & session restore
• Order POST → /order
• Receipt printing

See full file in /assets/js/pos.js.

10. REST API

Products:
GET  /pos/v1/products
GET  /pos/v1/products/search

Orders:
POST /pos/v1/order

Tables:
GET  /pos/v1/tables
POST /pos/v1/tables/update

Receipts:
GET  /pos/v1/receipt/html

Loyalty:
GET  /pos/v1/loyalty/search
POST /pos/v1/loyalty/add
POST /pos/v1/loyalty/redeem

Staff:
POST /pos/v1/staff/login-pin
POST /pos/v1/staff/logout
GET  /pos/v1/staff/current
    

11. Analytics Engine

The analytics subsystem now supports:

• Daily sales
• Summary
• Staff grouped performance
• Top products
• Terminal performance

12. Database Schema

Key tables now include:

• wp_pos_orders (+ table_id, table_label)
• wp_pos_order_items
• wp_pos_tables (status, area, elapsed)
• wp_pos_sessions (staff)
• wp_pos_loyalty
• wp_pos_terminals

13. Coding Standards & Security

• Nonce check recommended for future hardening
• Validate product IDs against WooCommerce
• Restrict analytics endpoints

14. Testing & QA

• Staff login tests
• Table status logic
• Loyalty points calculations
• Thermal printer test prints
• WooCommerce stock sync

15. Extending the Plugin

You can extend via:

• New product adapters
• Custom loyalty behaviours
• Payment gateways
• New table states