BOSRetail - Store POS & Back Office System

A comprehensive Point of Sale (POS) and Back Office management system designed for small-to-medium retail stores. Built with Python, PyQt6, and SQLAlchemy, BOSRetail provides a reliable, offline-first solution for retail operations.

🚀 Quick Start

For End Users

Download the latest release: BOSRetail-Demo-v0.1.0-Windows-x64.zip
Extract to your desired location
Run BOSRetail.exe
Login with demo credentials:
- Admin: admin / Admin123
- Manager: john.manager / Manager123
- Cashier: sarah.cashier / Cashier123

📖 See: Installation Guide | Quick Start Guide

For Developers

# Clone and setup
git clone <repository-url>
cd BOSRetail
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

# Initialize demo database
python -m src.utils.demo_data

# Run the application
python -m src.gui.main

🔧 See: Architecture Guide | Development Setup

✨ Key Features

🛒 Point of Sale (POS)

Fast sales processing with barcode scanning
Multiple payment methods (Cash, Card, Mixed)
Standard (B2C) and Company (B2B) receipts
Real-time inventory updates
Cashier session tracking

🏢 Back Office Management

Products: Add, edit, organize with categories
Inventory: Multi-location support, stock adjustments, low-stock alerts
Purchase Orders: Full workflow with goods receipt
Companies: B2B customer management
Users: Role-based access (Admin, Manager, Cashier)
Locations: Multiple stores with separate inventories
Pricing: Default and location-specific pricing

📊 Comprehensive Reports

Daily Sales Report
Sales by Product
Sales by Cashier
Inventory Report
Low Stock Alerts
Financial Summary

🔌 REST API (Optional)

External system integration (ERP, e-commerce)
API key authentication
Full CRUD operations
Webhook support

🏗️ System Architecture

BOSRetail is a standalone desktop application with optional API server:

┌─────────────────────────────────────────────┐
│  Desktop Application (BOSRetail.exe)       │
│  ┌─────────────────────────────────────┐   │
│  │  PyQt6 GUI                          │   │
│  │  - POS, Back Office, Reports        │   │
│  └─────────────────────────────────────┘   │
│              ↓ SQLAlchemy                   │
│  ┌─────────────────────────────────────┐   │
│  │  SQLite Database                    │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐  ← Optional
│  API Server (Separate Process)             │
│  ┌─────────────────────────────────────┐   │
│  │  FastAPI REST API                   │   │
│  └─────────────────────────────────────┘   │
│              ↓ SQLAlchemy                   │
│  ┌─────────────────────────────────────┐   │
│  │  SQLite Database (Shared)           │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

Key Points:

✅ GUI has direct database access (not client-server)
✅ API server is optional (for external integrations only)
✅ Offline-first design
✅ Multi-location support

📚 Learn More: Architecture Overview | Architecture FAQ

📚 Documentation

All comprehensive documentation is organized in the docs/ folder.

🎯 Where to Start

→ Complete Documentation Index - All docs organized by topic
→ Project Organization - Folder structure guide
→ Quick Reference - Find anything fast
→ Cleanup Reports - Organization & cleanup documentation

📖 User Documentation

Document	Description
Installation Guide	Complete setup instructions
Quick Start Guide	Get started in 5 minutes
Quick Reference	Common tasks and keyboard shortcuts

👨‍💻 Developer Documentation

Document	Description
Architecture Overview	System design and patterns
Architecture FAQ	Common architecture questions
Quick Architecture Guide	Developer onboarding
Testing Guide	How to test the application
Build Process	Creating deployments

🚀 Deployment Documentation

Document	Description
Main Deployment Guide	Complete deployment overview - START HERE ⭐
BoS Service Guide	API service deployment (central server)
POS Deployment Guide	POS terminal installation and setup
Quick Setup Guide	Fast deployment for all scenarios
BoS Deployment Guide	Back Office GUI deployment
Deployment Checklist	Pre-deployment verification
Packages Guide	Understanding packages

🛠️ Technology Stack

Component	Technology
Language	Python 3.10+
GUI Framework	PyQt6
Database	SQLite (default), PostgreSQL/MySQL (optional)
ORM	SQLAlchemy
API Framework	FastAPI
Authentication	bcrypt
Deployment	PyInstaller
Testing	pytest

📊 System Requirements

Minimum

OS: Windows 10 or later
RAM: 4 GB
Storage: 500 MB
Display: 1280x720

🗂️ Project Structure

BOSRetail/
├── src/                      # Source code
│   ├── api/                 # REST API (FastAPI)
│   ├── database/            # Models and database access
│   ├── gui/                 # User interface (PyQt6)
│   │   ├── screens/        # Application screens
│   │   └── dialogs/        # Dialog windows
│   ├── services/            # Business logic layer
│   └── utils/               # Utilities and helpers
├── docs/                     # Documentation
│   ├── user-guide/          # End-user documentation
│   ├── development/         # Developer documentation
│   ├── deployment/          # Deployment guides
│   └── archive/             # Historical docs
├── tests/                    # Test suite
│   ├── test_services/       # Service layer tests
│   └── test_database/       # Database tests
├── data/                     # Database files
├── backups/                  # Automatic backups
├── examples/                 # Code examples
├── build_deployment.ps1      # Production build script
├── build_demo_deployment.ps1 # Demo build script
└── requirements.txt          # Python dependencies

🔒 Security Features

✅ Password hashing with bcrypt
✅ Role-based access control (Admin, Manager, Cashier)
✅ Session management with timeout
✅ Comprehensive audit logging
✅ API key authentication
✅ Rate limiting
✅ Input validation

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src tests/

# Run specific test suite
pytest tests/test_services/test_sales_service.py

Test Coverage:

✅ Service layer tests
✅ Database model tests
✅ Business logic validation
✅ Error handling

📖 See: Testing Guide

📦 Building Deployments

Build All Targets (Recommended)

Windows:

.\build-all.ps1

Linux/Mac:

./build-all.sh

Builds all deployment packages:

Translations (.qm files)
POS Demo & Production
BoS Demo, Production & API Service

Individual Builds

POS Demo:

.\build-demo.ps1

POS Production:

.\build-prod.ps1

BoS Demo:

.\build-bos-demo.ps1

BoS Production:

.\build-bos-prod.ps1

BoS API Service:

.\build-bos-service.ps1

Translations:

.\build-translations.ps1

Advanced Options

# Build specific target
.\build-all.ps1 -Target POS

# Skip translations
.\build-all.ps1 -SkipTranslations

# Skip ZIP archives
.\build-all.ps1 -SkipZip

# Force rebuild
.\build-all.ps1 -Force

# Run builds in parallel (faster)
.\build-all.ps1 -Parallel

📖 See: Build Scripts Guide | Build Process Explained

🚀 Deployment (Build + Package Everything)

NEW: Master deployment scripts that build all packages and create a unified deployment structure.

Windows:

.\deploy-all.ps1

Linux/Mac:

./deploy-all.sh

What it does:

Builds all packages (via build-all script)
Collects all deployment artifacts
Creates deployment directory with:
- All package folders/ZIPs
- DEPLOYMENT_MANIFEST.txt - Package inventory
- README.md - Deployment guide
Creates deployment ZIP archive (optional)

Common scenarios:

# Deploy everything (default)
.\deploy-all.ps1

# Deploy only POS packages
.\deploy-all.ps1 -Target POS

# Deploy only BoS packages
.\deploy-all.ps1 -Target BoS

# Skip build (use existing packages)
.\deploy-all.ps1 -SkipBuild

# Custom output directory
.\deploy-all.ps1 -OutputDir C:\Deployments\BOSRetail-v1.0

# Force overwrite + skip ZIP
.\deploy-all.ps1 -Force -SkipZip

📖 See: Deployment Scripts Guide

🗺️ Roadmap

✅ Version 0.1.0 (Current)

Complete POS functionality
Back office management
Multi-location support
Purchase order workflow
Company (B2B) receipts
Comprehensive reporting
REST API

🔮 Future Versions

Cloud synchronization for multi-store
Mobile app for inventory management
Customer loyalty program
Advanced analytics dashboard
E-commerce integration
Multi-currency support
Multi-language support
Returns/refunds workflow

📝 Change Log

Version 0.1.0 (December 23, 2025)

✅ Initial production release
✅ Complete POS and back office functionality
✅ Multi-location inventory management
✅ Purchase order workflow
✅ Company receipt support
✅ Comprehensive reporting
✅ REST API with authentication
✅ Fixed report generation issues
✅ Fixed SQL join ambiguity in inventory reports

🆘 Support & Contributing

Getting Help

📖 Check the documentation
❓ Review Architecture FAQ
🐛 Report issues through the issue tracker

Development

Fork the repository
Create a feature branch
Make your changes
Write/update tests
Submit a pull request

📄 License

👥 Credits

Developed with ❤️ for small and medium retail businesses.

Special Thanks:

Python community
PyQt6 developers
SQLAlchemy team
FastAPI framework

Version: 0.1.0
Last Updated: December 23, 2025
Status: ✅ Production Ready

Quick Links: Installation | Quick Start | Deployment | Architecture

Name		Name	Last commit message	Last commit date
Latest commit History 668 Commits
.github		.github
.vscode		.vscode
_PROJECT_TEMPLATE		_PROJECT_TEMPLATE
build-config		build-config
docs		docs
examples		examples
migrations		migrations
scripts		scripts
src		src
test-scripts		test-scripts
tests		tests
utilities		utilities
.gitignore		.gitignore
DEBUG_LAUNCHER_GUIDE.md		DEBUG_LAUNCHER_GUIDE.md
INTEGRATED_FEATURES_SUMMARY.md		INTEGRATED_FEATURES_SUMMARY.md
README.md		README.md
SESSION_LOG.md		SESSION_LOG.md
build-all.ps1		build-all.ps1
build-all.sh		build-all.sh
build-bos-demo.ps1		build-bos-demo.ps1
build-bos-prod.ps1		build-bos-prod.ps1
build-bos-service.ps1		build-bos-service.ps1
build-demo.ps1		build-demo.ps1
build-prod.ps1		build-prod.ps1
build-translations.ps1		build-translations.ps1
complete_localization_fix.py		complete_localization_fix.py
debug_launcher.py		debug_launcher.py
deploy-all.ps1		deploy-all.ps1
deploy-all.sh		deploy-all.sh
enhance_localizer_combobox.py		enhance_localizer_combobox.py
fix_inventory_translations.py		fix_inventory_translations.py
fix_reports_hardcoded.py		fix_reports_hardcoded.py
fix_widget_tabs.py		fix_widget_tabs.py
requirements.txt		requirements.txt
run-app.ps1		run-app.ps1
show_fix_demo.sh		show_fix_demo.sh
test_bos_phase1.py		test_bos_phase1.py
test_debug_launcher_fix.py		test_debug_launcher_fix.py
test_dependency_check.py		test_dependency_check.py
test_localization_fix.py		test_localization_fix.py
test_login_fix.py		test_login_fix.py
test_pos_product_search_feature.py		test_pos_product_search_feature.py
test_translation_paths.py		test_translation_paths.py
verify_debug_launcher.py		verify_debug_launcher.py
verify_debug_launcher_fix.py		verify_debug_launcher_fix.py

fmoric/BOSRetail

Folders and files

Latest commit

History

Repository files navigation