Installation Guide

Relevant source files

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

• install_dependencies.bat
• requirements.txt
• pos_app.py
• build_exe.bat
• notification_service.py
• build_notification_exe.bat
• README_Notifications.txt
• test_telegram.py

This guide provides comprehensive instructions for setting up and installing the pos-tioadan project. The system consists of two main components: the core Point of Sale (POS) desktop application and an optional, standalone Telegram Notification Service. Both components can be run directly from the Python source code or be compiled into standalone executables for distribution.

This document covers prerequisites, dependency management, running from source, and building executables for deployment. Following these steps will result in a fully functional POS system with inventory management and optional real-time alerts.

Prerequisites

Before proceeding with the installation, ensure your system meets the following requirements:

• Python: Python 3.7 or later must be installed and accessible from your system's PATH. The installation scripts verify this.
  • Sources: install_dependencies.bat:12-18
• Internet Connection: Required to download Python packages from PyPI.
  • Sources: install_dependencies.bat:24-30
• Operating System: The build scripts (.bat) are designed for Windows. The Python code itself is platform-agnostic but the GUI is built with Tkinter.
  • Sources: README_Notifications.txt:4, build_exe.bat, build_notification_exe.bat

Installation from Source

This method is recommended for development and allows for direct modification of the source code. It involves setting up a Python environment and running the scripts directly.

The diagram below shows the high-level workflow for setting up the project from source.

Python Dependencies

The project's dependencies are listed in requirements.txt. They are separated by component.

Package	Version	Component	Description
fpdf2	>=2.7.0	POS Application	Used for generating PDF receipts and reports.
openpyxl	>=3.1.0	POS Application	Used for importing product data from .xlsx files.
requests	>=2.31.0	Notification Service	Used to send messages to the Telegram API.
pytz	>=2023.3	Notification Service	Used for timezone handling in the daily report scheduler.

Sources: requirements.txt:2-7, pos_app.py:5,6, notification_service.py:16,17

You can install all dependencies at once by running:

python -m pip install -r requirements.txt

Sources: install_dependencies.bat:23

1. POS Application Setup

The core POS application is a single-file graphical application.

1. Install Dependencies: Ensure fpdf2 and openpyxl are installed.

2. Run the Application: Execute the main script from your terminal.

   python pos_app.py
   

   Sources: CLAUDE.md:11

3. First Run: On its first execution, the application will automatically create necessary files and folders in its current directory:

   File / Folder	Description
   pos_inventory.db	The SQLite database for storing products, sales, and inventory data.
   receipts/	Default directory for saving generated PDF receipts. On Windows, it attempts to use Desktop/recibos.
   reports/	Directory for saving daily sales report PDFs.
   error_logs/	Directory for storing logs of errors encountered during XLSX imports.

   Sources: pos_app.py:22, pos_app.py:668, pos_app.py:1453, pos_app.py:1839

2. Notification Service Setup

The notification service is a background process that monitors the POS database.

1. Run the Setup Script: The install_dependencies.bat script automates the initial setup. It checks for Python, installs dependencies (requests, pytz), and creates the logs directory.

   install_dependencies.bat
   

   This sequence diagram illustrates the script's execution flow.

*Sources: [install_dependencies.bat](https://github.com/Alonso-pixel/pos-tioadan/blob/HEAD/install_dependencies.bat)*

2. Configure Credentials: The service requires a config.json file in the same directory.
* Copy config.example.json to config.json.
* Edit config.json and provide your Telegram bot_token and chat_id.
* Sources: README_Notifications.txt:10-14, notification_service.py:438-448

1. Test Configuration: Run test_telegram.py to verify your bot token and chat ID are correct. This script will attempt to send a test message to your specified Telegram chat.

   python test_telegram.py
   

   Sources: test_telegram.py, install_dependencies.bat:46-48

2. Run the Service: Once configured and tested, start the service.

   python notification_service.py
   

   The service will run continuously, polling the database for changes. On its first run, it will create notification_state.db to track sent alerts and a logs/ directory for its operational logs.
   Sources: notification_service.py:596, notification_service.py:35, notification_service.py:454

Building Executables

For easier distribution without requiring a Python installation on the target machine, you can build standalone .exe files using the provided batch scripts, which leverage PyInstaller.

1. Building the POS Application

The build_exe.bat script compiles pos_app.py into a single executable file.

The build process is as follows:

The PyInstaller command used is:

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

• --onefile: Bundles everything into a single executable.
• --windowed: Prevents a console window from appearing when the GUI app is run.
• --hidden-import: Ensures that libraries not automatically detected by PyInstaller are included.

The final executable will be located at dist/POS_TioAdan.exe.
Sources: build_exe.bat:19-23

2. Building the Notification Service

The build_notification_exe.bat script compiles notification_service.py into a console-based executable.

The PyInstaller command used is:

pyinstaller --onefile --console --name="TelegramNotifications" ^
  --hidden-import=requests ^
  --hidden-import=pytz ^
  notification_service.py

• --console: Ensures the application runs in a console window, which is necessary for a background service to display logs and be managed.

The final executable will be at dist/TelegramNotifications.exe.
Sources: build_notification_exe.bat:18-22

Deployment of Executables

After building, the executables can be deployed.

POS Application (POS_TioAdan.exe)

Simply copy dist/POS_TioAdan.exe to the target machine. No other files are needed. When run, it will create its database (pos_inventory.db) and other necessary folders in the same directory where it is located.
Sources: build_exe.bat:37-42

Notification Service (TelegramNotifications.exe)

This service requires a specific file structure to function correctly.

The following files must be placed in the same directory on the target machine:

• TelegramNotifications.exe: The compiled service.
• config.json: The configuration file with Telegram credentials.
• pos_inventory.db: The database file from the POS application that the service will monitor.

When TelegramNotifications.exe is run, it will create notification_state.db and the logs/ directory in this same folder.
Sources: build_notification_exe.bat:36-44, README_Notifications.txt:70-74