🛒 OpenPOS — Modern, Secure & Open-Source Point of Sale System

OpenPOS is an open-source, offline-first, enterprise-ready Point of Sale (POS) and inventory management system designed for cafes, coffee shops, bakeries, grocery stores, restaurants, boutiques, and retail franchises.

---

🌟 Key Features & Capabilities

• ⚡ Offline-First & Local Relational Storage: Powered by embedded SQLite (sqflite_common_ffi). The system operates 100% autonomously without requiring an active internet connection.
• 🚀 Auto-Launch on System Startup: Built-in toggle in Settings to automatically boot into OpenPOS when the computer or POS terminal powers on.
• 🌐 Full 7-Language Localization (Instant On-the-Fly Switching):
  • 🇺🇦 Ukrainian (uk)
  • 🇬🇧 English (en)
  • 🇩🇪 German (de)
  • 🇵🇱 Polish (pl)
  • 🇧🇾 Belarusian (be)
  • 🇰🇿 Kazakh (kk)
  • 🇫🇷 French (fr)
• 💱 Dynamic Multi-Currency Engine & Automatic Conversion:
  • Base currency normalization (UAH ₴) with real-time conversion into $ (USD), € (EUR), zł (PLN), ₸ (KZT), and Br (BYN).
  • Automatic change calculation and smart denomination chips for the active currency.
• ⏱️ Work Shift & Cash Discipline:
  • Open Shift: Set initial drawer float (e.g. 500.00 ₴) with timestamps and cashier attribution.
  • Sales Lock: Trading and adding items to cart are strictly locked until a cashier opens the shift.
  • Cash In / Cash Out: Service drops and top-ups with supervisor approvals.
  • Close Shift & Z-Report: Automated reconciliation (Opening Float + Cash Sales + Drops = Expected Cash), difference detection (Surplus / Shortage), and fiscal Z-Report printing.
• 💳 Automated Bank POS Terminal Integration (PCI DSS Compliant):
  • Cashiers never manually type card numbers. Total amount is pushed automatically to the terminal via local network / socket protocol.
  • Customer taps card or phone (Apple Pay / Google Pay). Terminal returns RRN, auth code, and masked card digits (•••• •••• •••• 4927).
• 🎁 Customer Loyalty & Bonus System:
  • Search by customer phone or personal QR card.
  • Tiered loyalty (Bronze, Silver, Gold, VIP), discount percentages, and bonus points redemption.
• 🔄 Item Returns & Partial Refund Slip:
  • Lookup by receipt number (CHK-260825-0010).
  • Restores inventory quantity automatically upon refund.
• ⏸️ Park Cart / Held Orders:
  • Park active customer cart in 1 click and resume anytime.
• 📜 Continuous Action Audit Log:
  • Categorized stream ([AUTH], [SALE], [REFUND], [CASH_OP], [ERROR]) for manager oversight.
• 📊 Rich Styled Excel (.xls) & CSV Exports:
  • Generates beautifully styled spreadsheets with navy headers, borders, padding, and KPI summaries.
• 📋 Selectable & Copyable Electronic Receipts:
  • 1-click clipboard copy button and ESC/POS thermal printing.

---

🔨 How to Compile and Build Standalone Release Applications

To compile OpenPOS into a production-ready, standalone executable or installation package for your store terminals:

🪟 Windows Desktop Executable (Release Build)

1. Ensure Flutter Windows desktop support is enabled:

   flutter config --enable-windows-desktop

2. Build the optimized release bundle:

   flutter build windows --release

3. Your standalone application bundle will be generated in:

   build\windows\x64\runner\Release\
   ├── openpos.exe                 <-- Launch executable
   ├── flutter_windows.dll
   ├── data\
   └── sqflite_common_ffi.dll
   

   💡 Tip: You can copy this entire Release folder to any USB stick or PC, create a desktop shortcut to openpos.exe, and run it without needing Flutter or developer tools installed! You can also package it with Inno Setup to create a standard .exe installer.

---

🤖 Android Tablet / POS Terminal (APK & App Bundle)

1. Build standalone universal APK:

   flutter build apk --release

   Output: build/app/outputs/flutter-apk/app-release.apk

   Copy this APK file to your Android POS terminal (Sunmi, PAX, iMin, Samsung Galaxy Tab) and install it directly.

2. Build Google Play App Bundle (if distributing via store):

   flutter build appbundle --release

---

🍏 macOS & 🐧 Linux

• macOS App:

  flutter build macos --release

  Output: build/macos/Build/Products/Release/OpenPOS.app

• Linux Executable:

  flutter build linux --release

  Output: build/linux/x64/release/bundle/openpos

---

⚡ Automatic Launch on System Startup (Kiosk Mode)

OpenPOS includes an integrated auto-start feature designed for retail POS terminals:

1. Open «Налаштування» / «Settings» in the application.
2. Scroll to «Підтримка та Система» / «Diagnostics & Support».
3. Toggle the «Автозапуск при старті системи» / «Launch on System Startup» switch to ON.
4. How it works:
   • On Windows: It registers OpenPOS into HKCU\Software\Microsoft\Windows\CurrentVersion\Run. When the store computer is turned on, Windows boots straight into the OpenPOS login screen.
   • On Linux: It creates an autostart desktop entry in ~/.config/autostart/openpos.desktop.

---

📦 How to Add and Manage Products (Step-by-Step)

1. Navigate to the Inventory Screen:
   • Click «Склад» / «Inventory» in the left navigation rail.
2. Add a New Product:
   • Click the «+ Додати товар» / «Add Product» button in the top-right corner.
   • Fill in the required fields:
     • Назва товару / Product Name: (e.g., Cappuccino 250ml).
     • Штрихкод / Barcode (SKU): Scan with barcode scanner or enter manually (e.g., 482000001001).
     • Категорія / Category: (e.g., Кава та Напої, Випічка, Снеки).
     • Ціна продажу / Selling Price: Base price in store currency (e.g., 55.00).
     • Собівартість / Cost Price (COGS): Purchase cost (e.g., 18.00) used for profit and margin calculations.
     • Кількість на складі / Stock Quantity: Initial inventory units (e.g., 150).
   • Click «Зберегти» / «Save».
3. Edit or Delete Products:
   • In the inventory list, click the ✏️ Edit icon next to any product to update prices or stock.
   • Click the 🗑️ Delete icon to remove obsolete items.
4. Low Stock Notifications:
   • When stock drops below 15 units, the item badge automatically turns Red to alert store staff.

---

🔌 Hardware & Peripherals Connection Guide

1. 📟 Barcode & 2D QR Scanners

• Connection: USB cable or Bluetooth wireless cradle.
• Operating Mode: HID (Keyboard Wedge Mode).
• How it works: When a barcode is scanned, the scanner automatically inputs the digits and emits an Enter key stroke. OpenPOS listens for scanner events across Windows, Android, macOS, and Linux without requiring any proprietary drivers.

2. 🖨️ Thermal Receipt Printers (ESC/POS)

• Supported Connection Types:
  • Ethernet / Wi-Fi (Recommended): Set printer IP address in Settings (e.g., 192.168.1.100, Port 9100).
  • USB / Virtual COM: Supported via standard POS print spooler.
  • Bluetooth: For mobile Android/iOS tablet setups.
• Standard Widths: Supports standard 58mm and 80mm thermal rolls with automatic line formatting.

3. 💳 Bank POS Terminals (Card & Contactless NFC)

• Supported Providers: PrivatBank, Monobank, Oschadbank, Ingenico, PAX, Verifone (BOS / JSON API protocols over local LAN/TCP/IP).
• Workflow:
  1. Cashier selects «Термінал» / «Card Terminal» during checkout.
  2. POS sends the transaction amount to the terminal IP.
  3. Customer taps card / smartphone (Apple Pay / Google Pay) and enters PIN on terminal keypad if requested.
  4. Terminal responds with SUCCESS, RRN Code, and AuthCode.
  5. POS prints the combined fiscal receipt with terminal authorization data.

---

🔒 Security Architecture & PCI DSS Compliance

OpenPOS is designed following PCI DSS (Payment Card Industry Data Security Standard) principles:

1. Zero Cardholder Data Retention (No PAN/CVV Stored):
   • The application NEVER prompts for, receives, or stores raw primary account numbers (PAN), magnetic stripe data, or CVV/CVC codes.
   • Only non-sensitive masked references (•••• •••• •••• 4927) and bank RRN codes are stored in sales records.
2. Cryptographic PIN Hashing:
   • Cashier PIN codes are hashed using SHA-256 with a unique application salt before SQLite storage. Plaintext PINs are never persisted.
3. Role-Based Access Control (RBAC):
   • Cashier (0000): Ring up sales, scan items, park carts, process payments.
   • Senior Cashier / Manager (2222): Authorize discounts, perform cash drops, approve returns.
   • Administrator (1111): Full access to financial analytics, store settings, and user management.
   • Manager Override: Sensitive actions require on-screen supervisor PIN verification.
4. Tamper-Evident Action Audit Logging:
   • All critical operations (logins, sales, refunds, cash drawer operations, errors) are recorded into app_logs with microsecond timestamps and user IDs.

---

📁 Clean Architecture Project Structure

lib/
├── core/
│   ├── constants/             # Global configurations & constants
│   ├── security/              # PCI DSS helpers, SHA-256 PIN hashing, audit logger
│   ├── services/              # Thermal printer, terminal, autostart, report export services
│   ├── theme/                 # Light and Dark Material 3 POS themes
│   └── utils/                 # i18n 7-language dictionary, currency converter, receipt generator
├── data/
│   ├── datasources/           # Local SQLite database & migrations
│   └── repositories_impl/     # Repository implementations (Sales, Products, Users, Settings)
├── domain/
│   ├── entities/              # Core business models (Product, Shift, SaleTransaction, Customer, User)
│   └── repositories/          # Domain repository contracts
└── presentation/
    ├── providers/             # State management via Flutter Riverpod
    ├── screens/               # UI Screens (POS, Inventory, Reports, Settings, Login)
    └── widgets/               # Touch keypads, shift dialogs, receipt preview, logs viewer

---

🚀 Getting Started & Build Instructions

Prerequisites

• Flutter SDK (v3.24.0 or higher)
• Visual Studio (Windows C++ Desktop development tools) or Android Studio

Installation & Development Run

# 1. Clone the repository
git clone https://github.com/your-username/openpos.git
cd openpos

# 2. Fetch Flutter dependencies
flutter pub get

# 3. Run automated unit tests
flutter test

# 4. Run in debug mode:
flutter run -d windows

Default Demo PINs

• Cashier: 0000
• Senior Cashier / Manager: 2222
• Administrator: 1111

---

📄 License & Commercial Usage

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

💡 You are completely free to use, modify, customize, and deploy this software in your own stores, restaurants, supermarkets, and commercial retail businesses without paying any license fees or royalties.