Billiards Club CRM Solution

Overview

Modern billiards halls are forced to operate on fragmented tools: a POS system, a time clock, a few Excel files for inventory and payroll, and manually controlled lights and air conditioning. The result is difficult revenue reconciliation, unexplained inventory losses, and electricity wasted on unoccupied tables.

Billiards Club CRM Solution consolidates all operations—from staff check-in to end-of-day closing—into a single system installed on-premises at the venue. All core business processes run 100% on the local LAN, so sales continue normally even when the internet goes down. This solution is designed for chain owners and facility managers who need tight control over three critical axes: money, goods, and people.

Multi-branch architecture is built in from the start: one owner account supervises multiple locations, with role-based permissions down to individual job titles. Every sensitive operation is tracked with before-and-after audit logs.

Detailed Features

Table Management & Billing

Real-time table layout updates, walk-in table setup in under 30 seconds, pause/resume functionality, table transfers and merges. Hourly rates are configurable by time period (regular hours, peak hours, weekends, tournament tables), with package deal options available.

POS Sales & Kitchen

Order from the table or mobile device, push preparation tickets to kitchen/bar displays and zone-specific thermal printers. Four-way bill splitting, cash and VietQR payments, with mandatory approval workflows and reason codes for refunds and order cancellations.

Promotions, Vouchers & Loyalty

Student discounts with photo verification, "come again" QR vouchers printed with receipts featuring anti-abuse rules, points earned based on actual play time and redeemable as direct bill discounts. 360° customer profiles with encrypted and masked personal information.

QR Code Self-Ordering

Each table has its own QR code. Customers scan to view the menu and place orders directly from their phones—no app installation required. Orders require staff approval before being added to the bill, with location verification to prevent ordering from outside the venue.

Inventory, Cost & Expenses

Recipe-based inventory deduction, immutable cost-of-goods at the moment of sale, inventory audits with variance analysis against allowable thresholds. Operational expense claims require receipt photos, with spending limits and shift-based cash reconciliation.

Staff: Shifts, Time Tracking & Payroll

Shift scheduling using shared templates with real-time understaffing alerts. Clock-in requires GPS location within venue radius plus selfie photo, with automatic shift closure for forgotten clock-outs. Payroll calculated from approved time records, with payslips issued to staff including a 24-hour confirmation/dispute window. Complete leave requests, overtime, tardiness, shift swaps, and multi-location work—all with approval workflows.

Task Management & Training

Shift-based task assignment in Kanban format: assign → accept → execute (with photo attachment) → verify. Tasks can be assigned to individuals or groups by job title and location. Training library and policies must be reviewed before clock-in privileges are granted.

IoT Device Control

Opening a table automatically turns on lights and AC; closing turns them off—no more equipment running for empty tables. The system uses ESP32 with Tasmota firmware communicating via internal MQTT, with retry queues and state mismatch detection. Includes maintenance alerts based on cumulative play hours per table.

Counter Devices

Connect 80mm thermal printers (cashier/kitchen/bar), RF-controlled table lights, and member fingerprint readers through a counter PC agent, with command logs and per-device test buttons.

Staff Mobile App

Dedicated mobile app for clock-in, shift viewing, task acceptance, table ordering and payment, payslip and penalty viewing, internal chat, and push notifications.

Reports & Monitoring

Revenue across 9 categories, profit/loss reports, table utilization rates, cost of goods, staff efficiency, shrinkage, and promotion effectiveness. Includes audit logs showing who did what, changing from which value to which value.

Technical Specifications

Specification	Value
Architecture	Modular monolith, multi-tenant/multi-branch
Backend	NestJS 11 · TypeScript · Prisma ORM
Database	PostgreSQL 15 · Redis 7
Web Frontend	React 19 · Vite · Ant Design 6 · TypeScript strict
Mobile App	React Native (Expo) — staff app & customer app
Real-time	Socket.io — 19+ real-time events
Queue & Background Tasks	BullMQ
IoT Protocol	MQTT (Mosquitto) — ESP32 + Tasmota firmware
File Storage	MinIO (S3-compatible)
Deployment	Docker Compose · Nginx · Ubuntu 22.04 · Mini PC on-site
Data Scale	109 tables · ~716 API endpoints · 281 web screens
Offline Mode	POS, table billing, IoT, chat run 100% on LAN
Security	2-tier RBAC · 2FA TOTP/Email · QR login · WebAuthn · ID card encryption AES-256-GCM · full audit logs
Reference Scale	1 location: 31 tables · ~30 staff · 47 IoT devices
Testing	534 automated test files (unit · integration · E2E)