Running the POS Application

Relevant source files

The following files were used as context for generating this wiki page:

• pos_app.py
• build_exe.bat
• notification_service.py
• requirements.txt
• test_telegram.py
• README_Notifications.txt
• CLAUDE.md

This document outlines the architecture, prerequisites, and procedures for running the Point of Sale (POS) application and its associated services. The system is designed as a desktop application for small retail operations, with an optional notification service for inventory monitoring.

The core application is a monolithic Python script using tkinter for the user interface and SQLite for data persistence. It can be run directly from the source code or as a compiled standalone executable. An independent notification service can run in the background to send alerts via Telegram for out-of-stock products and daily sales summaries.

Sources: CLAUDE.md:5-8, pos_app.py, notification_service.py:5-10

Architecture Overview

The system consists of two main components: the core POS application and an optional Telegram notification service. Both components interact with the same SQLite database but operate independently.

This diagram shows the main components. The user interacts with the POS Application GUI (pos_app.py), which reads from and writes to the pos_inventory.db database. The optional Notification Service (notification_service.py) runs separately, reads data from the same database, and sends alerts to the Telegram API.

Sources: pos_app.py, notification_service.py

Prerequisites

To run the application from the source code, the following Python libraries are required.

Library	Version	Purpose
fpdf2	>=2.7.0	Generating PDF receipts and reports.
openpyxl	>=3.1.0	Importing product data from .xlsx files.
requests	>=2.31.0	(For Notification Service) API calls to Telegram.
pytz	>=2023.3	(For Notification Service) Timezone handling.

These dependencies are listed in the requirements.txt file. tkinter is also required and is typically included with standard Python installations.

Sources: requirements.txt:2-7, CLAUDE.md:11

Method 1: Running as a Python Script

The primary method for running the application during development is by executing the main Python script.

1. Install the required dependencies:

   pip install -r requirements.txt
   

2. Run the application:

   python pos_app.py
   

Upon first execution, the application will automatically create the pos_inventory.db file in the same directory if it does not exist. It will also create a receipts directory on the user's Desktop for storing PDF receipts.

Sources: CLAUDE.md:9-11, pos_app.py:656-658, 777-781

Method 2: Building and Running the Executable

For deployment on systems without a Python environment, a standalone Windows executable can be built using the build_exe.bat script. This script uses PyInstaller to package the application and its dependencies into a single .exe file.

Build Process

The build_exe.bat script automates the following steps:

This flowchart illustrates the process automated by build_exe.bat, from cleaning old build artifacts to generating the final executable.

Sources: build_exe.bat:5-24

The PyInstaller command includes hidden imports to ensure libraries like openpyxl and fpdf are correctly bundled.

pyinstaller --onefile --windowed --name="POS_TioAdan" ^
  --hidden-import=openpyxl ^
  --hidden-import=fpdf ^
  pos_app.py

Sources: build_exe.bat:19-22

After a successful build, the executable POS_TioAdan.exe will be located in the dist directory. This single file can be distributed and run. On its first run, it will create the database (pos_inventory.db), receipts, reports, and error_logs directories in its current location.

Sources: build_exe.bat:29-37

Method 3: Running the Notification Service

The notification_service.py is a standalone service that monitors the inventory and sends alerts. It is designed to be run continuously in the background.

Features

• Zero-Stock Alerts: Polls the database every 5 minutes (configurable) and sends a Telegram message when a product's quantity reaches zero. It uses a state database (notification_state.db) to avoid sending duplicate alerts.
• Daily Sales Reports: Sends a summary of the previous day's sales at a configured time.

Sources: notification_service.py:5-10, 68-71, 513-524, README_Notifications.txt:19-22

Setup and Execution

1. Configuration: Copy config.example.json to config.json and fill in your Telegram bot_token and chat_id.
2. Testing: Run python test_telegram.py to verify that the bot token and chat ID are correct. This script will attempt to send a test message to the configured chat.
3. Execution: Run the service with python notification_service.py. The service will start and log its status to the console and to files in the logs/ directory.

The following diagram shows the sequence of a zero-stock alert.

This sequence diagram illustrates how the notification service checks for new out-of-stock products and sends an alert via Telegram, ensuring no duplicate notifications are sent.

Sources: notification_service.py:513-524, test_telegram.py, README_Notifications.txt:10-15

Application Structure and Data

Core Application (pos_app.py)

The main application is structured into two primary classes within a single file.

This class diagram shows the relationship between the POSApplication class, which manages the GUI and application logic, and the Database class, which handles all SQLite operations.

Sources: pos_app.py:25, 660

Database Schema

The application uses an SQLite database named pos_inventory.db to persist all data. The schema is automatically initialized on the first run.

This ER diagram outlines the tables in the pos_inventory.db database, including products for inventory, sales for transaction history, folio_counter for receipt numbering, and migrations for tracking schema changes.

Sources: pos_app.py:30-111

Generated Files and Directories

The application and its associated scripts create several files and directories during operation.

File / Directory	Created By	Purpose
pos_inventory.db	pos_app.py	Main SQLite database for inventory and sales.
receipts/	pos_app.py	Stores generated PDF receipts. Located on Desktop or in app folder.
reports/	pos_app.py	Stores generated PDF daily sales reports.
error_logs/	pos_app.py	Stores logs for errors encountered during XLSX import.
dist/POS_TioAdan.exe	build_exe.bat	The compiled, distributable application executable.
notification_state.db	notification_service.py	State database for the notification service to track sent alerts.
logs/	notification_service.py	Contains log files for the notification service.

Sources: pos_app.py:681, 1756, 1928, build_exe.bat:29, notification_service.py:48, 560

Conclusion

The POS Tio Adan application offers flexible execution methods suitable for both development and production environments. It can be run directly as a Python script for easy debugging and modification, or it can be compiled into a single, portable executable for straightforward deployment on Windows systems. The optional, decoupled notification service enhances its utility by providing real-time inventory alerts and daily summaries, making it a comprehensive solution for managing a small retail business.