TPCompanion

TPCompanion is a production-oriented business operations platform developed as a companion layer for the Shortcuts POS environment used in salon, spa, and retail operations. Rather than replacing the existing POS system, TPCompanion extends it with a modern React interface and a locally running Node.js/Express backend connected directly to Microsoft SQL Server. The backend operates as a Windows Service, allowing APIs, background schedulers, messaging workflows, reporting, Qatar GTA processing, application updates, and AI services to continue running independently of the frontend. The platform provides a dedicated analytics layer over existing Shortcuts data, covering revenue, appointments, products, staff, clients, business summaries, and custom date-range analysis. It also includes a configurable commission engine supporting percentage-based, flat/jump-slab, progressive structures, employee-specific rules, item and category filtering, company filtering, stylist/operator allocation, and commission summaries. Appointment data is reused across analytics and automation workflows, supporting reminders, confirmations, pre-arrival communication, no-show workflows, and related operational processes. A background messaging system automates customer communication through SMS and WhatsApp, covering appointment reminders, confirmations, pre-arrival messages, thank-you and receipt follow-ups, new-client communication, referrals, birthdays, series and gift-certificate expiry, miss-you campaigns, no-show communication, class-related workflows, and promotions. TPCompanion also provides scheduled automated reporting, allowing selected business reports to be generated and delivered without requiring the user to keep the application open. The platform includes a dedicated Qatar GTA electronic invoicing workflow covering device onboarding, certificate lifecycle management, supplier configuration, invoice and credit-note processing, UBL 2.1 generation, document validation and signing, submission, response processing, status tracking, and DCV/PDH document-chain management. Transaction control is used around relevant chain-state operations so failed processing does not leave local invoice state inconsistent. The application is packaged for Windows using @yao-pkg/pkg, hosted through WinSW as a Windows Service, distributed through an Inno Setup installer, and supported by an application-level update mechanism backed by a controlled release repository. Most recently, TPCompanion was extended with a locally hosted AI assistant combining two distinct capabilities: controlled business-data access and Shortcuts Fusion knowledge retrieval. Users interact through a free-text conversational interface, while the backend separates natural-language requests from actual business operations. Business requests are routed through capability discovery, eligibility checks, validation, and deterministic read-only tools rather than allowing the language model to generate unrestricted SQL against the production database. Supported capabilities include business summaries, revenue, appointments, clients, staff, inventory, commissions, cash movements, gift-certificate liability, refunds and voids, stock movement, discounts, taxation, and report-derived operations. The knowledge side uses Shortcuts Fusion retrieval with document synchronization, chunking, embeddings, semantic search, confidence evaluation, and fail-closed handling for unsupported answers. The AI runtime uses Ollama with Qwen3 for local inference and nomic-embed-text for embedding-based retrieval, keeping the AI workload within the local application environment rather than depending on a hosted general-purpose AI API. This architecture provides natural-language access while keeping business-data execution deterministic, validated, and application-controlled.