Prerequisites
Relevant source files
The following files were used as context for generating this wiki page:This document outlines the system requirements, dependencies, and configuration needed to run the POS Tio Adan application and its optional Telegram Notification Service. The project consists of a core desktop application for point-of-sale and inventory management, and a separate, standalone service for sending automated alerts.
System Requirements
The primary operating system for deployment is Windows. A Python 3.x installation is required to run the application from source or to execute the setup scripts.
- Operating System: Windows 7 or higher.
- Python: Python 3.7 or later is required for running the installation scripts.
Sources: install_dependencies.bat:11-18, README_Notifications.txt:4
Core POS Application (pos_app.py)
The main application is a monolithic GUI application built with tkinter. It handles all point-of-sale, inventory, and reporting functionalities.
Python Dependencies
The core application requires several Python libraries for its functionality, including PDF generation and Excel file importing.
| Library | Version | Purpose |
|---|---|---|
tkinter | N/A | The standard Python interface to the Tcl/Tk GUI toolkit, used for the entire user interface. |
fpdf2 | >=2.7.0 | Used to generate PDF receipts for sales and daily reports. |
openpyxl | >=3.1.0 | Used for importing product data from .xlsx Excel files. |
Sources: requirements.txt:2-3, pos_app.py:2-8
Build Dependencies
To create a standalone Windows executable (.exe), the pyinstaller library is used. This is a development dependency and not required for running the application from source.
- Library:
pyinstaller - Purpose: Bundles the Python application and its dependencies into a single executable file.
The build process is defined in build_exe.bat, which uses pyinstaller with specific options to include necessary hidden imports like openpyxl and fpdf.
pyinstaller --onefile --windowed --name="POS_TioAdan" ^
--hidden-import=openpyxl ^
--hidden-import=fpdf ^
pos_app.py
Sources: build_exe.bat:17-21
Telegram Notification Service (Optional)
The notification service is a standalone component that monitors the inventory database (pos_inventory.db) and sends alerts via Telegram for out-of-stock products and daily sales summaries.
Python Dependencies
This service has its own set of dependencies for making HTTP requests and handling timezones.
| Library | Version | Purpose |
|---|---|---|
requests | >=2.31.0 | Used to communicate with the Telegram Bot API. |
pytz | >=2023.3 | Used for timezone-aware scheduling of the daily report. |
Sources: requirements.txt:6-7, notification_service.py:15-16
Configuration (config.json)
The service requires a config.json file in the same directory to function. This file must contain the Telegram bot credentials and other operational settings. An example structure is provided in config.example.json.
| Key Path | Type | Description |
|---|---|---|
telegram.bot_token | string | The API token for your Telegram bot, obtained from @BotFather. |
telegram.chat_id | string | The unique identifier for the target chat where notifications will be sent. |
check_interval_minutes | integer | The interval in minutes for how often the service checks the database. |
Sources: README_Notifications.txt:8-14, 61-69, notification_service.py:440-448
Installation and Setup
The repository includes a batch script to simplify the installation of Python dependencies.
Automated Dependency Installation
The install_dependencies.bat script automates the setup process. The diagram below illustrates its workflow.
This diagram shows the steps executed by the install_dependencies.bat script.
Sources: install_dependencies.bat
Configuration Verification
After setting up config.json, you can verify the Telegram bot credentials using the test_telegram.py script. This script performs two key actions:
- Validates the bot token by calling the
/getMeAPI endpoint. - Sends a test message to the configured
chat_idusing the/sendMessageendpoint.
The following sequence diagram illustrates the verification process.
Sources: test_telegram.py
Summary
To successfully run the entire system, a user must have Python installed, run the install_dependencies.bat script to fetch all required libraries for both the POS application and the notification service, and correctly configure the config.json file with valid Telegram credentials for the optional notification feature. The build_exe.bat script provides a way to package the core application for distribution on Windows without requiring a Python installation on the target machine.