SaleFlex.PyPOS

Current Status: Beta v1.0.0b5 - Active Development Core POS functionality operational. See roadmap for upcoming features.

Watch Demo | Documentation | Quick Start

Touch Screen Point-of-Sale Application

SaleFlex.PyPOS is a modern, Python-based point-of-sale (POS) system designed for retail businesses, restaurants, and service-oriented establishments. Built with PySide6 (Qt framework), it offers a touch-optimized interface with cross-platform compatibility and robust database support.

Current Version Demo: 1.0.0b3

Key Features

SaleFlex.PyPOS POS system is designed to streamline the sales process and improve efficiency with these capabilities:

Multi-Payment Processing: Accept cash, credit cards, debit cards, and mobile payments
Receipt & Invoice Generation: Automated transaction documentation with ESC/P printer support
Inventory Management: Real-time stock tracking with low-stock alerts
Customer Management: Store customer information, preferences, and purchase history
Analytics & Reporting: Comprehensive sales, inventory, and customer behavior analytics
System Integration: Connect with accounting software, warehouse management, and ERP systems
️Returns & Exchanges: Handle product returns and exchanges efficiently
Employee Management: Track employee time, attendance, and performance
Cashier Management: Role-based cashier account management with dynamic combobox selection. Admin users can view and edit all cashier accounts and create new cashier accounts directly from the Cashier Management form via the ADD NEW CASHIER button (admin-only, hidden for non-admin users). Non-admin cashiers can update only their own password. Field-level read-only protection enforced at the form layer (is_administrator flag). New cashier entry uses in-place form manipulation (no full redraw) for seamless UX
Campaign & Promotion Management: Flexible promotional campaigns with time-based, product-specific, and basket discounts
Loyalty Programs: Tiered membership rewards system with points earning, redemption, and customer segmentation
Country-Specific Closure Templates: Flexible template system for country-specific closure data (E-Fatura for Turkey, state tax for USA, VAT reporting for EU, etc.) stored as JSON templates in static_files/closures/ directory
Region Support: CountryRegion model tracks sub-country regions (states, provinces, special economic zones) with ISO 3166-2 compliant fields. Includes 80+ pre-populated regions for region-specific closure templates and compliance
Active Closure Management: Session-based closure tracking system that automatically loads open closures at startup and manages closure lifecycle (open → active → closed). Closure data is maintained in memory during operations and saved to database when closed
Document Management System: Complete transaction lifecycle management with temporary models during processing and automatic conversion to permanent models upon completion. Automatically updates document data during sales operations (PLU and department sales). Supports per-line REPEAT (clone line, save new DB record, update totals) and DELETE (soft-cancel line, mark is_cancel=True in DB, recalculate totals) actions from the sale list item popup; if the last active line is deleted the document is automatically cancelled and reset. CANCEL button: Red CANCEL button on the SALE form (below the denomination buttons, same row as PLU/X/SUSPEND) immediately voids the entire active transaction — sets transaction_status=CANCELLED, is_cancel=True, cancel_reason="Canceled by cashier: {username}", copies to permanent models, shows a confirmation dialog with receipt/closure number and total, then opens a new draft. If no open document exists, an info dialog is shown instead. Market suspend: SUSPEND saves the cart as pending, then creates a new draft (suspended rows no longer steal the receipt slot in create_empty_document). SUSPENDED_SALES_MARKET lists suspended receipts (hidden head id + columns); ACTIVATE (RESUME_SALE) clears is_pending, loads lines on SALE, and abandons any empty draft left open first. Closure: TransactionHead rows with is_pending=True and open TransactionHeadTemp suspended carts for the closure period are excluded from aggregated sales totals; their count is stored on Closure.suspended_transaction_count. Automatic recovery of incomplete non-pending transactions at startup; restores sale UI when re-entering SALE with an ACTIVE document
Auto-Save Functionality: Automatic database persistence system using descriptor pattern and wrapper classes. Model instances and dictionaries are automatically saved to the database when attributes are modified, ensuring data integrity and reducing manual save operations. Supports nested model wrapping and skip flags for batch operations
Peripherals (OPOS-style): pos/peripherals/ defines cash drawer, receipt printer, line display, scanner, scale, customer display, and remote order display classes. Wired behaviours on SALE (log-only until drivers exist): completed sale → receipt text + drawer open; CASH with no document → drawer open; selling and payment steps → three-line customer display updates. See docs/18-peripherals.md
Central Logging: Configurable logging via core/logger.py with a single saleflex root logger. Log level (DEBUG/INFO/WARNING/ERROR/CRITICAL), console output, and file output are controlled from the [logging] section in settings.toml. All modules use get_logger(__name__) for consistent, hierarchical log records
Centralized Exception Handling: Typed exception hierarchy rooted at SaleFlexError (pos/exceptions.py). Domain-specific subclasses (PaymentError, FiscalDeviceError, GATEConnectionError, TaxCalculationError, DatabaseError, etc.) replace bare Exception raises throughout the codebase. All exceptions are chained with raise ... from e to preserve the full traceback
Optimized Performance: In-memory caching of reference data (pos_data) and product data (product_data) minimizes disk I/O, extending disk life for POS devices with limited write cycles. All product lookups, currency calculations, VAT rate lookups, button rendering, and sale operations use cached data instead of database queries
Smart NumPad (4 Modes): The SALE form NumPad supports four operating modes: (1) Barcode/PLU lookup — type a barcode or product code and press ENTER to find and sell the product (searches ProductBarcode then Product.code); (2) Inline quantity — type a quantity then press a PLU product button to sell that many units; (3) X (Quantity Multiplier) button — pre-set the quantity before a barcode scan; status bar shows the active multiplier (x1, x3, etc.); (4) Payment amount — enter the tendered amount in minor currency units (e.g. 10000 → £100.00) then press CASH or CREDIT CARD. PLU inquiry (separate green PLU button beside X) shows price and per-warehouse stock from cached WarehouseProductStock without selling — either enter the code then PLU, or press PLU first then enter the code and ENTER

Architecture Overview

SaleFlex.PyPOS follows a layered architecture pattern with clear separation of concerns:

Application Layer (pos/manager/application.py): Main application class implementing Singleton pattern, combining CurrentStatus, CurrentData, and EventHandler
Business Logic Layer (pos/service/): Service classes (VatService, SaleService, PaymentService) for centralized business operations
Peripherals Layer (pos/peripherals/): OPOS-style device abstractions (cash drawer, receipt printer, line display, scanner, scale, customer display, remote order display). Current implementation is log-only (no device probing); see docs/18-peripherals.md
Event Handling Layer (pos/manager/event/): 9 specialized event handler classes for modular event processing. Event handler methods use _event suffix naming convention (e.g., _sales_form_event, _closure_event) to distinguish them from properties
Data Access Layer (data_layer/model/): 98+ SQLAlchemy models with CRUD operations and auto-save functionality
UI Layer (user_interface/): PySide6-based UI components with dynamic form rendering
Caching Layer (pos/manager/cache_manager.py): In-memory caching for reference and product data
Logging (core/logger.py): Central logging module; all components use get_logger(__name__) with configuration from settings.toml [logging]
Exception Layer (pos/exceptions.py): Typed exception hierarchy (SaleFlexError root) with domain subclasses for payment, hardware, tax, database, document, configuration, and authentication errors

┌─────────────────────────────────────────┐
│          UI Layer (PySide6)             │
├─────────────────────────────────────────┤
│    Event Handlers (9 modules)           │
├─────────────────────────────────────────┤
│   Business Logic (Service Layer)        │
├─────────────────────────────────────────┤
│      Data Access Layer (ORM)            │
├─────────────────────────────────────────┤
│    Cache Layer (pos_data/product_data)  │
├─────────────────────────────────────────┤
│         Database (SQLite/PG)            │
└─────────────────────────────────────────┘

Project Structure

SaleFlex.PyPOS/
├── saleflex.py              # Main application entry point
├── requirements.txt         # Python dependencies
├── settings.toml           # Application configuration
├── db.sqlite3              # Default SQLite database
├── PyPOS_GUIDE.md          # Quick reference guide (redirects to docs/)
│
├── docs/                   # Comprehensive documentation
│   ├── README.md           # Documentation index
│   └── *.md                # Topic-specific documentation files
│
├── data_layer/             # Database & ORM Layer
│   ├── engine.py           # Database engine configuration
│   ├── db_initializer.py   # Database initialization
│   ├── db_manager.py       # Database management utilities
│   ├── db_utils.py         # Database helper functions
│   │
│   ├── auto_save/          # Auto-save functionality
│   │   ├── auto_save_model.py
│   │   ├── auto_save_dict.py
│   │   └── auto_save_descriptor.py
│   │
│   ├── db_init_data/       # Initial data seeding
│   │   ├── cashier.py
│   │   ├── country.py
│   │   ├── currency.py
│   │   ├── product.py
│   │   └── ...             # Other initialization modules
│   │
│   ├── enums/              # Enumeration definitions
│   │   ├── control_name.py
│   │   ├── control_type.py
│   │   ├── custom_control_type_name.py
│   │   ├── event_name.py
│   │   └── form_name.py
│   │
│   └── model/              # Data models and CRUD operations
│       ├── crud_model.py   # Base CRUD operations
│       ├── mixins.py       # Model mixins
│       └── definition/     # Entity definitions (98+ models)
│
├── user_interface/         # UI Components
│   ├── window/             # Application windows and dialogs
│   │   ├── base_window.py
│   │   └── dynamic_dialog.py
│   │
│   ├── control/            # Custom UI controls
│   │   ├── button.py
│   │   ├── textbox.py
│   │   ├── checkbox.py
│   │   ├── combobox.py
│   │   ├── label.py
│   │   ├── datagrid.py
│   │   ├── panel.py        # Panel control with scrollbar support
│   │   ├── toolbar.py
│   │   ├── statusbar.py
│   │   ├── amount_table/   # Amount table control
│   │   ├── numpad/         # Numeric pad control
│   │   ├── payment_list/   # Payment list control
│   │   ├── sale_list/      # Sale list control
│   │   ├── transaction_status/  # Transaction status display
│   │   └── virtual_keyboard/    # Virtual keyboard component
│   │
│   ├── form/               # Form definitions
│   │   ├── about_form.py
│   │   └── message_form.py
│   │
│   ├── render/             # Dynamic form rendering (database-driven)
│   │   └── dynamic_renderer.py
│   │
│   └── manager/            # UI management logic
│       └── interface.py
│
├── pos/                    # Core POS Business Logic
│   ├── exceptions.py       # Centralized exception hierarchy (SaleFlexError root)
│   ├── data/               # POS-specific data types
│   │   ├── document_type.py
│   │   ├── document_state.py
│   │   ├── payment_type.py
│   │   └── discount_type.py
│   │
│   ├── hardware/           # Hardware integration
│   │   └── device_info.py  # Device information detection
│   │
│   ├── peripherals/        # OPOS-style peripherals (log-only until drivers are added)
│   │   ├── cash_drawer.py
│   │   ├── pos_printer.py
│   │   ├── line_display.py
│   │   ├── hooks.py        # SALE form line-display sync helpers
│   │   └── ...             # scanner, scale, customer_display, remote_order_display stubs
│   │
│   ├── service/            # Business logic services
│   │   ├── vat_service.py     # VAT calculation service
│   │   ├── sale_service.py    # Sale processing service
│   │   └── payment_service.py # Payment processing service
│   │
│   └── manager/            # Application management
│       ├── application.py  # Main application class
│       ├── current_data.py # Current session data
│       ├── current_status.py
│       ├── cache_manager.py      # Data caching
│       ├── closure_manager.py    # Closure management
│       ├── document_manager.py   # Document lifecycle
│       ├── event_handler.py      # Event handling (combines all event handlers)
│       └── event/          # Event handlers (9 specialized event handler classes)
│           ├── general.py        # GeneralEvent: Login, logout, exit, navigation
│           ├── sale.py           # SaleEvent: Sales transaction and product events
│           ├── payment.py        # PaymentEvent: Payment processing events
│           ├── closure.py        # ClosureEvent: End-of-day closure operations
│           ├── configuration.py  # ConfigurationEvent: Settings and configuration
│           ├── service.py        # ServiceEvent: Service-related operations
│           ├── report.py         # ReportEvent: Report generation and viewing
│           ├── hardware.py       # HardwareEvent: Hardware device operations
│           └── warehouse.py      # WarehouseEvent: Warehouse and inventory operations
│
├── core/                    # Core utilities
│   └── logger.py           # Central logging (get_logger, config via settings.toml [logging])
│
├── settings/               # Configuration management
│   └── settings.py
│
├── static_files/           # Static assets
│   ├── closures/           # Country-specific closure templates
│   │   ├── tr.json
│   │   ├── usa.json
│   │   ├── usa_ca.json
│   │   └── ...
│   └── images/             # Image assets
│       ├── saleflex.ico
│       └── ...

Business Applications

SaleFlex.PyPOS is designed to meet the diverse needs of various business types:

Retail Stores: Complete retail management with inventory, customer tracking, and sales analytics
Fast Food Restaurants: Quick service restaurant operations with order management
Chain Restaurants: Multi-location restaurant management with centralized control
Service Businesses: Various service-oriented establishments with customizable workflows

SaleFlex.GATE Integration

SaleFlex.PyPOS integrates seamlessly with SaleFlex.GATE - a Django-based centralized management system:

Centralized Management: Monitor and manage multiple POS systems from one dashboard
Cloud-Based Access: Remote control and monitoring for business owners and managers
ERP Integration: Seamless data synchronization with existing ERP systems
Scalable Architecture: Support growing businesses with multiple locations
Secure Data Flow: Robust API-based communication between POS terminals and backend

System Requirements

Hardware Requirements

Devices: Linux/Windows supported touch screen devices
Displays: Single or dual display configurations
Printers: ESC/P compatible receipt printers
Scanners: 2D and 3D barcode readers
Scales: Weighing scales for retail environments

Software Requirements

Python: 3.13 or higher (recommended)
PySide6: 6.11.0 (Qt-based GUI framework)
SQLAlchemy: 2.0.48 (ORM for database operations)
Requests: 2.33.0 (HTTP client for API communications)

Note on Python 3.14: Python 3.14 can be used to run the application, but SQLAlchemy does not yet officially support Python 3.14. You may encounter unexpected issues or incompatibilities. It is recommended to use Python 3.13 until official SQLAlchemy support for Python 3.14 is confirmed.

Supported Database Engines

SQLite (default, included)
PostgreSQL
MySQL
Oracle
Microsoft SQL Server
Firebird
Sybase

Quick Start

git clone https://github.com/SaleFlex/SaleFlex.PyPOS.git
cd SaleFlex.PyPOS
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate.bat
pip install -r requirements.txt
python saleflex.py

Default credentials: admin / admin (administrator) · jdoe / 1234 (standard cashier)

Installation & Setup

Prerequisites

Install Python 3.13 or higher (Python 3.14 is not yet officially supported by SQLAlchemy — use 3.13 for best compatibility)
Ensure pip is installed and up to date

Installation Steps

Clone or Download the SaleFlex.PyPOS project:

git clone https://github.com/SaleFlex/SaleFlex.PyPOS.git
cd SaleFlex.PyPOS

Create Virtual Environment:
```
python3 -m venv venv
```

Activate Virtual Environment:

Windows:

venv\Scripts\activate.bat

macOS/Linux:

source venv/bin/activate

Install Dependencies:
```
pip install -r requirements.txt
```
Run the Application:
```
python saleflex.py
```

First Login

After running the application, you will see the login screen:

Default Login Credentials:

Username	Password	Role
`admin`	`admin`	Administrator — can edit all cashier accounts
`jdoe`	`1234`	Standard cashier — can update own password only

After successful login, you will be redirected to the main menu:

If you select "SALES", you will see a form as shown below:

Configuration

Edit settings.toml to configure database connections and basic application settings
Note: Many POS settings (hardware ports, display settings, backend connections) are now managed through the database (PosSettings model) and can be configured via the application UI or API
The application uses SQLite by default, stored in db.sqlite3
Device information (serial number, OS) is automatically detected and stored on first initialization

Database Models Overview

The application includes 98+ database models organized into logical categories:

Core System: Cashier, Store, Table, Country, CountryRegion, City, District
Currency & Payment: Currency, CurrencyTable, PaymentType, ClosureCurrency
Product Management: Product, ProductVariant, ProductAttribute, ProductBarcode, ProductUnit, ProductManufacturer, DepartmentMainGroup, DepartmentSubGroup
Transaction Models: TransactionHead/HeadTemp, TransactionProduct/ProductTemp, TransactionPayment/PaymentTemp, TransactionDiscount/DiscountTemp, TransactionTax/TaxTemp, TransactionTip/TipTemp, TransactionDepartment/DepartmentTemp, TransactionDelivery/DeliveryTemp, TransactionNote/NoteTemp, TransactionRefund/RefundTemp, TransactionSurcharge/SurchargeTemp, TransactionFiscal/FiscalTemp, TransactionKitchenOrder/KitchenOrderTemp, TransactionLoyalty/LoyaltyTemp, TransactionChange/ChangeTemp, TransactionVoid, TransactionLog, TransactionSequence, TransactionDocumentType, TransactionDiscountType, TransactionStatus
Warehouse Management: Warehouse, WarehouseLocation, WarehouseProductStock, WarehouseStockMovement, WarehouseStockAdjustment
Customer Management: Customer, CustomerSegment, CustomerSegmentMember
Campaign & Promotion: CampaignType, Campaign, CampaignRule, CampaignProduct, CampaignUsage, Coupon, CouponUsage
Loyalty Programs: LoyaltyProgram, LoyaltyTier, CustomerLoyalty, LoyaltyPointTransaction
Cashier Performance: CashierWorkSession, CashierWorkBreak, CashierPerformanceMetrics, CashierPerformanceTarget, CashierTransactionMetrics
Closure & Reporting: Closure, ClosureCashierSummary, ClosureCurrency, ClosureDepartmentSummary, ClosureDiscountSummary, ClosureDocumentTypeSummary, ClosurePaymentTypeSummary, ClosureTipSummary, ClosureVATSummary, ClosureCountrySpecific
Form & UI: Form, FormControl (supports parent-child relationships for Panel controls with generic model form pattern), PosSettings, PosVirtualKeyboard, ReceiptHeader, ReceiptFooter, LabelValue

All models support:

UUID Primary Keys: Unique identifiers for all records
CRUD Operations: Base CRUD class provides create, read, update, delete operations
Audit Trails: Created/updated timestamps and user tracking
Soft Delete: Records can be marked as deleted without physical removal
Auto-Save: Automatic database persistence when attributes are modified

Development Roadmap

Core Infrastructure

Project Structure - Basic application framework
Database Layer - SQLAlchemy ORM integration with 98+ models
Database Structure - POS data layer structure with comprehensive model definitions
UI Foundation - PySide6 interface framework
Auto-Save System - Automatic database persistence with descriptor pattern
Configuration Management - Advanced settings system
Central Logging - Configurable logging via core/logger.py; level, console, and file output driven by settings.toml [logging]; application-wide use of get_logger(__name__)
Centralized Exception Handling - Typed SaleFlexError hierarchy in pos/exceptions.py; domain-specific subclasses for payment, hardware, tax, database, document, configuration, and authentication errors; all exceptions chained with raise ... from e

POS Core Modules

Hardware Integration

User Interface

Business Features

Warehouse & Inventory Management

Sector-Specific Features

Integration & Connectivity

Security & Authentication

User Authentication System - Multi-level user access control
Data Encryption - Secure data storage and transmission
Audit Trail - Comprehensive transaction logging
Role-Based Access Control - Granular permission management
PCI DSS Compliance - Payment industry security standards

Performance & Scalability

In-Memory Data Caching - Reference data (pos_data) and product data (product_data) loaded once at startup to minimize disk I/O
Product Data Cache - All product-related models (including Currency, CurrencyTable, and Vat) cached in memory for fast sale operations, currency calculations, VAT lookups, and button rendering
Active Closure Management - Current closure data maintained in session memory (CurrentData.closure) with automatic loading at startup and lifecycle management (open → active → closed)
Auto-Save Optimization - Automatic database persistence reduces manual save operations and ensures data integrity without performance overhead
Database Optimization - Query optimization and indexing
External Caching Layer - Redis/Memcached integration (optional)
Load Testing - Performance testing under high load
Memory Management - Efficient resource utilization via pos_data and product_data caches
Concurrent Transaction Handling - Multi-terminal support

Data Management

Data Migration Tools - Database upgrade and migration utilities
Backup & Recovery - Automated backup and restore systems
Data Export/Import - CSV, Excel, and API data exchange
Data Archiving - Long-term data storage solutions

Localization & Compliance

Multi-Language Support - Internationalization (i18n)
Currency Support - Multi-currency handling with exchange rate tracking
Tax Compliance - Country-specific tax regulations with VAT/tax rate management
Fiscal Printer Support - Government-mandated receipt requirements
Local Regulations - Region-specific compliance features via ClosureCountrySpecific model with template-based initialization (supports Turkey E-Fatura, USA state taxes, EU VAT reporting, etc.)
Region Management - CountryRegion model for tracking states/provinces/special zones with ISO 3166-2 compliant fields. Includes 80+ pre-populated regions (US states, CA provinces, DE states, FR regions) and integration with closure templates
ISO 3166 Compliance - Country and region models use ISO 3166-1 (alpha-2, alpha-3, numeric) and ISO 3166-2 (subdivision codes) standard field names for international compatibility

Documentation

Comprehensive documentation is available in the docs/ directory:

Documentation Index - Complete guide organized by topic
Installation Guide - Detailed setup instructions
Dynamic Forms System - Database-driven UI system
Virtual Keyboard - Virtual keyboard configuration
Data Caching - Caching strategy and implementation
Document Management - Transaction lifecycle management
Closure Operation - End-of-day closure (authorization, aggregation, sequences)
Central Logging - Logging configuration and usage (core/logger.py, settings.toml [logging])
Exception Handling - Centralized exception hierarchy, usage patterns, and design guidelines
Database Models - Complete model reference
Service Layer - Business logic services architecture
Troubleshooting - Common issues and solutions

Contributing

We welcome contributions to SaleFlex.PyPOS! Please read our contributing guidelines and feel free to submit issues, feature requests, or pull requests.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributors

_{Ferhat Mousavi}

Support & Donations

If you find SaleFlex.PyPOS valuable and want to support its development, you can contribute through cryptocurrency donations:

USDT: 0xa5a87a939bfcd492f056c26e4febe102ea599b5b
BUSD: 0xa5a87a939bfcd492f056c26e4febe102ea599b5b
BTC: 184FDZ1qV2KFzEaNqMefw8UssG8Z57FA6F
ETH: 0xa5a87a939bfcd492f056c26e4febe102ea599b5b
SOL: Gt3bDczPcJvfBeg9TTBrBJGSHLJVkvnSSTov8W3QMpQf

Your support helps us continue developing new features and maintaining this open-source project.

For more information about the SaleFlex ecosystem, visit SaleFlex.GATE for centralized management capabilities.

Name		Name	Last commit message	Last commit date
Latest commit History 245 Commits
core		core
data_layer		data_layer
docs		docs
pos		pos
settings		settings
static_files		static_files
user_interface		user_interface
.gitignore		.gitignore
LICENSE		LICENSE
PyPOS_GUIDE.md		PyPOS_GUIDE.md
README.md		README.md
requirements.txt		requirements.txt
saleflex.py		saleflex.py
settings.toml		settings.toml

Folders and files

Latest commit

History

Repository files navigation

SaleFlex.PyPOS

Touch Screen Point-of-Sale Application

Key Features

Architecture Overview

Project Structure

Business Applications

SaleFlex.GATE Integration

System Requirements

Hardware Requirements

Software Requirements

Supported Database Engines

Quick Start

Installation & Setup

Prerequisites

Installation Steps

First Login

Configuration

Database Models Overview

Development Roadmap

Core Infrastructure

POS Core Modules

Hardware Integration

User Interface

Business Features

Warehouse & Inventory Management

Sector-Specific Features

Integration & Connectivity

Security & Authentication

Performance & Scalability

Data Management

Localization & Compliance

Documentation

Contributing

License

Contributors

Support & Donations

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Uh oh!

Contributors

Uh oh!

Languages