POS Simulator

A comprehensive Point of Sale (POS) System implementing core retail transaction workflows with a focus on robust inventory management, payment processing, and audit compliance.

🎯 Overview

The POS Simulator is a full-featured retail management system built with Python and Streamlit. It provides cashiers and managers with tools to process transactions, manage inventory, handle returns, and maintain comprehensive audit logs.

Key Features

• 🛒 Shopping Cart Management - Add/remove items, apply discounts, calculate taxes
• 💳 Payment Processing - Support for cash and card payments with change calculation
• 🧾 Receipt Generation - PDF receipt generation with detailed transaction info
• 📦 Inventory Management - Real-time stock tracking with low-stock alerts
• 📊 Sales Reporting - Daily sales summaries and transaction analytics
• 🔄 Returns & Exchanges - Process product returns and exchanges
• 👥 Role-Based Access Control - Manager, Cashier, and Auditor roles
• 📜 Audit Logging - Comprehensive activity logging for compliance
• 📥 Bulk Import - Import products from CSV/JSON files
• 💰 Approval Workflows - Manager approval for high-value discounts and voids

🛠️ Tech Stack

• Backend: Python
• Frontend: Streamlit
• Database: MySQL
• PDF Generation: xhtml2pdf, ReportLab
• ORM: SQLAlchemy

📋 Requirements

• Python 3.8+
• MySQL 8.0+
• Dependencies listed in requirements.txt

🚀 Installation

1. Clone the Repository

git clone https://github.com/bugsNburgers/POS_self.git
cd POS_self

2. Install Dependencies

pip install -r requirements.txt

3. Environment Configuration

Create a .env file in the project root:

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=1234
MYSQL_DB=pos_db

4. Database Setup

Ensure MySQL is running and create the database schema (consult your database setup documentation).

5. Run the Application

streamlit run app.py

The application will be available at http://localhost:8501

📁 Project Structure

POS_self/
├── app. py                          # Main Streamlit application
├── requirements. txt                # Python dependencies
├── . env                           # Environment variables (create locally)
├── pytest.ini                     # Pytest configuration
├── . pylintrc                      # Pylint configuration
│
├── services/                      # Business logic layer
│   ├── __init__.py               # Service exports
│   ├── db. py                     # Database connection pooling
│   ├── auth_service.py           # User authentication & authorization
│   ├── cart_service.py           # Shopping cart logic
│   ├── payment_service.py        # Payment processing
│   ├── receipt_service.py        # Receipt generation
│   ├── stock_service.py          # Inventory management
│   ├── import_service.py         # CSV/JSON product import
│   ├── return_service.py         # Return/exchange processing
│   ├── approval_service.py       # Approval workflows
│   ├── report_service.py         # Sales reporting
│   ├── logs_service.py           # Activity log queries
│   └── monitoring_service.py     # System monitoring
│
├── pages/                         # Streamlit pages (UI routes)
│   ├── cart.py                   # Cart management page
│   ├── payment.py                # Payment processing page
│   ├── receipt.py                # Receipt display page
│   ├── returns.py                # Return processing page
│   ├── reports.py                # Sales reports page
│   ├── stock.py                  # Stock management page
│   ├── import_products.py        # Product import page
│   ├── users.py                  # User management page
│   ├── approvals.py              # Approval requests page
│   ├── logs.py                   # Activity logs page
│   └── monitoring. py             # System monitoring page
│
├── assets/                        # Static assets
│   └── receipt_template.html     # Receipt PDF template
│
├── tests/                         # Unit and integration tests
│   ├── test_auth.py              # Authentication tests
│   ├── test_cart.py              # Cart logic tests
│   ├── test_payment.py           # Payment processing tests
│   ├── test_import.py            # Import functionality tests
│   └── ... 
│
├── DB/                           # Database scripts & schemas
│
├── CART_README.md                # Cart feature documentation
├── STOCK_IMPORT_README.md        # Import feature documentation
└── CICD pipeline. md              # CI/CD setup documentation

🔐 User Roles & Permissions

Manager

• Full system access
• Approve/deny discount and void requests
• User management
• System monitoring
• All reports and inventory features

Cashier

• Process transactions
• View cart and payment
• Generate receipts
• Process returns (with limitations)
• View own activity logs
• Discounts >10% require manager approval

Auditor

• Read-only access to activity logs
• Compliance reporting
• No transaction permissions

🗄️ Core Services

Database (services/db.py)

Connection pooling for MySQL with prepared statements and transaction support.

Authentication (services/auth_service.py)

User login, password verification, role-based access control, and audit logging.

Cart Management (services/cart_service.py)

• Add items to cart
• Quantity updates
• Line-item discounts
• GST calculation
• Cart persistence

Payment Processing (services/payment_service.py)

• Cash payment processing
• Card payment integration
• Change calculation
• Stock decrement on payment

Receipt Generation (services/receipt_service.py)

• PDF receipt generation using Jinja2 templates
• Receipt storage in database
• Receipt retrieval and display

Stock Management (services/stock_service.py)

• Real-time inventory tracking
• Low stock alerts
• Stock adjustments
• Stock history

Import Service (services/import_service.py)

• CSV/JSON product import
• Data validation
• Batch insert with duplicate handling
• Import audit logging

Approval Workflow (services/approval_service.py)

• Manager approval requests
• Discount approval tracking
• Void transaction approvals

Activity Logging (services/logs_service.py)

• Comprehensive audit trails
• Log filtering and search
• Export capabilities

🧪 Testing

Run tests using pytest:

# Run all tests
pytest

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

# Run specific test file
pytest tests/test_cart. py -v

📝 API Documentation

Refer to the individual module docstrings and the CART_README.md and STOCK_IMPORT_README.md files for detailed API documentation on specific features.

🔄 Development Workflow

1. Create feature branch from main
2. Make changes and write tests
3. Run pytest to ensure all tests pass
4. Commit with conventional commit messages
5. Push and create pull request for review

📊 Performance Considerations

• Database connection pooling (5 connection pool size)
• Decimal precision for financial calculations
• Indexed queries for receipt and transaction lookups
• Batch operations for bulk imports

🚨 Error Handling

• User-friendly error messages in Streamlit UI
• Detailed logging of system errors
• Transaction rollback on failures
• Validation of all user inputs

📄 License

Developed for retail point-of-sale operations.

---

For more detailed information on specific features:

• Cart Operations: See CART_README.md
• Product Imports: See STOCK_IMPORT_README.md
• CI/CD Pipeline: See CICD pipeline.md