SaleFlex.PyPOS Documentation Complete user and developer guide for the SaleFlex.PyPOS point-of-sale application.
Touch UI reference images live under static_files/images/README.mdFirst Login tour). Filenames include:
sample_login.jpg, sample_main_menu.jpg, sample_sale_form.jpg, sample_sale_func_dual_functions_form.jpg, sample_sale_payment_form.jpg, sample_sale_customer_form.jpg, sample_closure_form.jpg, sample_closure_detail_form.jpg, sample_closure_receipts_form.jpg, sample_closure_receipt_details_form.jpg, sample_settings_form.jpg, sample_cashier_form.jpg, sample_cashier_add_form.jpg, sample_product_form.jpg, sample_product_detail_form.jpg, sample_customer_list_form.jpg, sample_customer_detail_form.jpg, sample_warehouse_list_form.jpg, sample_warehouse_stock_in_form.jpg, sample_warehouse_adjustment_form.jpg, sample_warehouse_history_form.jpg.
In Markdown under docs/, reference them as ../static_files/images/<filename>.
#
Document
Summary
1
Introduction Overview, key features, application screens, default credentials
2
System Requirements Hardware, software, and supported database backends
3
Installation Guide Step-by-step setup (Python, venv, pip, first run)
4
Configuration settings.toml + settings hub + POS / loyalty forms in DB
5
First Login Default credentials, role differences, automatic document recovery
6
Virtual Keyboard Configuration DB-driven keyboard themes, enable/disable, custom themes
Part 2 — Daily Operations
#
Document
Summary
10
Sale Transactions NumPad modes, adding products, COUPON / applied coupon ids, CampaignUsageLimitsCAMPAIGNCampaignAuditServiceBONUS loyalty redemption on PAYMENT (points → LOYALTY discount), Item Actions (REPEAT / DELETE); PAYMENT form AMOUNTSTABLE row-height layout
11
Suspend and Resume Sales SUSPEND button, parked carts, market mode, Suspended Sales list
12
Cancellations Line cancellation (DELETE), full document cancellation (CANCEL)
13
End-of-Day Closure Authorization, aggregation flow, sequence management
14
Cashier Management Create/edit cashiers, role permissions, ADD NEW CASHIER
15
Product Management Product List search, Product Detail tabbed dialog
16
Inventory Management Stock levels, goods receipt, adjustments, movement history, negative stock policy
17
Customer Management Customer List search, ADD new customer, Customer Detail tabbed dialog (info, activity, point movements ledger), Walk-in Customer, SALE form CUSTOMER dual button, sale-assignment workflow
41
Loyalty Programs Local loyalty: policy / earn-rule / redemption models, phone_normalized, enrollment; LoyaltyRedemptionServiceBONUS ; LoyaltyEarnServiceearn_eligible_payment_typesEARNEDREDEEMEDTransactionLoyaltyPoint movements grid (CUSTOMER_LOYALTY_POINTS_GRID), closure receipt detail loyalty summary; not yet: void/refund/exchange point clawback automation
42
Customer Segmentation CustomerSegmentService: auto CustomerSegmentMember from criteria_json, VIP via preferences_json, sync on completed sale and customer save, marketing_profile with loyalty tier
43
Campaign & Promotions Cart snapshot, ActiveCampaignCacheCampaignServiceCampaignUsageLimitsCampaignAuditServicedistinct_applied_campaign_countCouponActivationServiceapply_campaignadministrator CAMPAIGN_LIST / CAMPAIGN_DETAIL UI
Part 3 — Architecture (Developer)
#
Document
Summary
20
Project Structure Folder layout, class inheritance chain, startup sequence, design patterns
21
Database Models Overview 100+ models organized by domain, temp/permanent split, country-specific templates
22
Dynamic Forms System DB-driven UI forms, Panel controls, CheckBox, form transitions, generic save pattern, Campaign management (administrators)
23
UI Controls Catalog Custom Qt widgets (Button, TextBox, NumPad, SaleList, TabControl, …); AmountTable viewport row-height sync
24
Event System EventHandler, event_distributor(), all event categories with handler mapping (incl. APPLY_COUPON
25
Service Layer VatService, SaleService, PaymentService (net due, discount copy, campaign audit), LoyaltyEarnService, LoyaltyRedemptionService, LoyaltyService, CustomerSegmentService, campaign/ActiveCampaignCachedistinct_applied_campaign_count
26
Document Management Transaction lifecycle, suspend/resume, line cancellation, payment flow
27
Data Caching pos_data / product_data caches, ActiveCampaignCache
Part 4 — Operations & Maintenance
#
Document
Summary
30
Peripherals Cash drawer, receipt printer, line display, scanner, scale — OPOS-style stubs
31
Central Logging core/logger.py configuration, log format, usage patterns
32
Exception Handling SaleFlexError hierarchy, usage patterns, design guidelines
33
Database Initialization Seed data functions, initialization order, adding new seed data
34
Startup Entry Point Working-directory fix, Python version guard, single-instance lock, post-init_db idempotent UI patches (e.g. customer Point movements tab, SALE COUPON button, demo coupon seed, ensure_campaign_management_formsrefresh_active_campaign_cache()
35
Troubleshooting Common issues, database problems, closure issues, sale issues
36
Support and Resources GitHub, issue tracker, donations, license
#
Document
Summary
40
Integration Layer SaleFlex.GATE hub, third-party ERP/payment/campaign connectors, offline outbox, SyncWorker, notification system
Topic
Document
First time setup
Installation Guide -> Configuration -> First Login
Processing a sale
Sale Transactions
Applying item discounts or markups (%, amount)
Sale Transactions → Item Discounts and Markups
End-of-day
End-of-Day Closure
Cashier accounts
Cashier Management
Stock management
Inventory Management
Customer management / sale assignment
Customer Management
Loyalty (earn/redeem, customer point audit, closure receipt summary)
Loyalty Programs
Marketing segments (auto rules)
Customer Segmentation
Campaigns & coupons (cart snapshot, ActiveCampaignCacheCAMPAIGNCampaignService, CampaignAuditService / distinct_applied_campaign_count, CouponActivationService, apply_campaign, admin UI via Settings → CAMPAIGN SETTINGS )
Campaign & Promotions · Dynamic Forms — Campaign management
UI customization
Dynamic Forms System
Database schema
Database Models Overview
Event wiring
Event System
Logging setup
Central Logging
Error handling
Exception Handling
Hardware devices
Peripherals
Startup guards
Startup Entry Point
Common errors
Troubleshooting
GATE & external systems
Integration Layer
Reference & campaign caches (pos_data, product_data, ActiveCampaignCache
Data Caching
Last Updated: 2026-04-11
Version: 1.0.0b7
License: MIT