UltimatePOS Operations Manual
Single-Site Ecommerce + POS

Run retail operations with one connected system.

UltimatePOS is built for real shops that need the website, the till, the stock file, supplier ordering, reporting, and content management to work together instead of fighting each other. This manual is written as an operational reference, not marketing copy, so every section focuses on what to do, what to configure, and what to check next.

Ecommerce storefront In-store POS Supplier ordering Customer loyalty Reporting and cash control
FrontendReact, TypeScript, Vite production bundle served from dist/.
BackendPHP API endpoints in api/ with installer-based first-run setup.
DatabaseMySQL or MariaDB with schema loaded from database/schema-base.sql.

Quick Start

This is the shortest practical route from fresh deployment to a working store. Use it for first-time setup, demo environments, or refresher training before a new launch.

Launch Checklist in 8 Moves

  1. Run the installer and create the first admin account.
  2. Complete General Settings and store details.
  3. Configure payments and delivery rules.
  4. Create categories, then products, then variants.
  5. Create at least one cashier for POS use.
  6. Run one web checkout test.
  7. Run one POS sale including start-of-day and end-of-day.
  8. Review reports and confirm everything reconciles.

What to test before going live

  • A product appears correctly in the storefront.
  • A barcode finds the correct item in POS.
  • Payment methods show correctly in the right channel.
  • Loyalty settings behave as expected.
  • Supplier ordering workflow can be completed.
  • Cash count and end-of-day reporting match the till.
  • Staff know which role guide they should follow.

Requirements

Before installing UltimatePOS, confirm the hosting environment is ready for both the PHP backend and the built frontend bundle.

Server Requirements

  • PHP 8.1 or newer.
  • MySQL 8.0+ or compatible MariaDB with JSON and utf8mb4 support.
  • Apache or Nginx with PHP-FPM.
  • HTTPS-enabled domain or subdomain.
  • Write permission to the project root during setup so the installer can create .env.

Deployment Package

  • dist/ and its compiled assets.
  • api/ including installer.php and all endpoints.
  • database/schema-base.sql.
  • Static assets such as robots.txt, manifest.json, and service-worker.js.
Important
Production must serve the built frontend from dist/index.html. Do not serve the source project index.html in a live environment.

Installation

Use the installer for fresh deployments. The installer validates database access, imports the base schema when needed, seeds initial settings, and creates the first admin account.

Step 1: Prepare the server

  1. Create an empty database for the application.
  2. Create a temporary installer or migration database user with schema privileges for that database.
  3. Create a separate runtime database user with data-only privileges for normal operation.
  4. Upload the project files to the intended web root or deployment directory.
  5. Copy the built frontend from dist/ so the compiled application files are publicly served.
  6. Confirm PHP can read project files and write a root-level .env file.
  7. If an old .env exists from a previous installation, remove it before first run.

Step 2: Run the installer

  1. Open the site URL in a browser. A fresh installation redirects to /setup.
  2. Enter the application URL, database host, port, database name, and the temporary installer user credentials.
  3. Enter the store identity details such as store name, phone, email, and address.
  4. Create the first administrator account with a strong password.
  5. Submit the installer and wait for schema import and initial seeding to complete.
  6. After setup, replace the database credentials in .env with the restricted runtime user.

Step 3: Validate the installation

  • Login works at /login.
  • Admin pages load without setup redirects.
  • A test product can be created and saved.
  • Store settings and payment settings can be opened.
  • POS loads for staff or admin users.
Note
You normally do not need to import SQL manually. The installer can load database/schema-base.sql automatically when the required tables do not yet exist.
Least Privilege
Use a short-lived installer or migration user only for setup and schema changes. The day-to-day application account should be limited to SELECT, INSERT, UPDATE, and DELETE on the application database. If an upgrade needs one-time schema backfills, temporarily switch to the installer account, apply the schema, then switch back.

First Login and Initial Setup Order

After installation, the fastest way to get the system operational is to configure the basics in a sensible order rather than jumping between modules.

  1. Login as the admin user created during installation.
  2. Open General Settings and enter store identity, contact details, tax rate, order prefix, loyalty settings, POS float, age verification, and printer settings.
  3. Open Payments and configure Viva Wallet, PayPal, and Viva POS terminal credentials if you plan to use them.
  4. Open Delivery and create active delivery or collection options.
  5. Create product categories before creating products.
  6. Add products, variants, prices, stock, images, and barcodes.
  7. Create POS staff accounts if non-admin staff will use the till.
  8. Run a test sale in POS and a test web checkout before going live.
Tip
Use one test product with a barcode and one regular webshop product during setup. That lets you validate both the public storefront and the POS flow with minimal setup time.

Role Guides

UltimatePOS is easier to train and operate when responsibilities are split clearly. These role guides explain which parts of the system each person should care about most and what their normal routine should look like.

Store Owner

Focus on commercial control: store setup, pricing rules, payment providers, supplier relationships, margins, reporting, and go-live quality.

  • Owns business settings and payment decisions.
  • Reviews reporting, margins, and supplier performance.
  • Approves live process changes.

Administrator

Focus on system accuracy: products, categories, customers, orders, deliveries, content, and troubleshooting configuration issues.

  • Maintains data quality.
  • Supports staff and resolves operational issues.
  • Controls what appears online and in POS.

Store Staff

Focus on execution: serving customers, handling POS sessions properly, following age-check policy, recording cash movements, and closing the till correctly.

  • Uses POS and customer display.
  • Runs start-of-day and end-of-day routines.
  • Escalates exceptions to admin or owner.

Store Owner Guide

This is the high-value workflow for the business owner or decision-maker. It focuses on setup, commercial controls, operational checks, and the points where mistakes cost money.

  1. Complete General Settings first so the store identity, tax rate, order numbering, loyalty rules, and POS float are correct.
  2. Configure payment providers before launching. Test both the website checkout and the in-store payment path.
  3. Review delivery rules and collection logic so the customer promise is accurate before orders start coming in.
  4. Approve product structure, pricing standards, and stock-management rules before the catalog grows.
  5. Set expectations for staff cash handling: opening float, cash adjustments, refunds, and end-of-day reconciliation.
  6. Review reports routinely, especially total sales, cash variance, supplier ordering performance, and best-selling products.
  7. Use supplier records and supplier orders to keep stock availability aligned with actual demand instead of relying on memory.
  8. Before making major live changes, test them with one product, one order, or one till session instead of changing everything at once.
Owner Priority
The biggest avoidable failures are usually bad payment configuration, poor stock discipline, or staff not recording cash adjustments. Treat those three as non-negotiable operating controls.

Administrator Guide

Administrators keep the system accurate. Your job is not just to enter data, but to keep the storefront, POS, and reporting aligned so staff can trust what they see.

  1. Review the dashboard, web orders, POS sales, and supplier activity at the start of each day.
  2. Maintain categories and products carefully. Create clean structures, use reliable SKUs, and keep barcodes and stock status current.
  3. Check customer requests and supplier orders so promised items are followed through and not forgotten.
  4. Keep media, storefront content, brands, and blog content up to date so the public site remains consistent with current stock and promotions.
  5. Use delivery, payment, and general settings pages to control behaviour centrally rather than solving issues ad hoc.
  6. Create and maintain cashier accounts instead of sharing the same login across the whole team.
  7. Use reports to investigate exceptions: missing stock, odd sales patterns, cash mismatch, or failed supplier follow-up.
  8. When troubleshooting, verify configuration first, then data, then browser cache, before assuming there is a code defect.
Admin Discipline
If a product is wrong in one place, it usually affects three places at once: storefront visibility, POS sale behaviour, and reporting quality. Fix root data, not just symptoms.

Store Staff Guide

Staff should use the system consistently rather than inventing workarounds. The POS is reliable when the till routine is followed properly every time.

  1. Login with your own cashier code at the start of the shift.
  2. Count the till accurately and enter denomination quantities, not value totals, when declaring the opening float.
  3. During sales, add the correct items, confirm variants carefully, and attach a customer when loyalty or customer history matters.
  4. Use discounts only within store policy and complete age verification correctly for restricted items.
  5. If cash is removed or added for any reason, record a cash adjustment immediately. Do not wait until later.
  6. If a customer pauses their purchase, park the sale rather than trying to remember it manually.
  7. If the internet connection drops, continue using POS normally and tell a supervisor if the offline queue warning remains for too long.
  8. At the end of the shift, complete the cash count carefully and do not close the till until the end-of-day process is finished.
Staff Rule
If the cash drawer changes, the system must know why. Recording adjustments is part of the sale workflow, not an optional extra.

Public Storefront

The storefront is the customer-facing website. It displays products, categories, offers, brand content, blog content, cart state, checkout, and account pages.

Homepage

The homepage can show featured categories, a hero section, product highlights, latest blog entries, and brand content depending on your storefront settings.

  1. Open the site homepage.
  2. Confirm hero text, imagery, and featured areas match your brand.
  3. Check featured categories and spotlight products display correctly.
  4. Verify brand logos, blog previews, and contact details are current.

Shop and Product Pages

Customers browse products by category, filters, search, or direct product links.

  1. Open /shop to browse the main catalog.
  2. Use categories and search to narrow the product list.
  3. Open a product page to choose a variant, review details, and add it to the cart.
  4. Check product images, descriptions, pricing, and stock messaging before publishing products live.

Checkout and Order Flow

The checkout uses a structured multi-step flow so billing, shipping, delivery, loyalty, and payment can be completed in sequence.

Customer checkout steps

  1. Add products to the cart and open the cart page.
  2. Review quantities, remove unwanted items, and continue to checkout.
  3. Login or continue as a guest depending on the store policy.
  4. Enter billing details and shipping details.
  5. Select a delivery method. Collection-only products restrict delivery choices automatically.
  6. Apply loyalty redemption if available.
  7. Select an enabled payment method such as Viva Wallet or PayPal.
  8. Submit the order and verify the thank-you page loads.
Important
Payment methods appear based on the payment settings page. If a provider is enabled but incomplete, customers may still see a warning or a disabled action until the provider credentials are corrected.

Customer Accounts

Customer accounts hold order history, addresses, profile details, and loyalty point information.

  1. Customer logs in at /login.
  2. Customer opens /account to review previous orders.
  3. Customer can open an order detail view to see items, totals, and addresses.
  4. Customer can update account details and address information.
  5. Loyalty balance is visible where applicable.

Admin Dashboard

The dashboard is the control centre for administrators. It gives quick visibility into business activity and provides the top-level path into each module.

What it is for

  • Quick sales overview.
  • Recent activity and operational visibility.
  • Fast navigation into the main admin modules.

Recommended daily use

  • Check new orders and unresolved operational issues first.
  • Use the sidebar to move directly into POS, inventory, reports, or customers.

Products and Categories

Products, variants, categories, stock status, pricing, and barcodes are managed here. Set up categories first, then add products into the correct structure.

Create product categories

  1. Open Admin → Inventory → Product Categories.
  2. Create top-level categories first.
  3. Add child categories if your catalog needs nested structure.
  4. Set category order to control storefront and admin listing order.
  5. Mark age-restricted categories where required.

Create a product

  1. Open Admin → Inventory → Products.
  2. Create a new product and enter the product name, brand, and descriptions.
  3. Select the correct category.
  4. Upload product images or leave blank if you plan to add them later.
  5. Add one or more variants with SKU, price, sale price, cost price, stock status, barcode, and optional variant image.
  6. Set product options if the product varies by size, flavour, colour, or similar attributes.
  7. Configure flags such as POS-only, collection-only, age-restricted, active, and manage stock.
  8. Save the product and verify it appears in the correct channel.
Note
Products without images can still be sold. In POS, missing or broken images fall back to a stable placeholder showing the product title instead of a broken image icon.

Customers and Customer Requests

Use the customer module to manage registered users, loyalty balances, and customer records. Use the customer request workflow to track special orders or manual requests.

Manage customers

  1. Open Admin → Customers → Customer List.
  2. Search by name, email, or contact details.
  3. Open a customer record to review account information and order history.
  4. Edit details when contact information changes.
  5. Use customer communications tools where configured.

Manage customer requests

  1. Open Admin → Customers → Customer Requests.
  2. Create a request when a customer asks for a special item, reserved item, or manual follow-up.
  3. Record names, phone numbers, item details, and status notes.
  4. Update the request as stock arrives or the item is collected.

Web Orders and POS Sales

UltimatePOS separates online orders and POS sales into dedicated views so you can manage them appropriately while still reporting on both.

Web Orders

  1. Open Admin → Sales → Web Orders.
  2. Search or filter orders.
  3. Open an order to review items, payments, customer details, and status.
  4. Edit status, update order details, or process refunds where needed.

POS Sales

  1. Open Admin → Sales → POS Sales.
  2. Review till transactions and payment breakdowns.
  3. Use this area to investigate a completed in-store transaction or reconcile issues.

Gift Vouchers

Gift vouchers are managed as their own records and can be sold or redeemed through the platform.

  1. Open Admin → Inventory → Gift Vouchers.
  2. Create voucher entries or review existing voucher balances.
  3. Track issued value, current balance, active status, and related order references.
  4. Redeem vouchers through web or POS flows where supported.

Offers and Promotions

Offers can target categories or products and are automatically applied in checkout and POS when the rules match.

  1. Open Admin → Inventory → Offers.
  2. Create the promotion and choose the offer type.
  3. Select target products or categories.
  4. Set buy/get quantities, promotional prices, percentages, or other matching rules.
  5. Set start and end dates if the promotion is time-limited.
  6. Save the offer and run a test purchase to confirm it applies as expected.

Media Gallery

The media module is the central image library for products, content pages, and brand assets.

  1. Open Admin → Inventory → Media Gallery.
  2. Upload images into the library.
  3. Use the picker in product or content editors to reuse uploaded assets.
  4. Keep image naming consistent so media remains easy to find later.

Suppliers and Supplier Orders

Supplier workflows let you keep vendor records, import supplier catalogs, link supplier items to your own stock, and create supplier purchase orders.

Create supplier records

  1. Open Admin → Suppliers → Supplier List.
  2. Create a supplier with contact name, email, phone, website, and address details.
  3. Add ordering notes if the supplier has account-specific instructions.
  4. Save the supplier and confirm it appears in the supplier list.

Import supplier catalog data

  1. Open the supplier detail area and locate the catalog or import tools.
  2. Upload the supplier CSV file.
  3. Review imported items and confirm the data looks correct.
  4. Link supplier catalog lines to existing product variants using supplier SKU or direct mapping.
  5. If required, create new products from supplier lines where no internal product exists yet.

Create supplier orders

  1. Open Admin → Suppliers → Supplier Orders.
  2. Create a new order and select the supplier.
  3. Add lines for the required products or supplier catalog items.
  4. Save the order and send it through your normal supplier communication channel.
  5. When stock arrives, receive the order and confirm inventory updates have been applied.
Tip
Linking supplier SKUs to your own product variants reduces future ordering friction and improves due-in visibility for stock on order.

Reports

Reporting covers sales, payment methods, cash reconciliation, transaction counts, hourly breakdowns, and product performance.

Operational reports

  • POS daily summaries.
  • Cash reconciliation.
  • Payment method breakdowns.
  • Cash adjustments and expected vs actual till cash.

Sales analysis

  • Total sales and transaction counts.
  • Top-selling products.
  • Hourly sales performance.
  • Combined visibility across web and POS activity.

Storefront Content, Brands, and Blog

Use the content modules to control how the public website looks and reads without changing code.

Storefront configuration

  1. Open Admin → Content → Storefront.
  2. Update hero text, hero image, and text alignment.
  3. Select spotlight content such as featured categories or a product of the month.
  4. Adjust header and footer presentation if those options are enabled in the page.
  5. Save and review the public homepage.

Brands and blog

  1. Open Admin → Content → Brands to manage brand visuals and public brand presentation.
  2. Open Admin → Content → Blog Posts to create or edit articles.
  3. Use Blog Categories to keep posts organised.
  4. Review the public blog pages after publishing content changes.

SEO and Sitemap

The SEO module helps control how the site is described to search engines and how public content is indexed.

  1. Open Admin → Settings → Sitemap / SEO.
  2. Review titles, descriptions, and indexable content where available.
  3. Confirm products, categories, and blog content use appropriate metadata.
  4. Verify the generated sitemap after major content changes.

Delivery Configuration

Delivery options define how customers can receive orders and what they are charged.

  1. Open Admin → Settings → Delivery.
  2. Create each delivery option with a name, description, price, and active state.
  3. Set free shipping thresholds where appropriate.
  4. Make sure collection is enabled if you offer in-store collection.
  5. Test checkout with and without collection-only products.

Payment Configuration

Payment settings control which payment methods are visible and which credentials are used for each provider.

Viva Wallet and PayPal

  1. Open Admin → Settings → Payments.
  2. Enable Viva Wallet if card processing through Viva is required.
  3. Enter Viva Merchant ID and API Key.
  4. Enable PayPal if PayPal checkout should be offered.
  5. Enter PayPal Client ID, Client Secret, and choose the environment.
  6. Save and run a test checkout before switching to live credentials.

Viva POS terminal

  1. Enable Viva Wallet POS Integration if an in-store terminal is used.
  2. Enter the POS Client ID, Client Secret, and Terminal ID.
  3. Save the settings and test a POS card transaction.
Important
Ecommerce Viva settings and Viva POS terminal settings are separate. Configure both if you use Viva online and in-store.

General Settings

General Settings contain the core operational defaults for the system. These settings affect public storefront behaviour, POS behaviour, and background integrations.

Store Info

  • Store name.
  • Contact phone and email.
  • VAT number and company registration number.
  • Company address.

Business Rules

  • Order prefix.
  • Tax rate.

Loyalty System

  • Points earned per £1 spent.
  • Points required to redeem £1.

Integrations

  • WhatsApp API token.
  • WhatsApp phone number ID.

POS Float

  • Default starting till float.
  • Used for start-of-day and end-of-day reconciliation.

Operational Controls

  • Camera age verification toggle.
  • Thermal printer support toggle.
  • Cache clearing and forced reload.

Recommended setup order for General Settings

  1. Complete Store Info first so legal and contact details are correct.
  2. Set the tax rate and order prefix under Business Rules.
  3. Configure Loyalty only if you intend to use it immediately.
  4. Set the POS Float before training staff on tills.
  5. Enable Age Verification if you sell restricted products in POS.
  6. Enable Thermal Printer Support only after the printer environment has been tested.

POS Staff

Cashiers are separate operational users for the till. They allow accountability and shift reporting without needing every staff member to use the main admin login.

  1. Open Admin → Settings → POS Staff.
  2. Create a cashier name and secure code.
  3. Save the cashier record.
  4. At the POS, login using the cashier prompt before starting a session.

Quick Stock

Quick Stock is a fast operational tool for editing stock levels without opening the full product editor.

  1. Open Admin → Quick Stock.
  2. Search for the product or scan the barcode.
  3. Adjust the stock level or stock status.
  4. Save the change and confirm the product reflects the updated availability.

POS Overview

The POS is designed for touchscreen sales, barcode scanning, loyalty redemption, restricted-product age checks, parked sales, offline queueing, and end-of-day reconciliation.

Core functions

  • Cashier login.
  • Barcode search and manual browsing.
  • Discounts and loyalty redemption.
  • Cash, manual card, and configured terminal payments.

Operational protections

  • Opening float declaration.
  • Cash adjustments.
  • Offline sales queue.
  • End-of-day count and reconciliation.

POS Start of Day

Starting the till correctly is important because later cash reconciliation depends on the opening float and cashier session data.

  1. Open /pos and login as the cashier.
  2. If the till is closed or has no active session, the float count modal opens.
  3. Count the cash drawer and enter the quantity of each denomination.
  4. Confirm the total against the expected float amount set in General Settings.
  5. Continue to open the POS session.
Note
The denomination form expects quantities, not money values. For example, enter how many £20 notes are present, not the total value of all £20 notes.

POS Selling Workflow

This is the standard selling procedure staff should follow for normal in-store transactions.

Sell an item

  1. Search for a product, scan a barcode, or browse categories.
  2. Tap the product tile to add it to the sale.
  3. If the product has multiple variants, select the required option.
  4. Adjust quantities using the sale controls.
  5. Add a customer if loyalty or customer history should be attached.
  6. Apply discounts if authorised.
  7. Tap finalise sale and choose the payment method.
  8. Print, email, or complete the receipt workflow as required.

Parked sales and offline queue

  1. Use the park sale feature if the customer steps away or wants to continue later.
  2. Name the parked sale clearly so it is easy to recall.
  3. If the internet connection drops, continue selling. Offline sales are queued locally.
  4. When the connection returns, the queue syncs automatically.

Restricted product sales

  1. If a sale contains age-restricted products and camera verification is enabled, the age verification workflow starts before payment.
  2. Complete or override the verification according to store policy.
  3. Only continue once the age-check result is acceptable.

POS End of Day

End-of-day closes the active till session, compares the actual counted cash to the expected total, and produces a summary suitable for review and reporting.

  1. Open the End of Day option in the POS sidebar.
  2. Allow the system to calculate expected till cash from opening float, cash sales, and cash adjustments.
  3. Count the drawer and enter the quantity of each denomination.
  4. Review any mismatch warnings carefully before confirming.
  5. Complete the report and store or print the summary as required by your business process.
Important
Do not skip cash adjustments during the day. If money is removed or added without recording it, end-of-day differences will be misleading.

Customer Display

The customer display mirrors the current sale on a second screen so the customer can see items, pricing, and payment progress.

  1. Open /customer-display on the second display device.
  2. Keep the display connected to the same browser environment or setup channel as the POS terminal.
  3. Start or update a sale in POS and confirm the mirrored display updates in real time.

Visual Guide

Visual examples for key workflows across administration, POS operations, and storefront conversion.

Admin Workspace Layout

Admin workspace screenshot
SidebarMain system sections live here, grouped by operational area.
Main PanelThis is where page-specific editing, reporting, and management happens.

POS Selling Screen

POS selling screen screenshot
SearchBarcode scans and product search should start here.
Sale AreaReview items, quantities, and payment before completion.

Start / End of Day Count

POS cash count screenshot
Expected TotalComes from settings or reconciliation logic.
Quantity EntryEnter note and coin counts, not the total cash value.

Storefront Product Journey

Storefront product journey screenshot
DiscoveryCustomers usually start from homepage, featured categories, or search.
ConversionGood pricing, clean images, and clear checkout rules reduce friction.

Staff Training Appendix

Use these scenario drills for induction and refresher training. They are designed to reduce common transaction mistakes and ensure consistent handling of exceptions.

Scenario 1: Refund Handling

  1. Locate the original order in Web Orders or POS Sales.
  2. Confirm the item, quantity, and payment method before taking action.
  3. Apply the refund in the correct channel, then verify order status and notes are updated.
  4. If cash is returned from the drawer, record the movement if store process requires a cash adjustment entry.
  5. Confirm customer communication is clear before closing the case.
Control Point
Never process a refund against the wrong transaction just because the customer name matches. Verify order ID and line items every time.

Scenario 2: Gift Voucher Sale and Redemption

  1. Issue the voucher from the Gift Vouchers workflow or POS process, recording amount and voucher number.
  2. Confirm the voucher appears with an active balance.
  3. During redemption, apply the voucher to the correct sale and verify remaining balance calculations.
  4. If voucher balance reaches zero, confirm final status is updated correctly.
  5. Escalate immediately if voucher number conflicts or unexpected balances are shown.
Best Practice
Read voucher numbers back to the customer before finalising redemption to reduce keying errors.

Scenario 3: Supplier Order Receiving

  1. Open the supplier order and confirm which lines have physically arrived.
  2. Receive only the delivered quantities, not the full order by default.
  3. Verify stock movement against expected SKUs and linked variants.
  4. Check that due-in quantities and expected dates update as intended.
  5. Report and note shortages or substitutions immediately so ordering history remains accurate.
Operational Note
Correct receiving is critical for stock reliability. Over-receiving by mistake causes hidden stock inflation and poor reordering decisions.

Maintenance and Routine Admin Tasks

Routine discipline keeps the platform reliable. The system is flexible, but reliability still depends on clean operational habits.

  • Review new web orders and supplier orders daily.
  • Check low-stock items and due-in items regularly.
  • Keep payment credentials, contact details, and delivery settings current.
  • Verify backups of the database and uploaded media are in place.
  • Clear cache only when necessary after confirming a stale asset problem.

Local Media Smoke Test

Use the local smoke test after PHP upgrades, upload-path changes, or release hardening work so you can verify the media pipeline without hand-running curl commands.

What the script verifies

  • Disposable admin creation and authenticated login.
  • PNG upload through the media conversion endpoint.
  • Media delete through the protected media API.
  • Audit log entries for media.upload and media.delete.
  • Category create and delete through the protected categories API when you run the companion category smoke test.
  • POS order creation, stock deduction, and orders.create_pos audit logging when you run the companion POS orders smoke test.
  • Customer authentication, web order creation with server-side pricing calculation, and pending order state before payment confirmation when you run the companion web orders smoke test.
  • Product CRUD with variant management and products.create/products.update/products.delete audit logging when you run the companion products smoke test.
  • Supplier order creation, receipt processing, and stock replenishment when you run the companion suppliers smoke test.
  • Admin-only settings updates with batch configuration handling and settings.update audit logging when you run the companion settings smoke test.

How to run it

  1. Confirm local database credentials in .env are correct.
  2. Use a PHP runtime with GD WebP support. Homebrew PHP is the default test runtime.
  3. Run npm run smoke:media:local from the project root.
  4. Run npm run smoke:categories:local when you want to verify protected category mutations and their audit trail.
  5. Run npm run smoke:orders:pos:local when you want to verify POS order creation, stock reduction, and order audit logging.
  6. Run npm run smoke:orders:web:local when you want to verify customer order creation, server-side pricing, and pending order status.
  7. Run npm run smoke:products:local when you want to verify product CRUD, variant handling, and mutation audit logging.
  8. Run npm run smoke:suppliers:local when you want to verify supplier order workflow and stock replenishment.
  9. Run npm run smoke:settings:local when you want to verify settings management and admin-only access control.
  10. Review the printed HTTP status codes and database state summaries.
Environment Note
If Homebrew PHP is used against a MySQL instance provided by XAMPP, the smoke script forces the DB host to 127.0.0.1 for that run so PHP uses TCP instead of a Unix socket path that may not exist.

Troubleshooting

Most operational issues are configuration, connectivity, or data consistency problems rather than application failures. Work through the checks below before escalating.

Setup loops back to /setup

  • Confirm the root-level .env file exists and is readable.
  • Confirm the installer finished successfully.
  • Confirm the required database tables were created.

Payment option missing

  • Check whether the provider is enabled in Payments.
  • Verify the relevant credentials are present.
  • Check whether the current route is web checkout or POS, as provider settings differ.

POS cash mismatch

  • Confirm the opening float was declared correctly.
  • Confirm all cash adjustments were logged.
  • Recount denominations by quantity rather than total money value per row.

Updated files do not appear

  • Use General Settings → Cache to clear service worker and local caches.
  • Confirm the deployed dist/ files are the new build, not an older copy.

Go-Live Checklist

Complete this checklist before directing real customers or store staff to the live system.

  • Admin login works and first admin credentials are stored securely.
  • General Settings are completed with correct contact and legal information.
  • Payments are configured and tested using the intended live providers.
  • Delivery methods and collection logic have been tested.
  • At least one full web order has been placed successfully.
  • At least one full POS sale has been completed successfully.
  • Supplier records and stock workflows are ready if purchasing is managed in-system.
  • The customer display works if a second screen is used.
  • Staff have been trained on start-of-day, end-of-day, and refunds.
  • Backups, SSL, and environment credentials are confirmed.

UltimatePOS Operations Manual.