Contributing to the Project

Relevant source files

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

• CLAUDE.md
• build_exe.bat
• config.example.json
• error_logs/importing_errors_2025-11-01_14-52-12.txt
• install_dependencies.bat
• notification_service.py
• pos_app.py
• README_Notifications.txt
• requirements.txt
• test_telegram.py

This document provides a technical overview of the "POS Tio Adan" project, intended for developers who wish to contribute. It covers the system architecture, development setup, key components, and build processes. The project consists of a primary Point of Sale (POS) desktop application and an optional, standalone Telegram notification service.

The core of the project is a monolithic POS application built with Python's Tkinter for the GUI and SQLite for the database. It is designed for small retail operations. A separate notification service runs in the background, monitoring the database for specific events (like zero-stock products) and sending alerts via Telegram.

System Architecture

The project is composed of two main, independent applications that interact through a shared SQLite database.

• POS Application (pos_app.py): A single-file, monolithic desktop application that handles all user-facing POS and inventory management tasks.
• Notification Service (notification_service.py): A standalone, multi-threaded service that polls the database and sends alerts via the Telegram Bot API.

The diagram below illustrates the high-level architecture and data flow between components.

Development Setup

To contribute to the project, you need Python 3.7+ installed. The setup involves installing dependencies from requirements.txt.

Sources: install_dependencies.bat:12-18

Dependencies

The project is split into two parts, each with its own set of dependencies.

Component	Dependency	Version	Description
POS Application	fpdf2	>=2.7.0	For generating PDF receipts and reports.
POS Application	openpyxl	>=3.1.0	For importing products from .xlsx files.
Notification Service	requests	>=2.31.0	For making HTTP requests to Telegram API.
Notification Service	pytz	>=2023.3	For handling timezones in daily reports.

Sources: requirements.txt:2-7

Installation

A batch script is provided to automate the setup process on Windows.

1. Ensure Python is installed and added to the system's PATH.
2. Run the install_dependencies.bat script. This script performs the following actions:
   • Checks for a valid Python installation.
   • Installs all required packages using pip install -r requirements.txt.
   • Creates the logs/ directory for the notification service.
   • Checks if config.json exists and provides a warning if it's missing.

Sources: install_dependencies.bat:5-52

Configuration

The notification service requires a config.json file. You must copy config.example.json to config.json and fill in your Telegram credentials.

Sources: README_Notifications.txt:11-15, test_telegram.py:12-18

The configuration file contains settings for Telegram, database paths, polling intervals, and logging.

Section	Key	Description	Default Value
telegram	bot_token	Your Telegram bot token from @BotFather.	...-EXAMPLE
telegram	chat_id	The chat ID to send notifications to.	123456789
polling	zero_stock_interval_seconds	How often to check for out-of-stock products.	300 (5 minutes)
daily_report	send_time	Time to send the daily report (HH:MM).	08:00
daily_report	timezone	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 to the notification service's state database.	notification_state.db
logging	log_level	Logging level for the service.	INFO
notifications	out_of_stock.message_template	Template for the out-of-stock alert message.	(See file)
notifications	daily_report.message_template	Template for the daily sales report message.	(See file)

Sources: config.example.json

Database Schema

The system uses two separate SQLite databases: one for the POS application (pos_inventory.db) and one for the notification service state (notification_state.db).

POS Database (pos_inventory.db)

This database stores all product, sales, and application-related data. It is managed by the Database class in pos_app.py.

The following ER diagram shows the relationships between the tables in pos_inventory.db.

Notification State Database (notification_state.db)

This database is used exclusively by notification_service.py to prevent duplicate alerts and track sent reports. It is managed by the StateTracker class.

Core Components

POS Application (pos_app.py)

This is a monolithic Tkinter application structured into two main classes.

Sources: CLAUDE.md:13

Database Class

Handles all SQLite operations for pos_inventory.db. It opens and closes a connection for each individual operation, with no connection pooling. Key methods include add_product, get_product_by_barcode, record_sale, and update_quantity. The class also handles database initialization and schema migrations, such as adding new columns (folio, cost, brand) to existing tables.

Sources: pos_app.py:19-511, CLAUDE.md:45-46

POSApplication Class

The main GUI application class. It manages the Tkinter root window and a ttk.Notebook with multiple tabs:

1. Venta/Salida de Inventario (POS): For selling products.
2. Entrada y Busqueda de Inventario (Inventory): For managing stock, searching, filtering, and importing products.
3. Imprimir Ticket (Receipt): To view, copy, or save the last sales receipt as a PDF.
4. Reportes (Reports): To generate daily sales reports on demand.

Sources: pos_app.py:688-788

The sales process flow is illustrated in the sequence diagram below.

Notification Service (notification_service.py)

A standalone, multi-threaded Python script that provides real-time alerts and daily reports. It is designed to run continuously in the background.

Sources: notification_service.py:3-9

The service is composed of several classes:

Class	Description
StateTracker	Manages notification_state.db to prevent duplicate alerts and log sent reports.
POSDatabaseReader	Provides read-only access to pos_inventory.db with a connection timeout to avoid locking the GUI app.
TelegramNotifier	Handles all communication with the Telegram Bot API, including message formatting and retry logic.
NotificationService	The main orchestrator class that initializes components and manages the monitoring threads.

Sources: notification_service.py:29-498

The zero-stock monitoring flow is as follows:

Build Process

The project includes a batch script, build_exe.bat, to package the pos_app.py into a single, standalone Windows executable using PyInstaller.

The build process is as follows:

1. Clean: Removes previous build artifacts (build/, dist/, *.spec).
2. Build: Runs pyinstaller with the following key options:
   • --onefile: Creates a single executable file.
   • --windowed: Prevents a console window from appearing when the app is run.
   • --name="POS_TioAdan": Sets the name of the output executable.
   • --hidden-import: Includes openpyxl and fpdf which might not be detected automatically.
3. Output: The final POS_TioAdan.exe is placed in the dist/ directory.

Sources: build_exe.bat

The following flowchart visualizes the build script's execution.

Conclusion

Contributing to the "POS Tio Adan" project involves understanding its two-part architecture: the monolithic Tkinter POS application and the separate Telegram notification service. Development requires setting up a Python environment and, for the notification service, configuring API credentials. Key areas for contribution include enhancing the GUI, adding new features to the POS logic in pos_app.py, improving the database interactions, or extending the capabilities of the notification service in notification_service.py. All changes to the POS application must be packaged using the provided build_exe.bat script for distribution.