A Word to the Reader

Running a snooker centre is an act of choreography — tables turning, members arriving, kitchens firing, scoreboards flickering, ledgers closing. This guide is the script.

The Snooker King platform was designed not to replace the rhythm of a busy room, but to amplify it. Every screen, every button, every report exists because a real operator, on a real night shift, asked for it. This guide walks you through the system as it actually behaves — from a member tapping a QR code at the door, to the moment the manager closes the till and reviews the day.

Read it linearly the first time. Keep it on a shelf for the second. The chapters move from the broadest concepts (architecture, roles, daily flow) toward the deepest mechanics (settings, audit logs, troubleshooting). Cross-references and a glossary close the volume.

— The Snooker King Team
June 2026

Table of Contents

"A well-run room is the sum of small, well-kept records."

Architecture & Tenancy

Snooker King is a multi-tenant cloud platform for cue-sport venues. One installation can serve a single hall, a regional chain, or a national franchise — without code changes, from the same browser.

The platform is composed of four cooperating surfaces. Understanding them in this order will help every later chapter make sense.

Tenancy Hierarchy

Every record in the system belongs to a four-level hierarchy. Permissions, reports, and even the colour of the navigation bar depend on which level you are signed into.

Browsers, Devices & Connectivity

Snooker King is a browser-first application. There is no installer, no desktop client, and no required plugins.

A Day in the Life

Here is the daily rhythm of a typical centre — every event in this list is a feature you will meet later in the guide.

Roles & Access Control

Before you can do anything, the system must know who you are and which centre you speak for. Every screen, button, and report obeys your role.

The Six Roles

Snooker King ships with six functional roles, mapped onto five physical user types in the database. manager and operator share the employee table and are differentiated by the employee's role field; the other four are stored in their own tables (admins, clients, organizations, members). Permissions follow the role at every request — pages, modals, and even individual rows.

Signing In

Page Access Matrix

The console exposes pages by role. Unlisted modules are hidden from the navigation entirely.

Context Switching & Sign-Out

Multi-centre managers can change scope from the header context switcher. Switching is audited (a row in System Logs ties subsequent actions to the new scope). Manual sign-out clears local storage immediately and revokes the active session.

The Operations Console

The Operations Console is the cockpit. Every other feature in the platform is launched from here, and every report ends here. We treat it as the single most-used surface in the entire product.

Anatomy of the Console

Sidebar Pages

Three sidebar links are always visible to anyone signed in (Operations, Deposits, Revenues); the rest light up by role. Order is fixed so muscle memory carries between centres.

1. Dashboard — announcements feed and management.
2. Admins · Clients · Employees · Organizations · Centers — tenancy and identity surfaces (top-down).
3. Campaigns · Memberships — promotions, tier definitions, discount rules.
4. Operations — the live table grid; most of a shift is spent here. Always visible.
5. Deposits — wallet top-ups, ledger, refund / cash-out. Always visible.
6. Revenues — financial reports, shift reconciliation, thermal slip, exports. Always visible.

Members and POS aren't separate sidebar tabs — the M shortcut (or the table action panel) opens member search; POS opens from the table tab itself, since every order is bound to a table or member.

Header Bar

• Centre selector (multi-centre roles only) — switches scope.
• Notifications — alerts in priority order; click to acknowledge.
• Avatar menu — profile, theme, sign out.
• Bug-report icon — file an issue without leaving the page.

The Dashboard Page

The Dashboard is a focused communication surface — its job is to surface the announcements that matter to the signed-in user, not to act as a number-board. Live operational numbers live on the Operations grid (the next page), and financial numbers live in Revenues.

• Announcements feed — a card listing every announcement targeted to the current user (by role, organization, centre). The card carries an unread count and can be collapsed.
• Announcements management — for roles that can author announcements, a searchable table of every announcement with title, organization, visibility, publish window, and status, plus a Create New Announcement button.

If a manager wants live shift numbers, the Operations grid shows occupancy and pending-payment counts in real time, and the Revenues module shows tender breakdown and totals.

Search & Filtering

Each module has its own search field and filter chips. The Operations grid lets you filter by table type, status, zone, and assignment. The Members directory lets you search by name, phone, RFID card ID, or member number. Revenues lets you filter by date range, payment method, employee, and centre.

Modals — the Workhorse

Most actions open in a modal so the underlying live grid keeps updating. The most common modals you will meet:

• Settings modal — branding, devices, themes, integrations.
• Member modal — assign a member to a table, view history, top up wallet.
• POS / F&B modal — order entry, modifier picker, kitchen send.
• Invoice modal — payment entry, split-bill, refund, reprint.
• Live monitor editor — edit per-centre theme, layout, footer.

Notifications & Alerts

The header bell shows live alerts: low stock, new bug report, membership renewal due, large discount applied, end-of-shift cash variance. Click to acknowledge; alerts persist until handled.

Clients, Organizations & Centres

Centres are the heartbeat of the system. Almost every other entity — tables, members, invoices, employees, F&B items — belongs to exactly one centre. Get the centre right and the rest follows.

Creating an Organization

Creating a Centre

Each centre carries its own opening hours, table inventory, F&B menu, price lists, and employee roster. The Centre wizard does the heavy lifting in a guided flow:

The Centre Settings Tree

Every centre exposes a deep tree of settings. The full path from least-changed to most-changed:

Centre
├── Identity ........... name, address, contact, time zone
├── Branding ........... logo, colours, social links, monitor footer
├── Hours .............. weekly schedule, holidays, last call
├── Tariffs ............ table tiers, peak/off-peak, member discounts
├── F&B Menu ........... categories, items, modifiers, combos
├── Inventory .......... stock items, low-stock alert, movements log
├── Employees .......... roles, permissions, status
├── Devices ............ printers, monitors, RFID readers, lighting relays
├── Integrations ....... payment, e-invoice (LHDN), notifications
└── Compliance ......... tax, e-invoicing, age policy

Tariffs & Peak Hours

Tariffs are the most-edited setting after F&B. The model is intentionally simple — three layers, applied in order:

1. Base rate per table type (Snooker, Pool, English).
2. Time band modifier — peak (often 18:00–23:00) adds a percentage; happy hour subtracts.
3. Member discount — applied last, after time band.

Rates can be overridden per table for special tables (championship, VIP). The effective rate column on the operations grid always shows the final number a customer will pay.

Cloning a Centre

For a multi-centre rollout the most useful shortcut is the clone action: configure the flagship completely, then clone-create new centres so almost everything carries over. Address and table count typically need to differ; everything else can be inherited at clone time and adjusted in place per centre afterward.

Other multi-centre operations — bulk menu sync, organization-wide tariff broadcast — are handled centre-by-centre today; do them with care during quiet hours and verify with the proforma screen on a representative invoice before publishing.

Tables, Sessions & Lighting

Tables are why the customer is here. This chapter covers the live operations grid, the session lifecycle, and the lighting integration that ties software to the physical room.

Operational States

Five canonical states live on center_tables.current_status: available, occupied, checkedout, inactive, and maintenance. The Operations grid renders more than five badges by layering two derived signals on top — pending (session finished, invoice not yet settled) and rental-active / rental-idle for tables in a rental window — plus a static fnb label for F&B-only tables. The stored column is the audit truth; the rendered badge is the operator's at-a-glance.

Starting & Stopping a Session

Lighting Integration

Snooker King controls table lighting through Vyrox's MQTT relay gateway. The platform sends commands over an HTTPS bridge (vyrox.vip/mqtt_light/*) which fans them out to the ESP-based relays mounted above each table. The architecture is command-and-query, not push-heartbeat — operators always see real-time state because the console asks the gateway every few seconds, not because the relay phones home.

• Relay states — the gateway reports each channel as on or off. There is no stored "error" state; if the gateway is unreachable the operator sees a neutral placeholder badge while the platform retries.
• Failure logging — when a command (turn-on, turn-off) fails or times out, a light_control_failure row is written to System Logs with the table, channel, and HTTP error so it can be triaged after shift.
• Concurrency-safe polling — the front-end debounces and serialises status fetches so a busy room doesn't hammer the gateway with parallel queries.
• Test mode — managers can pulse a relay from the device settings panel to confirm wiring without disturbing live tables.
• Cancel-stuck-light — a one-shot admin tool clears a relay that got jammed in an old command from a previous shift.

Maintenance & Out of Service

To take a table out of service, open the table action panel and switch its status to Maintenance (or Inactive if the table is being decommissioned for a longer period). The cell is hidden from the live operations grid and the public Live TV Monitor stops advertising it. Maintenance is a soft signal, not a hard lock — bookings already in the future on that table are not auto-cancelled, so a manager should review the day's bookings after marking a table down for repair.

Sessions & Multi-Member Play

A session can have one host member plus additional players. Each player is recorded against the session for leaderboard, history, and split-bill purposes. Players can be added or removed mid-session; the duration is shared but the bill can be split per person at checkout (Chapter XVI).

Countdown Packages

Some venues sell time as packages — for example "60 minutes for a flat fee". The countdown module attaches a remaining-time clock to a session; when it reaches zero, an upsell prompt appears at the operator station. Packages are configured per centre with their own pricing.

The Live TV Monitor

Every centre has at least one wall-mounted display showing all tables, their state, prices, and rotating promotions. The Monitor is browser-based, fullscreen, and updates without refresh.

Theme Presets

The monitor ships with four ready-made looks. Pick one per centre; pixel-level overrides are available where needed.

Layout Styles

• Grid — even cells, the default for medium and large rooms.
• List — single column of wide rows; works on narrow / portrait displays.
• Spotlight — one or two highlighted tables at the top, the rest tiled below.

Density is selectable from compact, comfortable, or spacious.

Sections of the Monitor

• Header — centre logo, current time (12h or 24h), optional weather, today's promotion. Height switchable between compact, standard, and tall.
• Summary stats — pick from active count, overtime count, paid-in-full count. Total revenue is intentionally hidden from the public board to protect commercial information.
• Tables grid — every table with type, state, current price/hr, and elapsed time for active sessions.
• Rotation panel — full-bleed promotional photos and offers; transitions every few seconds.
• Footer marquee — global brand strip, marquee speed and font size both configurable.

Quick-Add & Reset

When you create a new centre, the wizard seeds the Monitor config in one shot from a canonical template — never start from a blank screen. Reset to default restores the same template at any time. The footer brand strip is loaded from a global setting, so re-branding the company updates every venue's monitor at once.

Hardware Recommendations

Live Cast / Public Broadcast

Big matches deserve an audience. Live Cast turns any battle on any table into a public, token-gated URL that anyone with the link can watch — frame scores, fouls, breaks, and a customisable overlay, all in real time.

How It Works

1. The operator (or the host member from the portal) starts a battle on a table.
2. A unique 16-character alphanumeric token is generated and stored on the battle row. Routes /live/?token=X, /live.php?token=X, and /debug/cast.php?token=X all resolve to the same Cast page; the token alone is the credential.
3. The server validates the token against battles.broadcast_token with the additional gate broadcast_enabled = 1. A revoked or never-enabled match returns a friendly empty-state page rather than data.
4. The Cast page shows player names, current frame, frame scores, last-pot information, and a brand overlay — no other tables, no payment data.
5. Visibility is a toggle, not a timer: when the host disables the broadcast, the same token immediately stops resolving. There is no auto-expiry — to keep a result shareable after the match, leave the broadcast enabled; to lock it down, flip the switch off.

Broadcast Layouts

Three presentation styles ship with the platform:

Use Cases

• Final tables — the lounge can stream the final on a side TV without operator effort.
• Coaching review — a coach watches an academy match remotely.
• Social sharing — members share the link to their friends' phones for pocket viewing.

Members & Profiles

A member is more than a phone number. The member record is the spine of loyalty, billing, social play, and analytics. Every interaction in the room echoes back to it.

Membership Tiers

Tiers are not a hard-coded ladder — every organization defines its own set in the Memberships module, and tier names ("Silver", "Gold", "Champion", "Premier", whatever fits the brand) are free-text. Each memberships row carries a consistent shape that pricing and rewards bind against:

Discounts are configured on a separate per-tier table (the membership-discount module): a tier can carry a list of discount rules — by table type, by F&B category, by day-band — that apply automatically when the member is identified at session start or invoice creation.

The Member QR & RFID Card

Every member has a unique QR code in the portal and (optionally) a physical RFID card linked to the same account. Scanning either at the kiosk or on the operator app:

• Identifies the member instantly.
• Locks the tier discount on the next session.
• Records the visit (used for retention reports).
• Auto-fills any waiting F&B order or pre-booking.

Face Recognition (optional check-in)

Where the venue has the appropriate consent and hardware, members can be identified at the door by face. The recognition pipeline is browser-side via WebRTC: a video element + canvas overlay, three sequential gates — detect (a face is present and large enough), liveness (anti-spoof signal: blink / micro-movement), and match (cosine similarity against the centre's enrolled face embeddings). Voice prompts are localised (English / 中文 / Bahasa Malaysia); on a confirmed match the operator station auto-fills the member into the next-table flow.

Sensitivity is tunable per centre on the Face Settings panel: face_match_threshold (0.05–0.75), face_duplicate_threshold, face_detection_confidence, face_min_face_size_pct, face_liveness_check, face_antispoof_check, and face_scan_timeout_sec. Embeddings live in the member_faces table and are scoped per organization. Recognition is opt-in and fully disable-able — flip face_mode to off and the door modal disappears entirely.

The Member Portal

The Member Portal is a full mobile-first experience. It is the surface most customers touch most often, and it is engineered for one-handed, mid-frame use.

The Nine Surfaces

The portal is intentionally swipe-driven. Across the bottom navigation, modal sheets, and inner pages, members reach nine main surfaces:

Becoming a Member

A guest is elevated to a free member in three taps. The flow is intentionally idempotent — running it twice is safe.

Wallet, Top-Ups & Stored Credit

The wallet is the spine of the loyalty programme. Balances tracked on every account include:

• Cash credit — top-up via card or e-wallet; spendable across tables and F&B.
• Comp credit — issued by management for service recovery; usually expires after a configurable window.
• Stamps & points — earned per spend, redeemable per the loyalty rules (Chapter XIX).

Showcards & Recognition

Showcards are short animated full-screen recognitions — a member's first century break, a tier upgrade, a tournament win. They appear on the portal and on the Live TV Monitor for everyone in the room to see. Operators can trigger them manually from the member's profile.

Sound & Haptics

The portal has a sound system that plays subtle confirmation, success, and error tones, plus open/close cues for full-screen sheets. Members can mute the entire sound bus from settings.

Battles & Tournaments

A battle is a managed match between two members on a real table — best-of-frames, automatic scoring assist, and a rating that follows the player across centres. Tournaments are scheduled multi-battle ladders that the platform runs end-to-end.

Game Format Families

Snooker King's battle engine ships with a broad catalogue of cue-sport rule files, grouped into seven format families. Each family carries its own scoring rules and frame structure; many include short-form variants. The full per-format catalogue lives in Appendix B.

• Snooker (plus shorter-form variants)
• Eight-Ball — English (plus variant rule sets)
• Nine-Ball (plus variant rule sets)
• Carom Billiards
• English Billiards
• Russian Pyramid
• Straight Pool

Anatomy of a Battle

Every battle moves through one of six recorded states on the battles.status column:

1. pending_accept — the host has issued an invite (to a specific member or as an open challenge); waiting on the opponent to accept. Format and best-of frames are committed here.
2. pending_confirm — opponent has accepted; the system is waiting on the host to confirm and the table to be allocated.
3. in_progress — frames are live; the operator (or member, in self-score mode) enters frame results as they finish.
4. completed — final frame entered or auto-finalised by the time-out cron. The system stamps the winner, posts to the leaderboard, and updates Glicko-2 ratings.
5. cancelled — abandoned before a winner was declared. The pending invitee row is also marked cancelled so it doesn't linger in someone's invites list.
6. disputed — either party has raised an integrity dispute mid- or post-match. The match is frozen until a manager resolves it from the operator console.

Glicko-2 Rating

Battles update each player's Glicko-2 rating — a successor to Elo that also tracks rating volatility and uncertainty. New players start with a high uncertainty that narrows as they play more matches; the result is fairer match-making and a more stable leaderboard.

• Rating — your skill estimate.
• Deviation — how confident the system is in that rating.
• Volatility — how stable your recent results have been.
• Win rate — a separate quality metric, surfaced alongside rating.

Tournament Lifecycle

Tournaments move through four states:

1. Draft — being configured, not yet visible to members.
2. Registration — open for sign-ups; entry fee captured if applicable.
3. In Progress — bracket is live; matches are released round by round.
4. Completed / Cancelled — final state with archived results.

Hosting a Tournament

Frame-by-Frame Scoring

Operators record frames using a simple panel: enter break / clearance / fouls per player. The system handles tie-break rules and updates the leaderboard in real time. Frame results stream to any active Cast URL (Chapter VII) instantly.

Leaderboards

Every centre has a leaderboard panel that filters by game format and by time window. The score blends Glicko-2 rating with frames won and opponent strength.

Coaching & Notes

Each leaderboard row exposes a Coach Notes field, visible only to the member and their authorised coach. Use it to track drills, weakness areas, and plan for the next tournament.

Stakes & Compliance

Where house rules permit, battles can carry a stake. The organization-level setting controls whether stakes are off, credit-only, or cash. In jurisdictions where wagering is restricted, leave it on off or credit-only; the system will refuse cash stakes and show a notice.

Battle Layouts on the Big Screen

When the operator pushes a battle to the public Cast URL or to the Live TV Monitor, the same three layouts apply (Chapter VII). Choose Crucible Classic for finals, Premier League Theatre for sponsor-heavy events, and Pressroom Minimal for embedded streams or coaching review.

Bookings & Reservations

Reservations live alongside the live grid. Customers book through the member portal or by calling staff who use the Bookings panel in the operations console.

Booking Flow

1. Select date, start time, and duration; pick a specific table from the available list.
2. Capture customer name, mobile, and any notes; confirmation lands in the operations grid as a future card on that table.
3. The booking is written with status='confirmed'. The platform does not currently capture a monetary deposit at booking time — front-desk staff handle deposits as cash receipts against the member wallet if required.
4. When the party arrives, the operator opens the booking and taps Check In; the booking moves to checked_in and is linked to the live game session.
5. When the table closes, the booking is automatically marked completed by the same handler that closes the table.

No-Shows & Cancellations

A booking can be cancelled by the member from the portal or by an operator from the operations grid. Bookings that are still confirmed after their end-time pass are auto-flipped to no_show by a maintenance pass — the platform doesn't wait for someone to remember to do it manually. Cancellation policies — free-cancellation windows, deposit-forfeit rules, repeat-no-show consequences — are venue policy decisions today; enforce them as house rules at the front desk and capture the reason in the booking note. The platform tallies a member's lifetime no-show count from the booking history, which managers use to gate large-party reservations from chronic no-shows.

Walk-In vs Held Tables

When a table is booked but the booked party is late, the operator decides whether to hold the table or assign it to a walk-in. The platform's job is to record the decision and the resulting session against the right booking and member, so the audit trail is intact regardless of which way the call went.

F&B Menu, Combos & Modifiers

F&B is often the difference between a profitable centre and a struggling one. Snooker King treats the kitchen as a first-class citizen — orders bind to tables, kitchen tickets print automatically, stock decreases live, and the menu is in your hands at all times.

Building a Menu

Modifiers in Detail

Modifiers are stored as structured data on each order line, so the kitchen ticket reads cleanly and reports stay aggregable. Examples:

• Tea — Sugar level: 30%, Ice: less, Add: pearls (+RM 2.00)
• Burger — Doneness: medium, Side: fries, Sauce: chipotle

Combos

A combo is a curated bundle that appears as a single item on the menu but expands into its component lines on the kitchen ticket. The ticket shows the components so the cook line is never guessing; the receipt shows only the bundle line so the customer sees the value.

Photos, Descriptions & Up-Sell

Every item carries a photo, short description, and an optional long description. These power the member-portal Marketplace and the operator POS picker. A clean photograph routinely lifts attach-rate by double-digit percentages.

Pricing Strategies

• Static price — most items.
• Time-banded price — happy-hour drinks, lunch sets.
• Member-tier discount — e.g. Gold members get a flat percentage on snacks.
• Combo override — bundle price ignores component prices.

Item Availability

Each menu item carries an active / inactive flag in the menu editor. Toggling an item to inactive removes it from the operator POS and from any customer-facing menu surface (such as the QR-token public order page). When inventory is configured (Chapter XIV), low-stock items are surfaced for review so a manager can deactivate them before the cook line runs out — that step is operator-driven, not automatic.

Multi-Centre Menu Strategy

Two patterns work for most chains:

1. Single master menu — push from the flagship to all centres; small price overrides per branch.
2. Tiered menus — group centres by format (lounge, hall, academy) and maintain one menu per group.

F&B POS, KOT & Kitchen Display

When the customer is hungry, every second matters. The POS is built so a moderately busy bar can take, modify, and send an order in well under a minute.

Taking an Order

KOT — the Kitchen Order Ticket

Every submitted order produces a KOT formatted for thermal printers. Each ticket shows table, member name (if any), items, modifiers, quantity, special notes, and a sequence number. Re-prints are one tap away from the operator station.

Order & Item States

State is split across three rows for clean accounting — the order itself, each line item on the order, and the F&B session that groups orders for one table:

There is no platform-wide "completed" state on fnb_orders itself; once submitted, the order is read-only and "delivery" is the cook line's job — the platform does not track plate-on-table state.

Kitchen Output is Print-First

Snooker King does not run a screen-based KDS where cooks tap "in progress" and "ready". The kitchen workflow is print-first — every submission emits a fresh KOT to the kitchen printer (or bar printer for bar-routed categories) and the cook line works the printed tickets. Re-prints are one tap from the operator station; modifications after submit print a delta KOT so the cook can spot what changed without re-reading the whole ticket.

Voids, Comps & Refunds

Mistakes happen. Snooker King draws a strict distinction between three actions:

Take-Away & Member Pickup

An order without a table binds to a member instead. The KOT prints with the member's name and phone for pick-up; the customer can also track readiness in the portal Marketplace tab.

Payment from POS

The POS can take payment immediately or push the line into the table's running tab. If immediate, the same multi-tender splitter used for table sessions applies (Chapter XV).

Inventory & Stock Control

Inventory in Snooker King is deliberately simple — a flat stock-level tracker bolted onto the existing item catalog, not a full recipe-driven cost-of-goods engine. Most centres need a clean low-stock signal, not theoretical-vs-actual variance accounting; the platform delivers the former by default.

What the Module Actually Tracks

• Stock-tracked items — any catalog item can be flagged as stock-tracked from the inventory tab. Untracked items behave as before — they're sellable, but the platform doesn't decrement anything when they sell.
• Current quantity — a single integer per item, per centre.
• Minimum stock alert (min_stock_alert) — when current stock falls to or below this number, the item shows as low-stock in the inventory list and on the operator console.
• Stock movements — every adjustment writes a row to the movements log: who, when, how many, and a free-text reason. This is the audit trail.

Three-Panel Editor

The Inventory tab uses a three-panel layout: Categories on the left, Items in the middle, Movements / Combo Detail on the right. Items can be drag-reordered and grouped by category. The view toggles between list and grid; sort presets include "lowest stock first" so the morning shift can scan the top of the list and place orders.

Daily Workflow

Invoices, Payments & Tenders

Every economic event in the centre — table time, F&B order, membership upgrade, comp, refund — flows into invoices. The invoice engine is the audit backbone of the platform.

Invoice Lifecycle

An invoice progresses through four payment_status values on its revenues row: Pending (lines can still be added or edited), Outstanding (issued but not fully paid; outstanding_amount > 0; settle only with a monetary tender, Appendix C), Paid (locked from edits without explicit re-open by an authorised employee), and Cancelled / Voided (retired before settlement with a reason in System Logs). The platform does not auto-flag "overdue" — the outstanding state is the only unpaid signal, read live. Historical invoices stay in revenues with their immutable number; nothing is archived elsewhere.

Supported Tenders

Settlement splits into monetary tenders (real money in/out) and internal-ledger tenders (member balances applied at creation). The two pools are kept separate so an outstanding-balance receipt can never be paid down with non-monetary credit:

Multi-tender across the four monetary pools is supported on a single invoice (part cash, part card, balance e-wallet, all in one settle). Internal-ledger tenders (wallet, points, stamps) apply while the invoice is still being built. Appendix C lists the formal allowed-tender set for outstanding-balance receipts.

Discounts & Promotions

Discounts apply at three levels, in order:

1. Line-item — manual percentage or amount on a single line.
2. Invoice-level — applied to the running subtotal (member tier, voucher, campaign).
3. Promotion engine — rule-based (e.g., "Mondays after 22:00 — 20% off Pool tables").

Reading an Invoice

The printed and PDF invoice is structured for both customers and auditors:

• Header — centre name, address, tax ID, invoice number, date.
• Member block — name, ID, tier, QR (if applicable).
• Lines — table session, F&B items, modifiers, discounts.
• Totals — subtotal, taxes, grand total.
• Tenders — each payment method, change given.
• Footer — operator name, terminal, time of close, audit reference.

Refunds

Refunds are gated by the operator's role and refund permission flag. The flow:

Idempotency

The payment layer is idempotent: if the network drops mid-payment and the operator retries, the system de-duplicates the second request and never double-charges. The operator can retry safely without calling support.

Split-Bill Workflow

Splits are common in social play. Snooker King supports split modes that match how groups actually settle their bills, and keeps the parent invoice and revenue counters perfectly in sync.

Split Modes

• Even split — total ÷ N people; each pays the same.
• Itemised — each person picks the lines they consumed.
• Custom amounts — operator types each share manually.
• Hybrid — start with itemised, then add a service-charge split evenly across all parts.

How a Split Settles

1. Operator opens Split bill on the active invoice.
2. System creates one child invoice per payer, each with its own outstanding balance.
3. Each child accepts its own multi-tender payment.
4. When every child is fully paid, the parent invoice flips to paid; outstanding badge clears.

Refunds on Split Invoices

A refund applies to a single child invoice. The parent's totals recompute to keep the audit chain coherent.

Splits in the Portal

Member-initiated splits in the portal create QR codes that other members scan to claim their share. The operator station shows progress in real time.

E-Invoice & LHDN Compliance

For Malaysian operators, Snooker King produces compliant e-invoices and submits them to LHDN's MyInvois system. For other jurisdictions, the same engine applies a two-stage tax stack — service charge first, then tax — and stamps both rates on every line.

LHDN Lifecycle

1. Draft — created automatically alongside the sales invoice.
2. Unvalidated — created locally, not yet submitted. The internal revenues.status column carries this value while the receipt is still editable.
3. Submitted — sent to MyInvois; document UUID captured. The portal link becomes live the moment LHDN responds with a valid UUID, even before final validation.
4. Valid — LHDN accepted the document. (MyInvois's literal status string is Valid, not "Validated" — the platform stores it verbatim so a status check against LHDN never drifts from the source of truth.)
5. Invalid — LHDN rejected the document post-submission. The platform exposes the rejection error so it can be fixed and resubmitted.
6. Cancelled — revoked by the issuer within the LHDN-permitted 72-hour cancellation window, with reason captured.

The check-status handler treats ['Valid', 'Invalid', 'Cancelled'] as terminal — once LHDN reports one of those, the platform stops polling MyInvois for that document.

What Is Captured & the Operator Workflow

Each submission persists the document UUID, submission timestamp, original MyInvois status string, item codes/quantities/unit prices/taxes per line, buyer details (name, NRIC validated to 12 continuous digits, address) where required, and any error messages from LHDN's response. For most operators e-invoicing is invisible — submission runs in the background and only two screens matter: the compliance dashboard (daily count of submitted, valid, failed) and the failed queue (Invalid invoices with the underlying error and a one-tap resubmit).

Deposits & Member Credit

Deposits and member credit are the platform's prepay layer. Members fund their wallet ahead of time and spend it across tables, F&B, and tournament entries.

How Deposits Work

1. Member tops up their wallet via the portal or at the cashier (cash, card, e-wallet).
2. The deposit posts to the member-credit ledger as a positive entry.
3. Each spend posts a negative entry; the running balance is always exact.
4. Refunds reverse a specific deposit row, never delete it — the audit chain is preserved.

The Member Wallet Fields

Each member's wallet, scoped per-organization on the member_organization_accounts row, holds four numbers:

• Base credit balance (base_credit_balance) — the member's own money, loaded by top-up. This is what a refund returns.
• Bonus credit balance (bonus_credit_balance) — credit issued by the venue (top-up promotion, comp, recovery). Usually non-refundable; spend-rule configuration decides which discounts it can stack with.
• Reward points — earned per spend (Chapter XIX); burned at a configured ratio at checkout.
• Tokens — a discrete-credit currency for specific reward redemptions, separate from cash.

Refund & Cash-Out

Base credit is refundable at any time, subject to the centre's policy and the operator's refund permission. Bonus credit is non-refundable by default. Every cash-out creates a permanent ledger entry; the original deposit row is preserved so the audit chain stays intact.

Stamp Card & Loyalty

The stamp card is a dual-currency loyalty system: stamps for visits and milestones, points for spend. Members earn passively as they play; redemption is a single tap.

Stamps & Points

Stamps are a per-centre digital loyalty currency written to a single ledger (stamp_card_transactions); each row is auditable with source plus originating revenue_id / session_id / table_id / invoice_id. They are awarded when a qualifying event fires (session close, invoice settled, manual add). A per-period cap (centre columns stamp_period_mode, stamp_max_per_period, stamp_period_hours) limits earn within a rolling window — mode is day (centre TZ), hours (rolling N), or unset. Spend is on any catalog item with items.stamps_cost set; points work identically via items.points_cost. Practical difference: stamps are small integers (one per visit), points scale to spend amount so they fit higher-value redemptions; reports show stamp-cost and point-cost separately.

Redemption Flow

Redemption is staff-driven and identity-bound — there is no portal-generated redemption code that an operator types in:

Campaigns & Promotions

Campaigns are the lever a manager pulls when a Tuesday afternoon needs a lift. A campaign is a discount rule with a window, a scope, and a redemption record — and that is the unit of work the platform manages.

The Campaign Shape

Every campaign is a discount applied to qualifying invoices. The shape is consistent regardless of how the customer encounters it:

• Discount — a percentage or a flat amount.
• Window — start and end dates; optionally bound by day-of-week / time-band conditions.
• Coupon code (optional) — for campaigns that the member must redeem by entering / scanning a code.
• Scope — what the campaign applies to: a table type, an F&B category, specific items, a member tier, a minimum spend.
• Redemption record — every use is logged so the campaign's effect is measurable.

Common patterns built from this shape: a publishable coupon code (one or many uses), an automatic time-banded discount (no code needed), a member-tier discount, a single-use voucher issued by management to a specific member or list.

Stacking

Two campaigns plus a member-tier discount can compound in unintended ways. Always walk the resulting price through the proforma screen on a sample bill before publishing — every step of the pricing pipeline (Appendix D) is visible there, so the diverging point is obvious if the final number isn't what you expect.

Rental, Ticketing & Countdown

Three smaller modules round out a typical centre's revenue streams: rental of equipment, ticketing for events, and countdown packages that bundle time into flat-fee promotions.

Equipment Rental

Cues, gloves, chalks, and accessories can be rented per session or per visit. The Rental module is built around four handler families:

• Plan handlers — define rental plans (item, price, deposit, duration).
• Session handlers — open and close active rentals; track who has what and since when.
• Forfeit handlers — capture deposit forfeit when an item is returned damaged or not at all, with reason and amount stamped to the ledger.
• Settings handlers — per-centre rental defaults.

Every rental_* POST is CSRF-validated and session-write-closed before processing, so rapid-fire scans at a busy counter never fight for the session lock.

Ticketing Mode (Rapid Table Activation)

"Ticketing" in this platform is not event ticketing — it's a centre-level toggle (centers.ticketing_mode) that switches the operator station into a kiosk flow optimised for fast table starts. With ticketing mode on, a member scans their QR or RFID card, the system resolves the card via resolve_table_by_qr, and a table is activated for them in one tap — bypassing the full operations grid for venues whose front-of-house works more like a turnstile than a host stand.

Countdown Packages

A countdown package is a flat fee for a fixed block of time. Each package row in countdown_packages carries name, duration_hours + duration_minutes, price, its own sst_rate and service_charge_rate, a status, and a table_selection_mode that decides whether the package is restricted to specific tables or available across the centre. When the package is sold and started, a session-level ledger row in countdown_session_packages tracks the remaining time and links to the parent game_sessions.id; once the time runs out the operator is prompted to sell another package, never auto-charged.

RFID Card Scan Mode

QR codes are universal but a physical card is faster. RFID Card Scan Mode lets a member tap a card on a reader at the door or counter and be identified instantly.

What It Does

• Resolves an RFID card ID to a member account.
• Auto-assigns the member to an active or pending session at that station.
• Triggers tier discounts and stamp accrual without operator intervention.
• Logs the tap as a member visit for retention reporting.

Setting Up a Reader

Issuing Cards

Cards are linked to members from the member profile screen. A single member can carry multiple cards (e.g. a primary and a backup). Cards can be deactivated instantly if lost.

Reports & Analytics

Reports are not a byproduct of a Snooker King install — they are one of the reasons to install it. Three families of reports cover almost every question a manager will ask.

Financial Reports

Operations Reports

• Table history — every session on a table, with member, duration, and the revenue rows it produced. Lives under the Table History module per centre.
• Average session length — derived directly from duration_seconds on closed sessions; filterable by table type and date range.
• F&B order detail — per-session item-level view from fnb_order_items with modifier breakdown.

The platform does not currently ship a built-in occupancy heat-map, a maintenance-hours roll-up, or a recipe-driven stock-variance report. If those numbers matter to your business, derive them from the underlying data via export.

Member & Loyalty Reports

• Member ledger — full transaction history per member from stamp_card_transactions, member-credit ledger, and revenues.
• Top spenders — leaderboard ranked by lifetime invoiced amount per organization.
• Battle & tournament participation — players, frames, format, by date range.

Acquisition-funnel and retention-cohort dashboards (e.g. "% of new members still active at 30 / 60 / 90 days") are a frequent ask but are not built into the platform today. The data needed to compute them is present in members and revenues — it just hasn't been packaged as a one-click report.

Thermal Shift Reports

The Revenue Report module produces a compact 80mm thermal-printer summary perfect for the safe envelope at end of shift: tender breakdown, voids, comps, refunds, and the cash variance against the float. Reprints are one tap.

Export

Reports can be exported as CSV directly from the operator console, or printed as 80 mm thermal slips through the Revenue Report module. Excel and PDF export, and recurring scheduled-email reports, are not currently part of the platform — pipe the CSV exports into your accounting system or BI tool when those formats are required.

Spotting Outliers

The platform's reports are designed to be read every day, not subscribed to passively. The most useful rituals:

• Open Revenues each morning. Tender mix, voids, comps, refunds. Anything that looks unlike yesterday is worth a closer look.
• Eyeball the Comp & Void report weekly. Operators with abnormal void rates jump out from the table.
• Scan low-stock items. Items at or below their min_stock_alert jump to the top of the inventory tab — a 30-second scan after lunch service avoids weekend-evening run-outs.
• Watch outstanding balances. Sums that creep up week over week are a workflow problem, not a software problem.

System Logs & Audit Trail

If reports tell you what happened, system logs tell you who, when, from where, and why. The audit trail is the platform's memory, designed for forensic clarity rather than developer convenience.

What Is Logged

Every consequential action — and many merely interesting ones — produces a log row. The viewer is role-scoped, so each user sees only what they are entitled to see.

The log_type column uses an open vocabulary, so new event categories can be added without schema migration. Common values seen in the running system today:

Anatomy of a Log Row

• log_type — open vocabulary; categorises the event.
• user_id, user_type, user_name — actor identity.
• center_id — scope of the event.
• action, entity_type, entity_id — what was done to what.
• outcome — success / failure / partial.
• details — JSON payload (sensitive keys stripped before persistence).
• ip_address, created_at — request context.

Searching the Log

The Log Viewer supports filters on every column. Common starting points:

• By user — every action a specific operator took today.
• By log type — every payment_failure in the past week.
• By outcome — every failed action, regardless of category.
• By entity — every change to a specific invoice or member.

Sensitive Key Stripping

Before any payload is persisted, the writer strips a deny-list of sensitive keys (passwords, card numbers, certain identifiers). This means you can log freely in development and the production audit will never leak credentials.

Forensic Investigations

When something looks wrong (missing cash, complaint, unauthorised refund), the standard playbook is:

Bug Reports & Support

Real software lives or dies by how quickly its operators can flag problems and how transparently those problems are resolved. The Bug Reports module is built around that loop.

Filing a Report

Lifecycle of a Report

The status ENUM has exactly four values:

There is no "Won't Fix" status in the platform — out-of-scope tickets are kept on Pending Human Decision with the rationale in a thread comment, so the audit trail and the reasoning live together.

Devices & Hardware

A snooker centre is also a small fleet of devices — printers, displays, RFID readers, and lighting relays. Snooker King treats each as a first-class entity with a friendly name, a centre binding, and an explicit health story so problems are noticed in minutes rather than at end-of-shift.

Printers

Printers are configured per centre with two technical types: escpos (thermal, 58 / 80 mm, USB / Bluetooth / network) and windows (A4 driver-printer for invoices). Each carries a friendly name, a connectivity mode, an optional centre-default flag, and a status (active / inactive). Routing to specific printers is decided by menu category (Chapter XII), not by individual item.

The Print Queue Lifecycle

Every job — a kitchen ticket, a thermal receipt, a cash-up slip — passes through a self-healing per-centre queue rather than printing inline. A small browser-side poller running on each operator station fetches pending jobs scoped to its centre, marks them printing while the driver is engaged, and writes back printed or failed with the timestamp. Jobs hold their full payload (HTML for ESC/POS rendering, raw bytes for Windows drivers) so a stuck printer can be requeued from another station without losing the original document.

queued ──poller picks it up──▶ printing
printing ──driver returns OK──▶ printed
printing ──driver fails / times out──▶ failed
failed ──operator requeues──▶ queued (new attempt row)

Failed jobs are not auto-retried; an operator must resubmit from the print queue panel. This is a deliberate guard against double-printing. The queue stores its rows in the print_queue table; the table is auto-created by the API on first use, so a fresh deployment never blocks on a missing schema.

Live Monitors

Wall displays open the public Monitor URL with a centre-specific token; the URL itself is the credential, so revoke and reissue if a screen leaves the venue. The Monitor refreshes its data on a polling interval rather than a push channel, which keeps it dependable on hotel-style Wi-Fi.

RFID Readers

Most RFID readers behave as USB keyboard wedges — they "type" the scanned card number into a focused input field. The platform binds a quick-scan input on the operator console; whatever the reader emits gets resolved through stamp_resolve_member_card against the member_cards table (Chapter XXII).

Lighting Relays

Lighting relays drive the table lamps via Vyrox's MQTT gateway (Chapter V). The platform issues turn on / turn off commands on session start and end, and queries channel state on demand for the operator's relay badge — there is no relay-side heartbeat. Command failures (timeout, unreachable gateway) raise a light_control_failure log row with the table and channel for after-shift triage; a test-mode toggle lets a manager pulse a relay during commissioning without disturbing live tables.

Theming & Branding

Theming is a deeper feature than most platforms expose. Snooker King ships with multiple curated themes for the operations console and the Live TV Monitor; each can be tuned to match a venue's house style.

Console Themes

The console ships with a family of themes inspired by cue-sport rooms. Examples:

• Classic Baize — vibrant green, the default.
• Midnight Blue — muted blue, low-light operator stations.
• Rosewood — mahogany warmth, premium lounges.
• Charcoal — warm minimal dark, modern halls.
• Slate Plum — dusty purple, distinctive lounges.
• Felt Dusk — green dusk, soft on the eye for late shifts.
• Cue Ash — oak and chalk, light tone for daytime.

Additional presets ship from time to time. Each user picks their own; managers can also pin a per-shift theme to shared terminals.

Live Monitor Themes

The Live TV Monitor has its own theme family separate from the console: Broadcast Pro, Apex Lounge, Glass Modern, and Departure Board (Chapter VI). They are intentionally bolder and louder than console themes, because they read across a room.

Branding

Branding is configured at the organization level and pushed down to centres:

• Primary & accent colours.
• Square logo (≥ 512px, transparent PNG recommended).
• Wordmark (SVG preferred).
• Default monitor footer text.
• Email header image and receipt header.

Centre Chat & Announcements

Two lightweight communication tools sit alongside the operations console: a centre chat for in-venue conversations, and an announcements board for broadcasts.

Centre Chat

Centre chat is a real-time channel scoped to a single centre. Use it to coordinate operators, confirm a kitchen call, or pass a member request to a manager without leaving the console. Messages are stored in the platform database and are subject to the same role-based visibility as everything else.

Announcements

Announcements are broadcast messages — created at organization or client level — that appear in the operator console and (where configured) on the member portal Home tab. Use them for shift handover notes, scheduled maintenance, or campaign launches.

Member Social

The member-side equivalent is the Social tab in the portal. Members chat with friends inside social_chat_rooms (rooms can be 1:1, group, or attached to a social game), post photos, react to showcards, and see localised leaderboards. Operator-role accounts do not have read access to those threads — the message bodies are stored to power the conversation but the access-control layer keeps them out of staff dashboards. Honour that boundary in your house policy too: chat content belongs to the members, not to the venue.

Mobile App & Mobile API

The mobile app is the member portal hardened with native capabilities. It is the surface most customers touch most often, engineered for one-handed, mid-frame use.

Installing

• iOS — App Store, search "Snooker King".
• Android — Google Play, search "Snooker King".

Native Capabilities

The Mobile API

The native app talks to the platform through a dedicated, versioned mobile API (MOBILE_API_VERSION = "1.0.0"). Authentication is via Bearer token in the Authorization header; tokens are valid for 30 days from issue, after which the app re-authenticates silently. The mobile API endpoint is purpose-built for the Snooker King Flutter app — it is not a general-purpose public partner API today, so third-party integrations should be brokered through the platform team rather than coded against this surface directly. Login attempts are rate-limited and return HTTP 429 once a per-IP cap is hit.

Privacy & Permissions

• Location — only used to suggest the nearest centre.
• Camera — receipts and avatar only.
• Notifications — separated into Bookings, Battles, and Marketing; users can mute marketing alone.

Employees, Settings & Permissions

Settings are organised by scope, not by feature. The closer the scope to the user, the more often the setting changes.

Scope Hierarchy

Adding an Employee

Backups & Restore

The platform takes nightly database backups, retained for a configurable window. Manual point-in-time restores are available on request from support. Granular restore (e.g. one invoice or one member) is not exposed in the UI, by design — that surface area would be a fraud vector.

Troubleshooting & FAQ

Most issues resolve in under five minutes. The decision tree below covers most cases reported by new operators.

First-Aid Checklist

1. Is the internet up? Open any other website.
2. Hard-refresh the page: Ctrl+Shift+R (Win) or Cmd+Shift+R (Mac).
3. Try a different browser tab. If it works there, your tab is stale.
4. Check the notification bell — most "the system is broken" reports turn out to be an unread alert.
5. Sign out and sign back in. Half of remaining issues clear here.

Common Issues & Fixes

"My screen is frozen on the operations grid."

Real-time updates are pushed live. If the connection drops, the grid stops updating. Hard-refresh restores it; if it recurs, your network may be unstable.

"I clicked Settle but nothing happened."

Settle is disabled if the table has open kitchen tickets. Look for the small bell or chip on the cell — it indicates pending kitchen items. Mark those completed first.

"Discounts are not applying."

Check, in order: was the member scanned? Is their tier active? Is the discount in the active time band? Is there an organization-level override that excludes that item?

"The Live TV Monitor went blank."

The monitor browser sometimes loses focus during OS updates. Press F5 on the wall keyboard, or use Devices → Monitors → Refresh from the console to push a remote refresh. If the issue recurs, disable display sleep on the monitor PC.

"The light didn't turn on when I started a session."

Check the relay heartbeat in Devices → Lighting. A device showing error is offline; the table can still be played with a manual lamp switch while the relay is investigated.

Frequently Asked Questions

Q. Can I run Snooker King without internet?

The platform is cloud-native. Short outages are tolerated by the operator app (orders queue locally), but settle and payment require connectivity. We recommend a backup mobile router for centres in unstable-internet areas.

Q. How many tables can one centre handle?

The Live TV Monitor renders cleanly up to about 60 tables on a 1080p display. The console grid scrolls indefinitely; some customers run well over a hundred tables on one centre.

Q. Can I migrate from another POS?

Yes. The platform accepts CSV imports for members, F&B menus, and historical sales. Custom migrations from common POS products are available via the support team.

Q. Is my data encrypted?

Yes — TLS in transit, AES-256 at rest. Sensitive identifiers (member phone, email) are encrypted at the column level with path-derived keys; QR cards remain valid across migrations between domains.

Q. Can I export everything?

Yes — CSV, Excel, JSON, or PDF. Full database exports are available on request. We believe in your right to leave with your data.

Q. What about offline kitchen printing?

Kitchen printers connect over the local network. If the cloud is down but the LAN is up, kitchen tickets continue to print using a local relay so the cooks are never stranded.

Where to Get Help

• In-product — bug-report icon in the console header.
• Email — your dedicated support address.
• Phone — the success manager assigned to your account.
• Status page — incidents and maintenance windows.

Authentication & Security

Snooker King's authentication layer is engineered for shared terminals, busy shifts, and the inevitable bad actor.

Five Distinct Login Surfaces

Each role logs in through its own form, and the system tracks user type in the session for the visit's lifetime: Admin login (platform administrators), Client login (tenant owners), Organization login (regional directors), Employee login (managers and operators), and Member login (customers, web portal).

Brute-Force Defences

The platform enforces rate limits on two independent axes — by source IP and by the targeted email — so neither a single noisy IP nor a botnet rotating IPs against one account can grind through:

When a cap is hit the API responds with a wait-minutes message without leaking which axis tripped; successful sign-in resets the IP counter immediately. The form refuses double-clicks while a request is in flight (single-flight submit), every successful sign-in calls session_regenerate_id(true) to discard any planted session ID (session-fixation defence), and when an email exists in a different login surface the response steers the user to the right page without confirming the password (helpful but not leaky).

CSRF & Stale-Snapshot Recovery

Every form carries a CSRF token tied to the session. If the page sat open for hours and the token went stale, the platform refetches the login HTML, parses a fresh token from the meta tag, and retries the submission once before surfacing an error. Most operators never notice.

Password & Reset Flow

1. User clicks Forgot password on the login page.
2. A 64-character random token is generated. The platform stores only its SHA-256 hash, never the raw token, so a database read alone can't replay the link.
3. An email is dispatched containing the raw token in a one-time URL. The token is valid for one hour from issue, measured in UTC.
4. The link verifies the token by hashing the supplied value and comparing — then accepts a new password, stored with password_hash() using PASSWORD_DEFAULT.
5. On success the user is auto-signed-in with a fresh session ID; other devices already signed in to the account retain their sessions until natural expiry.

Username & Email Login

Most roles log in by email; employees can additionally log in by username. The lookup is case-insensitive (LOWER(username) = LOWER(?)), the row must be active and not soft-deleted. Choose usernames you would be happy to see on an audit row — they appear unmodified in System Logs against every action.

Multi-Centre Access & Sessions

An employee belongs to a centre via center_id; managers reaching multiple centres carry a separate allowed-centre list checked on each request. Each role keeps its own session variables (no identity bleed across roles). The session is closed and rewritten before rapid sub-calls (consecutive RFID scans) so file-lock contention can't slow operator taps. For shared operator stations, expect sign-out at the end of every shift — treat the operator account like a key, not a public terminal.

What Gets Audited at Login

Every attempt — success or failure — writes to System Logs (Chapter XXIV) with actor, timestamp, IP, user-agent, and outcome. A spike in login_failure entries from one IP is the first signal worth looking at.

The Public Order Page

Customers don't need to log in to order. A QR sticker on the table opens a public, token-gated ordering page that runs in any phone's browser.

How It Works

1. Each table has a printed QR sticker linked to a unique token.
2. The customer scans; their browser opens the public order page with that token.
3. The token resolves to a centre and a table on the server side.
4. The customer browses the F&B menu, builds a cart, and submits the order — no account required.
5. The order lands in the operator station and the kitchen exactly as if a waiter had typed it.

Built-In Safeguards

• Token validation on every API call — validateQRToken() runs on the server side for each request the page makes; a stale or revoked link can't be reused after revocation.
• Token revocation / rotation — tokens can be revoked or rotated without reprinting stickers; the page surfaces a "this table no longer accepts orders here" message and stops accepting input.
• No-referrer policy — the page emits Referrer-Policy: no-referrer as both an HTTP header and a meta tag, so the token never leaks to external CDNs through outbound image / link requests.
• Scoped writes — every mutating action is bound on the server to the centre and table the token resolves to, so a stolen token can never inject orders against a different table or centre.

The page deliberately does not implement a CSRF token (it has no logged-in session to bind one to) and does not rate-limit image fetches — both safeguards rely on the upstream token check and the no-referrer policy.

Optional Member Linking

Mid-flow, the customer can link the order to a member account by entering their phone number; an OTP is sent and verified, after which any tier discount or wallet credit applies. Linking is optional — a guest can still complete the order without it.

The Marketplace

Beyond the centre's own F&B menu, the Member Portal hosts a peer-to-peer marketplace where members buy and sell cue-sport gear directly from each other.

Two Sides, Three Views

• Browse — filterable list of all active listings.
• My Listings — the member's own posted items, with their lifecycle.
• Create Listing — multi-step form with image upload.

Listing States

Filters & Search

• Category — cues, cases, tips, chalks, accessories, services.
• Condition — new, like-new, good, fair, for-parts.
• Price range — minimum and maximum.
• Live debounced search by title and description.

Listing Detail View

Tapping a listing opens its detail page:

• Image carousel — swipe to browse photos.
• Title, price, condition, category.
• Description with seller notes.
• Seller card — name, member tier, joined date.
• Contact Seller button — opens a direct message thread.
• Report Listing button — flags the listing for moderation review.

Creating a Listing

Direct Messaging

Buyer-seller conversations live in the same chat infrastructure as the rest of the portal (Chapter XXVIII), so push notifications and unread badges work consistently. Operators do not see the contents of marketplace chats.

The Setup Wizard

Every fresh deployment runs through a guided wizard. By the time you exit it, you have a working organization, a centre, and a populated table grid — all without touching a settings page.

Four Steps

The progress strip at the top of the wizard reads Organization → Center → Table → Rate. Each step has its own form and persists its result before advancing.

1. Organization — legal name, contact email, mobile, and time zone.
2. Center — name, address, and how many tables to start with.
3. Table — type (Snooker / Pool / English), zone, and the canonical Live Monitor seed.
4. Rate — the default hourly rate that becomes the centre's starting tariff. After saving, the wizard finishes and drops you on the Operations page.

Skip Logic

If an existing organization, centre, or table set is detected, the corresponding step is skipped automatically. This means the wizard can re-run without any risk of duplicate data — useful if a setup is interrupted.

Direction & State

Each step records its created entity IDs, allowing forward and backward navigation without losing partial progress. If you exit and return tomorrow, the wizard resumes where you left it.

After the Wizard

You land on the Operations page with an empty grid of correctly-configured tables. From there:

• Open Settings to refine tariffs, hours, branding.
• Open F&B → Menu Editor to add categories and items.
• Open Devices to register the printer, monitor, and lighting relays.
• Invite employees from Employees → New (Chapter XXX).

Notifications & Sound

A busy centre is full of audible cues. Snooker King's notification and sound system is opinionated about which alerts demand attention and which fade into the background.

Notification Channels

• Toasts — short pop-ups in the corner of the screen. Errors and warnings appear bottom-left; successes and info appear top-right.
• Notification centre — opened from the header bell; a scrollable history (newest first, capped) of recent alerts.
• Email — for high-priority events like new bug reports, status changes, and resolution notices.

Per-User Mute

Each operator can independently mute two streams:

• Information stream — successes, info-level toasts.
• Alerts stream — errors and warnings.

Mute state persists in the browser. If an operator working a quiet shift mutes everything, their preferences come back the next day on the same device.

Sound Effects in the Console

Console sounds are synthesised in the browser — no audio file downloads, no licensing complexity:

• Soft chime on success.
• Distinct error tone on failure.
• Hover sounds (subtle) on key buttons.
• Text-to-speech announcements (English, Bahasa Malaysia, Mandarin) for selected events.

The Member Portal Sound Bus

The member portal exposes a global memberSound object whose methods correspond to specific UX moments. Each method emits a synthesised tone matched to the moment's emotional weight:

Persistent Mute

Members can mute the entire sound bus from their settings drawer. The preference is stored locally so the choice survives reloads.

Battle Audio

Battles run through a dedicated audio system organised around Match Vibe presets. Each preset bundles sound effects, voice (text-to-speech commentary), and visual animation into a named look, so the operator picks one option rather than balancing three sliders. Presets shipped with the platform include broadcast-style, minimal, and silent options.

Reconciliation Tools

Even with rigorous live calculations, rounding and concurrency can produce tiny ledger drifts over thousands of invoices. Snooker King ships four admin-only reconciliation utilities to put the books straight without touching customer-facing data.

The Four Tools

Safety Properties

• Dry-run by default — every tool reports what it would change unless explicitly told to apply.
• Bearer-token guarded — only platform administrators can run them.
• Idempotent — running twice in a row never compounds an effect.
• No customer-facing change — these tools touch internal totals to match the source-of-truth, not customer-visible amounts.

When to Use Each

• A single invoice's discount column "doesn't add up" — run discount invariant.
• An audit shows a few rows where line totals are pennies off — single-row absorption.
• One invoice has a larger drift across multiple lines — cascade.
• Quarterly book-tying — org-wide baseline, review the largest deltas first, then targeted apply.

Legal & Consent

Three legal pages ship with the platform — Terms of Service, Privacy Policy, and Cookie Disclaimer. They are versioned, consented to, and easy to amend without a release.

The Three Documents

• Terms of Service — usage rules, acceptable behaviour, liability, dispute resolution.
• Privacy Policy — what data is collected, how it's used, retention, member rights.
• Cookie Disclaimer — categories of cookies, opt-in / opt-out controls.

Versioning & Consent

Every document carries a version. When a new version is published, members and operators are presented with the change on next sign-in and asked to consent. The consent (with timestamp and version) is recorded against the user. Old versions remain readable in the legal archive for as long as any consent of that version exists.

Configuration

Document content lives in configuration files separate from the application code. Updating a clause does not require a code release — only a re-publish of the relevant document with a new version number.

Where Members See It

• The portal Settings drawer has a Legal link to all three documents.
• First-time sign-up requires explicit consent before account creation.
• A version bump triggers a one-time consent prompt on next sign-in.

Encryption, QR Tokens & Privacy

Behind every member QR card, every public Cast URL, every public order link, and every Live TV Monitor token sits the same small set of cryptographic primitives. They are the difference between a feature and a leak.

What Gets Encrypted

Path-Derived Keys

Encryption keys are derived from a small set of immutable values held server-side, including the deployment path itself. The benefits are practical:

• A migrated venue (different domain, same content) keeps every QR card and printed badge valid.
• A leaked database with no key material is useless — the column-level encryption is not reversible without the host.
• Keys are not committed to source control, ever.

Token Validation Pipeline

Every encrypted token follows the same five-step validation pipeline on the server:

1. Decrypt with the path-derived key — malformed payloads fail at this step.
2. Schema check — required fields, type, length.
3. Window check — for time-bound tokens (Cast URL, FNB order), reject outside the valid window.
4. Revocation check — for revocable tokens, reject if the issuing record is marked revoked.
5. Rate limit — typical cap is 30 failures per minute per source IP, returning HTTP 429 thereafter.

Privacy Posture

• No referrer leakage — public surfaces (Live TV Monitor, Cast URL, public order) send no-referrer so tokens never bleed to upstream CDNs.
• Sensitive-key stripping — the audit log writer removes a deny-list of keys (passwords, card numbers, certain tokens) before persistence.
• CSRF tokens — every authenticated form carries a session-bound token; stale tokens are auto-refreshed and the submission retried once before surfacing an error.
• TLS in transit, AES at rest — TLS terminates at the host; column-level AES protects the highest-sensitivity fields.

Operator Hygiene

• Treat printed QR codes as identifying material — the venue's posture should match how it would treat printed member cards.
• Revoke a Live TV Monitor token when a screen is decommissioned; print a fresh one when wall hardware is replaced.
• Refresh public Cast URLs after a tournament so old links cannot replay against the current bracket.

Cron, Schedules & Background Automation

Not everything happens because a button was pressed. A small fleet of background tasks keeps the audit trail tidy, releases stuck sessions, expires bookings, and pushes off-peak compliance work to quiet hours.

The Background Workers

The platform's confirmed scheduled task is the battle auto-timeout in debug/cron/. Other background-style behaviours are handled in-request (lazily, on first eligible request after the time window passes) rather than by a separate scheduler.

Manual / Admin-Only Tasks

Reconciliation tools (Chapter XXXVII) and one-off maintenance scripts are not on a cron — they are invoked by an administrator with a bearer token. They are designed to run on a quiet hour, in dry-run first, and apply only after review.

Time Zone Discipline

All timestamps used by background workers are UTC. Display layers convert to local time at render. Two practical implications:

• Durations are computed in the database, not in the browser, so PHP/MySQL skew can never produce a zero-or-negative session duration.
• Cron schedules are UTC; the battle auto-timeout (the platform's one true cron) fires at the same UTC instant regardless of where the operator team lives.

Idempotency & Safety

• Single-flight — no two workers race for the same record; SELECT ... FOR UPDATE or unique row locks are used where state transitions matter.
• Append-only logs — workers write log rows; they never edit older logs.
• Dry-run first — admin reconciliation tools have a default dry-run; cron tasks have hard limits on per-run row counts.
• Backoff — retried tasks (e.g. e-invoice resubmission) use exponential backoff so transient LHDN incidents don't snowball into runaway request volume.

Reading the Cron Trail

Each worker writes a structured row to System Logs (Chapter XXIV) with log_type describing the worker and outcome reflecting the result. Filter the log by worker name to see every run; filter by outcome=failure to see incidents.

Going Live: A Launch Checklist

A new centre opens at 18:00 on a Friday. By 22:00 the room is full. The difference between a smooth launch and a stressful one is two days of methodical setup. Use this chapter as a printable run-sheet.

Two Weeks Before

1. Run the Setup Wizard for the new centre (Chapter XXXV). Confirm organization, currency, time zone, and tax registration.
2. Decide branding: logo, colours, monitor footer text. Push from the organization to ensure consistency.
3. Provision physical hardware: kitchen printer, bar printer, RFID readers, lighting relays, monitor PCs, the wall display itself.
4. Open accounts for staff with the right role; send invites; confirm each can log in and see only what they should.

One Week Before

1. Build the F&B menu — categories, items with photos, modifiers, combos. Pilot a sample order end-to-end.
2. Pair the printers; pulse each lighting relay in test mode; tap-test every RFID reader.
3. Configure tariffs: base rate per table type, peak band, member-tier discounts, grace period.
4. Stand up the Live TV Monitor on its production hardware and verify the footer brand strip, weather, and rotation panel.
5. Configure tax: SST/VAT, e-invoice (if Malaysia), service charge, rounding rule.

Three Days Before

1. Soft launch with friends and family. Run a complete cycle: walk-in → start session → F&B order → split-bill → settle → reprint.
2. Run a battle with three frames; verify Cast URL, scoring panel, leaderboard update.
3. Open a booking, check in, complete the session, observe the booking transition to completed.
4. Sign off staff on Appendix A (keyboard shortcuts) — most useful on day-one.

Opening Day

1. Open shift; record the cash float; verify all printers and relays show green heartbeats.
2. Bring the Live TV Monitor up; confirm the rotation panel shows opening-day promotions.
3. Issue physical RFID cards to early members, link to their accounts, and demonstrate the QR card on the portal.
4. Run the first paid session; pay attention to the proforma vs receipt totals so any tariff misconfiguration is caught immediately.
5. Watch the Operations grid — colours and badges should match expectations against the documented states.

First Week

• Open Revenues each morning. Tender mix, voids, comps, refunds — anything unlike yesterday is worth a look.
• Watch printer last-print timestamps; reset failed prints; check kitchen ticket clarity.
• Hold a 15-minute end-of-shift retro: one thing that worked, one thing to improve.
• Issue a thermal Shift Report at every close; cross-check cash drawer to system before the float is locked away.

Day Thirty

• Run org-wide reconciliation in dry-run; review the largest deltas; apply targeted fixes during a quiet hour.
• Audit member tier coverage — anyone stuck on Free who is clearly active should be invited up.
• Read every Won't Fix bug report from the first month; many become small product wins for month two.

Daily Operations Cheat Sheet

A single page you can pin behind the till. Every recurring action a centre takes in a normal day, in the order it usually happens.

Morning Open

1. Sign in; pick the centre if multi-centre.
2. Open Operations; verify all tables are available.
3. Check the header bell — clear yesterday's outstanding alerts.
4. Open the cash drawer; record the float.
5. Glance at Devices — every printer, monitor, RFID reader, and lighting relay should be green.

During Shift — Tables

1. Customer arrives → tap the table → Start. If member, scan QR or RFID.
2. Pause / resume from the same panel; the meter freezes accordingly.
3. Stop session; the cell turns pending_payment; the operator panel offers Pay now.
4. If the customer wants to split, open Split bill; pick mode (even, itemised, custom, hybrid).
5. Settle the invoice; the cell flips to checkedout briefly, then available.

During Shift — F&B

1. Tap table → POS → pick items, modifiers, quantities → Send to kitchen.
2. Kitchen printer fires the KOT immediately; bar items go to the bar printer.
3. If a customer scans the table QR sticker, their order arrives in the same kitchen queue without operator intervention.
4. Mark cancelled items void; mark service-recovery items comp; refunds require the operator's refund permission and are logged.

During Shift — Members

1. Walk-in member → scan QR or RFID → tier discount applied automatically on the next session.
2. New customer → Become Member from the portal or the operator panel; OTP verifies; QR card issued instantly.
3. Top-up at the cashier → cash, card, or e-wallet → wallet credit posts; receipt printed.
4. Member redeems a stamp-card reward → enter or scan the redemption code at the POS; reward applies as a discount or comp line.

During Shift — Bookings

1. Booking due → operator gets a soft prompt; tap Check In when the member arrives.
2. Booking late → walk-in priority kicks in if the centre is configured to release; otherwise hold.
3. Booking no-show → cron marks expired; deposit handling follows policy.

End of Shift

1. Walk the floor — every table should be available or maintenance; nothing on pending_payment should be left.
2. Print the thermal Shift Report; reconcile cash drawer to system.
3. Hand the report and float into the safe; sign out the till.
4. Sign out of the console; close the browser.

If Something Goes Wrong

1. Read the alert — most "broken" reports are an unread alert.
2. Hard refresh — Ctrl+Shift+R.
3. Sign out / sign in.
4. File a bug from the header — context, screenshot, and recent state are captured automatically.
5. Continue serving customers — kitchen printers and operator POS are designed to keep running through most cloud interruptions.

Member Portal Deep-Dive

Chapter IX introduced the Member Portal at a high level. This chapter goes lower — the surfaces a member actually swipes through, the small UX guarantees that make those surfaces feel like an app rather than a website, and the pieces that matter when something goes wrong.

The Two Generations

The portal runs as a single web surface but is internally two layered generations cooperating. v2 (legacy PWA core) owns bottom navigation, identity, wallet, the classic battle invite flow, sticky CTAs, and push/badge primitives; v3 (modern shell) owns the Me-page swipe state machine, centre-detail full-screen modals, distance/favourites filter chips, debounced search, and the showcard recognition layer. Both share auth, session, and database — users never see the seam, but knowing it exists explains why some screens feel newer.

Bottom Navigation & Tabs

The portal exposes five primary surfaces as a fixed bottom-nav tab bar driven by switchMemberTab(). Tabs are persistent; switching tabs preserves scroll, search, and selected filters per tab. Coupons, tournaments, announcements, and other vertical surfaces are reached through these five — not via additional bottom-nav tabs.

The Me-Page Swipe State Machine

The Me page is horizontally swipable across multiple stat cards (visits, points, stamps, achievements). The state machine guarantees three things:

• Identity preservation — rapid swipes never momentarily render someone else's data.
• Catch-up — if the user swipes faster than data can load, the final card is loaded once, not every intermediate one.
• Tappable pagination dots — dots double as direct-jump targets, not just indicators.

Centre Detail & Quick Actions

Tapping a centre card opens a full-screen detail page. The page is built around four Quick Action chips just below the photo carousel — each is a one-tap operator-free shortcut:

Below the chips: real-time table availability, today's prices, hours, photos, member-only offers, and any battles currently in progress on the floor.

The Become-Member Flow

A guest can become a member from the Centre Detail page in three taps. The flow is engineered to be idempotent — running it twice produces the same result, never two memberships:

Modals on Top of Modals

When a full-screen modal (Book Table, Host Game, Become Member) opens on top of the centre detail page, the portal captures the previous header / nav / body-overflow state on open and restores it exactly on close. This is the difference between a clean modal close and the bug where the page underneath leaks visible navigation.

Sounds, Haptics & Showcards

Sounds (Chapter XXXVI) are bound globally with capture-phase tap delegation, throttled to 60 ms. Showcards — celebratory full-screen recognitions for first-century-break, tier upgrade, championship win — render on top of everything, hold for 4 seconds, and broadcast a low-energy event so the Live TV Monitor can mirror them in the venue.

Mobile App & API Reference

A reference table of the most-used mobile endpoints, the bearer-token model behind them, and the set of native services the Flutter app ships with today — FCM push, location, secure storage, receipt cache, and a WebSocket chat layer.

The Bearer Token

Issued on mobile login as 32-byte random hex stored on members.api_token; lifetime 30 days from issuance, expiry on api_token_expires_at (constant MOBILE_API_TOKEN_EXPIRY_DAYS); sent as Authorization: Bearer <token> on every request; logout sets api_token = NULL; expired tokens are rejected at validation; every login (success/failure) and logout is audited in System Logs.

Endpoint Pattern

The mobile API is a single PHP entry point — /debug/mobile-api/mobile-api.php — that dispatches by an action query parameter. Every call therefore looks like POST /mobile-api.php?action=<name> with the bearer token in the header. The headline actions, grouped by surface:

Additional actions handle bookings, battles, marketplace, and loyalty. The full list lives in the dispatch switch at the top of mobile-api.php and grows release by release.

Idempotency & Retries

The platform's most important write paths — invoice payment, split-bill checkout, table session start, and the client-portal API router — accept an optional client_request_uuid and deduplicate on it (typically against the row being mutated). When the mobile app drops a connection mid-payment and retries, the server returns the prior response instead of double-writing.

CORS & Origins

The mobile API returns the standard CORS headers (Access-Control-Allow-Origin: *, allowed methods GET, POST, OPTIONS, allowed headers Authorization, Content-Type). The bearer token, not the origin, is the security boundary.

Native Capabilities (Flutter App)

The Flutter mobile app ships with the following capabilities, each backed by a dedicated service in lib/services/:

• FCM push notifications — booking reminders, battle invites, payment alerts; FCM token registered on login, unregistered on logout (firebase_service.dart).
• Local notifications — in-app reminder rendering (local_notification_service.dart).
• Location & geocoding — used only to suggest the nearest centre (location_service.dart, geocoding_service.dart).
• Secure storage — bearer token kept in the OS keychain (secure_storage_service.dart).
• WebSocket chat — long-lived chat connection with auto-restart (chat_socket_service.dart, websocket_restart_service.dart).
• Receipt cache — invoices remain readable when offline (receipt_cache_service.dart).
• PDF & print — receipt rendering and pairing to print services (pdf_service.dart, print_service.dart).
• Permissions — runtime permission flow for the above (permission_service.dart).

Rate Limits & Abuse Protection

• Per-IP failure cap — token validation and other public endpoints rate-limit to ~30 failures per minute, returning HTTP 429 thereafter.
• Per-account login attempts capped on a separate counter so attackers spreading across IPs are still stopped.
• Image streams are throttled per IP to discourage menu-photo scraping.

Multi-Centre Operations & Chain Strategy

A single centre operates differently from a chain of fifteen. This chapter is the playbook for the chain — what to centralise, what to delegate, and which features only earn their cost above a certain footprint.

Centralise vs Delegate

Cloning a Centre

For a multi-centre rollout, set up the flagship completely, then use the wizard's clone pattern:

1. Run the Setup Wizard for the new centre; the Organization step is auto-skipped.
2. Pick the flagship as the source for tariffs, F&B menu, and Live Monitor config.
3. Override only the address, table count, and any local quirks.
4. Invite local staff; they inherit the role-based access defined at the organization level.

Cross-Centre Members

A free-tier membership at one centre is portable across the same organization without re-enrolling. Paid tiers are organization-wide unless explicitly scoped. Wallet balances are per-organization (not per-centre) so the member can spend their credit at any sister centre.

Reporting Across Centres

• Organization roll-up — every financial and operations report supports an "all centres" pivot for org-level roles.
• Per-centre breakdown — every roll-up exposes a drill-down by centre, then by employee.
• Like-for-like comparisons — week-over-week, month-over-month, with normalisation for table count and operating hours.
• Scheduled exports — daily P&L by centre to a CFO inbox; respects the recipient's role so they only receive what they are entitled to see.

Chain-Wide Campaigns

Campaigns can target an entire organization, a group of centres, or a single centre. The most common patterns:

• Brand-wide promo — "20% off all weekend across every centre". One campaign, one ROI report.
• Regional weather promo — "Half-price F&B if it rains in this city today". Centre-scoped, time-banded.
• Single-centre re-launch — "Centre A grand re-opening" with a member-tier override valid only in centre A.

Operational Roles in a Chain

Privacy, Data Rights & Compliance

Beyond Chapter XXXVIII (Legal & Consent), this chapter covers what members can ask for, what operators must respond with, and how the platform makes both practical.

Member Data Rights

The platform's policy commits to honouring the standard set of data rights. Where the member can self-serve, the path is in the portal; where it requires support involvement, the operator (or system administrator) handles the request and records the action in System Logs.

What Operators Cannot See

• Member private chats — only metadata (who, when) is logged; bodies are never readable by staff.
• Member passwords — never visible; reset is by the member's own email link.
• Saved payment instruments — held in the gateway, not in the platform.

What the Audit Log Will Show

Every consequential action — a void, a comp, a refund, a tier change, an exported data archive, a data-erasure request — produces a System Logs row (Chapter XXIV) tied to the actor. Members investigating "who edited my profile" get an answer in seconds.

Retention Windows

Subprocessors & Where Data Lives

The platform discloses, in a public sub-processor list, every third-party service (email delivery, payment gateway, push notification, mapping). The list is versioned; material additions trigger a notice to clients before activation.

Data Export Patterns

• One member — support-fulfilled archive of profile, visits, invoices, and marketplace listings.
• One organization — admin-initiated bulk export, including all centres, members, invoices, and audit trails. Delivered to the requesting administrator.
• One centre — same as organization, scoped to a single centre.

Erasure That Survives Audit

An erasure request anonymises the member's profile but preserves invoice history with the personal name replaced by an "Erased Member" placeholder. Tax law requires the invoice itself; privacy law requires the member's identity to disappear. Both are honoured.

Integrations & External Systems

Snooker King is the heart of a centre, not the entire universe. This chapter inventories the external systems the platform speaks to today — payment, tax, mail, push, chat, and native maps.

Payment & Tax

The settlement engine accepts five tender families on every invoice (Chapter XV): cash, card, e-wallet, bank transfer, and member credit / wallet. Each family is implemented as a routing path inside the payment module rather than a third-party SDK; gateway-specific references (auth code, UTR, e-wallet transaction ID) are captured with the payment row so reconciliation can match them later. For tax, LHDN MyInvois (Malaysia) moves invoices through unvalidated → Submitted → Valid (or Invalid), with terminal set {Valid, Invalid, Cancelled} (Chapter XVII; Appendix C). Other jurisdictions use the two-stage stack (service charge → tax) and periodic export. Multiple unvalidated invoices can be merged as a consolidated e-invoice for month-end runs.

Mail, Push & Chat

Transactional mail — password reset, OTP, booking confirmation, bug-report notifications, status changes — is sent via a server-side helper authenticated against an SMTP relay; the helper is the single funnel, so new features add a caller, never a new sender. Push runs through Firebase Cloud Messaging — the Flutter app registers its FCM token on login and unregisters on logout, with background and foreground handlers wired consistently across iOS and Android. Member chat traffic runs over a long-lived WebSocket connection that the mobile app pairs with an auto-restart service so transient disconnects recover without the user noticing.

Native Maps

From the Centre Detail page, Direction hands off to the device's native maps app (Apple Maps on iOS, Google Maps on Android, or the platform default) using the centre's coordinates. The platform never embeds a third-party map iframe, which keeps location queries off the network from any viewer.

Performance, Scale & Reliability

The design choices that let one Snooker King install run a sleepy 8-table hall on a Tuesday afternoon and a packed 60-table championship night on a Saturday — without anyone changing a setting.

Sizing

Hot Paths & Reliability Patterns

The four hot paths each have their own optimisation: the Operations grid refreshes incrementally with polling so only changed cells re-render; the Live TV Monitor uses an independent polling cadence so it never blocks the console; battle scoring writes are tiny and the Cast URL polls a single condensed JSON; the POS print queue absorbs bursts so a stuck printer never blocks the next order. Reliability is built on five patterns: idempotency keys on every state-changing endpoint (duplicate retries never double-write), single-flight on form submits (no double-posts), exponential backoff on outbound deliveries and e-invoice submissions, append-only audit (investigations always have a record), and graceful degradation (kitchen print, RFID scan, lighting stay local-first so cloud outages don't strand the floor).

Backup, Restore & Disaster Recovery

Backups should be invisible until they are the only thing that matters. This chapter is what you do before, during, and after a serious incident.

What Is Backed Up

Restore Patterns

• Point-in-time — full database restore to a moment within the retention window. Used for catastrophic failure only.
• Per-table restore — re-import a single table (e.g. members) from a known-good snapshot. Used for accidental mass deletes.
• Per-record restore — single member, single invoice, single setting. Used for honest operator mistakes; always touched by support, not by a UI button (the UI surface area would be a fraud vector).

Operator Side of DR

• Take photos of any printed receipt that matters; they remain valid even if the cloud is briefly unavailable.
• Keep a paper backup of the day's table allocations during a planned maintenance window.
• Know the support phone number; have it on a sticker behind the operator station.

Internationalization, Currency & Localization

Snooker King runs in any country, every centre with its own currency, language, and tax model. Configuration is per-organization for things that follow the legal entity, per-centre for things that follow the venue.

Currency & Rounding

Currency code is set per organization (MYR, SGD, IDR, AUD, USD, etc.); the display symbol, precision, grouping, and decimal mark follow that code. Rounding is per-organization — round-to-nearest 0.05 is the common cash rule, some operators use 0.10 for low-friction change. Internal storage is canonical 2-decimal DECIMAL; per-minute billing uses 4 decimals internally and rounds at display.

Languages & Time Zones

Three languages ship in the portal sound bus and announcement TTS: English, Bahasa Malaysia, Mandarin; UI translation is config-driven, additional languages add without a release. Per-user preference falls back to centre default, then organization default; receipts and emails honour the recipient's language wherever known. Every centre carries its own IANA time zone, all timestamps stored UTC and converted at display. Date format is per-locale (DD/MM/YYYY for most of the world, YYYY-MM-DD where ISO is preferred); first day of the week is per-locale; reports honour the user's setting.

Tax & Compliance Differences

The tax engine applies a two-stage stack per line — service charge first (on subtotal), then tax (on subtotal + service charge). Both rates are per-centre and stamped on every line for audit. Where a single tax label covers the obligation (SST in Malaysia, VAT in the EU, GST in Australia / Singapore), set the tax stage; jurisdictions needing a third layer (US local sales + city tax, excise / sin tax) apply it as an explicit line item rather than expecting a third tier. Real-time submission integrations run where required (Malaysia LHDN); elsewhere periodic export covers the obligation.

Releases, Versioning & Roadmap

Software that runs a business has to evolve carefully. Snooker King ships small, frequent, transparent changes — and gives operators the tools to know what changed and what to expect next.

Cadence & Reach

Bug fixes deploy continuously as they pass review; feature increments roll out weekly to a staging audience first; operator-visible release notes ship monthly with a summary email to managers; the quarterly roadmap names target windows for the next quarter. A change reaches you in four steps: engineering review & staging tests, soft-launch to a small cohort with telemetry watched, general release with an in-product release-note toast on next sign-in, and a feedback loop where any release-tagged bug short-circuits back to engineering.

Schema & Migration Safety

Schema migrations run on the first request after a release and are idempotent so they never double-apply. Backwards compatibility is default — operator screens never break mid-shift because of a release. Major data migrations go through the reconciliation tools (Chapter XXXVII), in dry-run first.

Reading the Release Notes

Each note is a Headline (one line, plain language), a Why (the operator-visible reason), an Action needed (almost always "none"; when not, listed clearly), and a Where to find more link into the relevant chapter of this guide.

Glossary

The vocabulary of Snooker King, defined for quick reference.

Keyboard Shortcuts

Every shortcut the operations console responds to. Mastering even five of these will measurably speed up a busy shift.

Operations Page (no modal open)

Inside Modals (universal)

POS & F&B

Split-Bill

Start-New-Table Modal

Document Reader (this guide)

Game Format Variants

Snooker King's battle engine supports a deep catalogue of cue-sport formats — each with its own rules, frame mechanics, and scoring panel.

Snooker Family

Pool Family

Carom & Specialty

Common Scoring Controls

Across formats the frame screen exposes consistent keyed buttons (data-verb): Foul (reason picker), Safety, Undo, Concede, Settings (Match Vibe). Format-specific actions — pots, cannons, breaks, frame completion — surface inline on the frame screen rather than as universal verbs.

Invoice & Revenue Status Reference

A complete reference of every invoice and revenue status, what triggers it, and what is or isn't possible from there.

Status Vocabulary

Two columns hold these values on a revenues row: payment_status tracks whether the customer has paid (pending / outstanding / paid / cancelled), and myinvois_status tracks the LHDN compliance lane (unvalidated → Submitted → Valid / Invalid / Cancelled). Reading them in isolation is fine; conflating them is the most common analyst mistake.

Invoice Types

• Individual — single transaction with its own e-invoice submission.
• Consolidated — multiple Unvalidated invoices merged into one submission, typical for batch month-end runs.
• Transaction Slip — short-duration sale recorded without an e-invoice; used where the platform's tax engine treats the amount as below the e-invoice threshold.

Allowed Tenders for Outstanding Payment

Outstanding-balance settlement accepts only the four monetary tenders: Cash (overpay → change), Card (reference / authorisation code), E-wallet (QR or transaction reference), and Bank transfer (UTR / statement reference). Member credit, points, stamps, and tokens apply at original invoice creation, never on outstanding-balance settlement.

Discount, Tax & Pricing Pipeline

When you change one number, knowing the order of operations protects you from surprises.

The Eight-Step Pipeline

1. Subtotal — sum of game charges and POS line items.
2. Manual discount — line-level or invoice-level percentage or amount entered by the operator.
3. Coupon discount — voucher or promotion code redemption.
4. Member discount — tier or campaign discount for the identified member.
5. Service charge — applied to subtotal, before tax (configurable per centre).
6. Tax (SST / VAT) — applied to subtotal plus service charge; granular per item or global.
7. Rounding adjustment — to nearest 0.05 or per-organization rounding rule.
8. Payable amount — what the customer owes after all of the above.

Member Discount Precedence

When a member is identified, the engine resolves which discount rule applies in a strict priority order, lowest-fallback first:

1. Package-specific — for countdown sessions where a package is explicitly selected, a per-package override (if configured for the member's tier) wins.
2. Table-specific — otherwise, a per-table override on the member's tier (filtered by category — countup vs countdown) is used.
3. Common (centre-level) — if neither override applies, the centre-level membership discount on the tier applies.

Overrides are not stacked. A package-level rule fully replaces the table-level one, which fully replaces the centre-level one. Each rule may be percentage or fixed-amount, may carry a min/max-spend gate, and may be restricted to specific weekdays or time bands (overnight ranges supported — the platform handles the wrap-around).

Currency Rounding (per organization)

Rounding is configured at the organization level via rounding_precision (default 0.05 = nearest five cents) and currency_decimals (default 2). The implementation uses PHP's round() with mode half-to-even (banker's rounding) — meaning a midpoint amount snaps to the nearest even increment. For five-cent precision: 1.025 → 1.02, 1.075 → 1.08; for two-decimal cents: 0.125 → 0.12, 0.135 → 0.14. Reward points have their own helper that allows up to three decimals but respects the org's currency_decimals when smaller.

Edge Cases

• Points redemption is not a discount line — it is recorded separately so the books distinguish loyalty cost from price discount.
• Service charge exclusion — some discounts can be configured to exclude service charge, depending on centre policy.
• Tax on service charge — applies in some jurisdictions, not in others; the toggle is per centre.
• Currency precision — most centres use two decimals; some use four for high-volume per-minute billing.
• Banker's rounding — operator expectations sometimes assume half-up; train operators that 1.025 rounds to 1.02 (down to even), not 1.03. Where a regulator requires half-up, raise it with support — it is an organisation setting.
• Grace period — countup sessions don't bill the first n seconds (configurable, 0–300). The grace value is snapshotted at session start so changes don't retroactively affect running tables.
• Idempotency on settle — every payment write carries a client_request_uuid; replays of the same UUID return the original outcome rather than double-charging.

Why the Order Matters

Putting a member discount before service charge produces a different total than putting it after. Snooker King fixes the order so a manager comparing two centres can rely on the numbers being computed the same way. If your venue's accounting requires a different order, raise it with support; it is a centre-level configuration, not a code change.

Operator Recipes

Twenty short, named procedures for the situations that actually come up on a busy floor. Each one is a single paragraph; the full path is in the chapters above.

Tables & Sessions

1 · Start a session for a walk-in. Tap the table → Start. No member needed. The cell turns occupied; the lighting relay fires.

2 · Attach a member after the session has started. Open the table panel → Member → scan QR or type the phone number. Tier discount and stamp accrual apply from the next billing tick onward, not retroactively.

3 · Move a session to a different table. Open the source table panel → Transfer → pick the destination → confirm. The meter does not pause; lighting follows the move automatically.

4 · End a session early without billing. Manager-only. Open the table panel → Comp Session → enter reason. The session closes with a comp invoice; nothing is charged but everything is logged.

5 · Take a table out of service mid-shift. Open the table panel → Maintenance → pick reason and ETA. The Live TV Monitor hides its price; bookings to that table are blocked until you mark it available again.

F&B & POS

6 · Add an F&B order to a running table. Tap the table → POS → search items → modifiers → quantity → Send to kitchen. The KOT prints; lines join the table's open tab.

7 · 86 an item for the rest of the shift. Open Menu Editor → tap the item → Mark unavailable. It disappears from operator POS and the public order page simultaneously; reverse the toggle the next day.

8 · Reprint a kitchen ticket. Open the table tab → find the order line → Reprint KOT. The ticket reprints with a "REPRINT" header so the cook line knows it's not new.

9 · Void an order line. Tap the order line → Void → enter reason. The line stays visible (audit), totals recalculate, and the kitchen gets a "VOID" notice if the order was already submitted.

10 · Comp an item for service recovery. Tap the order line → Comp → enter reason. The line stays on the receipt at full price with a comp adjustment line — customer sees the value, books see the marketing cost.

Settlement & Money

11 · Pay an invoice with two tenders. Open the invoice → Settle → enter cash amount → tap Add tender → enter card amount. The system tracks each part separately on receipt and audit log.

12 · Split a bill four ways equally. Open the invoice → Split bill → mode Even → set 4 payers. Each child invoice shows its share; settle independently. Parent flips to paid only when all four clear.

13 · Split a bill itemised. Same path; pick Itemised. Hand the station to each member in turn (or open the portal split flow), each ticking the lines they consumed.

14 · Refund a paid invoice. Find the invoice → Refund → pick lines and amount → enter reason → confirm. Recorded in System Logs against your account. Card-tender reversal is initiated where the gateway supports it; cash refunds open the drawer.

15 · Apply a coupon at checkout. Open the invoice or split-bill → Coupon → type the code or scan the QR. Eligibility is verified server-side; if the member or time band doesn't qualify, the dialog explains why.

Members

16 · Issue an RFID card to a member. Open the member profile → Cards → tap a card on the configured reader → save. The card resolves to the same account as the QR; either works at the door.

17 · Top up a member wallet. Open the member profile → Top up → enter amount → pick tender → confirm. The deposit posts to the ledger as a positive entry; spend draws against it automatically.

18 · Issue comp credit (service recovery). Manager-only. Open the member profile → Comp credit → enter amount, expiry, and reason. The reason is recorded; the member sees the credit in their portal wallet immediately.

Bookings, Battles & Cast

19 · Check in a booking. Open Operations → Bookings → find the row → Check In. If the booking carried a countdown package, the session auto-starts on the assigned table.

20 · Push a battle to a Cast URL. Open the battle from the Operations grid → Cast → pick layout. The token-gated URL is generated; share with anyone who should watch. Frame updates flow live without any extra operator action.

State Machines & Lifecycles

A flat reference of every state machine the platform exposes, with valid transitions. Use this when you suspect a record has skipped a state.

Table (center_tables.current_status)

Five canonical states are stored; the Operations grid layers extra rendered badges (pending, fnb, rental-active, rental-idle) on top — see Chapter V.

available  ──start session──▶ occupied
occupied   ──session ends──▶  (rendered as pending while invoice unpaid)
*          ──invoice fully paid──▶ checkedout
checkedout ──reset / next assignment──▶ available
available  ──manager marks down──▶ maintenance
available  ──manager hides──▶ inactive
maintenance ──restore──▶ available

Game Session (game_sessions.session_status)

active     ──end button / closeout──▶ checked_out
checked_out ──invoice fully paid──▶ completed
active     ──admin force-end──▶ ended
*          ──manager comp / void──▶ completed (with comp marker)

Game sessions do not carry a paused state — pause semantics live on frame-by-frame turn tracking and on the table's own status, not on the session row. The session row stays active from start to closeout, then transitions through checked_out while waiting for payment, and finally to completed (or ended for force-closes by an administrator).

Invoice (revenues.payment_status)

pending      ──finalise──▶ outstanding
outstanding  ──pay rest──▶ paid
pending      ──pay full at once──▶ paid
*            ──cancel/void with reason──▶ cancelled / voided

There is no "overdue" or "refunded" status on the invoice itself; partial-payment is captured by outstanding_amount while payment_status stays outstanding until fully paid. Refunds are line-level adjustments that reduce outstanding_amount rather than a separate state.

Battle (battles.status)

pending_accept   ──opponent accepts──▶ pending_confirm
pending_confirm  ──host confirms + table allocated──▶ in_progress
in_progress      ──final frame entered──▶ completed
in_progress      ──cron 24h timeout──▶ completed
*                ──party cancels──▶ cancelled
*                ──integrity flag──▶ disputed

Booking (bookings.status)

confirmed   ──party arrives──▶ checked_in
checked_in  ──table closes──▶ completed
confirmed   ──cancel──▶ cancelled
confirmed   ──end-time elapsed without check-in──▶ no_show

Bookings are written directly as confirmed — no "pending confirmation" step. no_show is automatic once utc_end_time passes without check-in.

F&B Order (fnb_orders + items + sessions)

fnb_orders.status:           draft ──Send to kitchen──▶ submitted (KOT printed)
fnb_order_items.payment_st:  unpaid ──invoice settles──▶ paid
                             unpaid ──void w/ reason──▶ cancelled
fnb_sessions.status:         active ──end-of-meal closeout──▶ completed

E-Invoice (revenues.myinvois_status)

unvalidated ──submit to MyInvois──▶ Submitted
Submitted   ──LHDN validates──▶ Valid
Submitted   ──LHDN rejects──▶ Invalid
Valid       ──cancel within 72h window──▶ Cancelled
Submitted   ──submission failure──▶ error

LHDN literal status strings stored verbatim. Terminal set {Valid, Invalid, Cancelled} — platform stops polling on terminal.

Bug Report & Member Tier / Wallet

bug_reports.status: New ──triage──▶ In Progress
                    In Progress ──cannot auto-resolve──▶ Pending Human Decision
                    In Progress ──fix deployed + verified──▶ Resolved
member tier:        upgrade/downgrade ──▶ tier (logged)
member wallet:      top-up ──▶ +ledger entry
                    spend  ──▶ -ledger entry
                    refund of specific deposit ──▶ reverse entry

Feature Reference Index

Concise references for fifteen features and modules that earn a closer look once the basics are running. The italic note at the end of each entry points to the chapter where the feature is set up.

Compliance & Receipts

Official Receipts (OR). A formally numbered receipt is issued for paid invoices once required by tax law; the numbering pattern is OR{YY}{org}{seq} (year, organization, sequence). ORs reprint from the invoice detail panel; the sequence never changes, so the same OR number always refers to the same invoice. See Ch XV.

QR Validity & Rotation. Centre QR tokens (member cards, table F&B stickers, monitor URLs, cast URLs) carry a centre-level validity policy. Rotating a token invalidates old printed materials immediately; revoke from the device panel when a screen leaves the venue or stickers are reprinted. See Ch XXXIX.

Invoice Snapshots. Every issued invoice freezes its rendered HTML at issue time so a reprint months later still matches the original — discount rules can change without rewriting history. Snapshot bytes live in invoice_snapshots, produced lazily on first reprint where a snapshot is missing. See Ch XV, glossary.

E-Invoice (non-Malaysia). The two-stage tax stack (service charge → tax) and per-line stamping is portable; jurisdictions without a real-time API rely on periodic CSV export rather than the LHDN MyInvois integration. Add a third tax label as an explicit line item. See Ch XVII, L.

Operations Surfaces

Unified Payment Layer. Multi-tender splits, idempotency on retry (client_request_uuid), and gateway-reference capture all flow through a single payment module rather than per-tender SDKs — that's why a card+cash+e-wallet split appears on one receipt with one audit row. See Ch XV, App D.

Print Queue Status. Submitted KOTs and invoice prints land in a per-printer queue; jobs retry with exponential backoff and surface in operator notifications when a printer stays offline beyond two retries. The queue absorbs bursts so a stuck printer never blocks the next order. See Ch XIII, XXVI.

Ticketing Kiosk Mode. Per-centre toggle (centers.ticketing_mode) flips the operator station into a one-tap-per-scan flow optimised for kiosk-style entry. Members tap RFID or scan QR; the system resolves and activates the next available table without operator confirmation. See Ch XXI, XXII.

Operations Surfaces (continued)

RFID Scan Mode actions. Each reader can be configured per-centre with a default action (auto-assign-to-next-active-session, open-member-profile, or check-in-pending-booking). Cards link to members from the profile screen; a member may carry multiple cards (primary + backup) and any card is deactivable instantly if lost. See Ch XXII.

Table History module. Beyond the headline report, the module exposes per-session drill-down: opening time, duration, members present, F&B lines, settlements, voids, comps. Filterable by table, employee, member, date range; CSV-exportable. See Ch XXIII.

Configuration Surfaces

Live Monitor JSON config. The config object covers theme preset, layout (grid / list / spotlight), header height, summary-stat selection, footer marquee, and rotation panel. Field-level overrides are accepted; reset-to-default reseeds from the canonical template (Ch VI). See Ch VI.

Custom Notifications & Sounds. Each user mutes information and alerts independently from the avatar menu (state persists per browser). Custom sound effects per centre are configured in the Notifications panel; per-role routing decides whether an alert pushes to email, in-app, or both. See Ch XXXVI.

Keyboard Shortcuts (custom). Appendix A covers the shipped shortcuts; per-role rebinding lives in the user-settings drawer (managers can pin a shift theme + shortcut layout to a shared terminal). Disabled shortcuts don't fire on focused inputs even if the layout would otherwise capture them. See App A, Ch XXX.

Admin & Audit

System Logs custom types. The log_type column is open vocabulary — new modules add their own values without schema migration. The viewer is role-scoped (admin / client / org / manager / operator / member) and the writer strips a deny-list of sensitive keys before persistence. See Ch XXIV.

Social Moderation. The operator-side social console exposes flagged listings, reported chat threads, and a one-tap remove + reason for marketplace listings. Members never see operator-side comments; status-change rows are immutable and join the System Log audit trail. See Ch XXVIII, XXXIV.

Admin Utilities. Beyond the four reconciliation tools (Ch XXXVII), bearer-token-guarded admin endpoints handle bulk re-tokenisation, organisation-wide tariff broadcasts, schema validation, and one-shot data corrections. All run dry-run by default and write a System Log row on apply. See Ch XXXVII.