Deployment Overview

Relevant source files

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

• build_exe.bat
• build_notification_exe.bat
• install_dependencies.bat
• notification_service.py
• pos_app.py
• README_Notifications.txt
• config.example.json
• requirements.txt

The project is deployed as two separate, standalone Windows executables: a primary Point of Sale (POS) GUI application and an optional background notification service. Both are generated from Python scripts using PyInstaller, which bundles the code and its dependencies into single .exe files. This approach simplifies distribution, as end-users do not need to have Python installed.

The deployment process involves installing dependencies, running build scripts to create the executables, and then distributing these executables along with necessary configuration files. The POS application is self-contained, while the notification service requires a config.json file and access to the POS database to function correctly.

System Components

The system is comprised of two main deployable artifacts, each built from a corresponding Python script.

Component	Source Script	Build Script	Purpose
POS_TioAdan.exe	pos_app.py	build_exe.bat	The main graphical user interface for sales, inventory management, and reporting.
TelegramNotifications.exe	notification_service.py	build_notification_exe.bat	A background console service that monitors inventory and sends Telegram alerts.

This diagram shows the relationship between the source code, build process, and the final deployed components.

Build Process

The executables are created using PyInstaller via two separate batch scripts. Before building, dependencies must be installed.

Dependencies Installation

The install_dependencies.bat script handles the setup for the notification service development environment. It checks for a Python installation and then installs the required packages from requirements.txt.

The primary dependencies are:

• POS Application: fpdf2, openpyxl
• Notification Service: requests, pytz

Sources: install_dependencies.bat:11-25, requirements.txt:2-7

POS Application Build (build_exe.bat)

The build_exe.bat script compiles the pos_app.py into a single, windowed executable named POS_TioAdan.exe.

The build process follows these steps:

1. Clean: Removes previous build and dist directories.
2. Build: Executes PyInstaller with specific flags:
   • --onefile: Bundles everything into a single .exe.
   • --windowed: Creates a GUI application without a console window.
   • --name="POS_TioAdan": Sets the output executable name.
   • --hidden-import: Includes openpyxl and fpdf which might be missed by PyInstaller's analysis.
3. Output: The final POS_TioAdan.exe is placed in the dist folder.

This flowchart illustrates the build process for the POS application.

Notification Service Build (build_notification_exe.bat)

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

The build process is similar to the POS application but uses different flags:

1. Clean: Removes the build directory and any previous executable.
2. Build: Executes PyInstaller with flags tailored for a background service:
   • --onefile: Bundles into a single .exe.
   • --console: Creates a console application, which is necessary to see service logs.
   • --name="TelegramNotifications": Sets the output executable name.
   • --hidden-import: Includes requests and pytz.
3. Output: The final TelegramNotifications.exe is placed in the dist folder.

This flowchart illustrates the build process for the notification service.

Runtime Environment and Configuration

For the applications to run correctly after deployment, certain files and directory structures are expected.

POS Application (POS_TioAdan.exe)

The POS application is largely self-sufficient. Upon first run, it will create the necessary files and folders in its directory.

File / Folder	Purpose	Created By
pos_inventory.db	The main SQLite database for products, sales, and inventory.	Database.init_database()
receipts/	Directory to store generated PDF receipts. Located on the Desktop by default, with a fallback to the application's directory.	POSApplication._init_output_paths()
reports/	Directory to store generated daily sales report PDFs.	POSApplication.generate_sales_report_pdf()
error_logs/	Directory to store logs for errors encountered during XLSX imports.	POSApplication.import_from_xlsx()

Sources: pos_app.py:25-26, 107, 110, 1004, 1572, 1795

Notification Service (TelegramNotifications.exe)

The notification service has external dependencies that must be present in the same directory as the executable.

The required file structure for deployment is as follows:

• pos_inventory.db: The POS database that the service monitors. It must be in the same folder.
• config.json: A critical configuration file containing API keys and settings. It must be created from config.example.json.
• notification_state.db: An SQLite database automatically created to track sent notifications and prevent duplicates.
• logs/: A directory automatically created to store service and error logs.

Sources: notification_service.py:28, 461, 513, config.example.json:11

config.json Configuration

This file controls the behavior of the notification service.

Section	Key	Description	Example Value
telegram	bot_token	The API token for the Telegram bot.	"123...:ABC..."
telegram	chat_id	The ID of the Telegram chat to send notifications to.	"123456789"
polling	zero_stock_interval_seconds	How often (in seconds) to check for out-of-stock products.	300
daily_report	send_time	The time of day (24-hour format) to send the daily report.	"08:00"
daily_report	timezone	The timezone for the daily report scheduler.	"America/Mexico_City"
database	pos_db_path	Path to the main POS database file.	"pos_inventory.db"
database	state_db_path	Path for the service's state-tracking database.	"notification_state.db"
logging	log_level	The logging level for the service.	"INFO"
notifications	out_of_stock	Contains settings for out-of-stock alerts, including an enabled flag and message_template.	{ "enabled": true, ... }
notifications	daily_report	Contains settings for daily reports, including an enabled flag and message_template.	{ "enabled": true, ... }

Sources: config.example.json

Execution

• POS Application: Double-click POS_TioAdan.exe to run the application.
• Notification Service:
  1. Ensure config.json is configured and pos_inventory.db is present.
  2. Double-click TelegramNotifications.exe.
  3. A console window will open and display log messages. This window must remain open for the service to continue monitoring.

Sources: README_Notifications.txt:14-19, 25-28