Home

Relevant source files

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

• pos_app.py
• notification_service.py
• config.example.json
• test_telegram.py
• CLAUDE.md
• build_exe.bat
• build_notification_exe.bat
• requirements.txt
• README_Notifications.txt

This document provides a technical overview of the pos-tioadan project, a Point of Sale (POS) system designed for small retail operations. The system is built with Python, using tkinter for the graphical user interface and SQLite for data persistence. The project consists of two primary components: a monolithic desktop application for managing sales and inventory, and a separate, optional notification service that sends alerts via Telegram.

The core application (pos_app.py) handles all user-facing interactions, including sales processing, inventory management, and reporting. The notification service (notification_service.py) runs as a background process, monitoring the inventory database for events like zero-stock products and sending daily sales summaries. Both components interact with a central SQLite database, pos_inventory.db.

System Architecture

The system is composed of two distinct applications that share a common database. The POSApplication is the primary user interface, while the NotificationService operates in the background.

This diagram illustrates the high-level interaction between the system components.

POS Application

The main POS application is a single-file monolithic program (pos_app.py) that provides the complete user interface and business logic for sales and inventory management. It is built using Python's standard tkinter library.

Sources: pos_app.py, CLAUDE.md:10-12

Core Components

The application is structured into two main classes:

1. Database: A dedicated class that encapsulates all SQLite database operations for the pos_inventory.db file. It handles table creation, data insertion, updates, and queries.
2. POSApplication: The main class that builds and manages the tkinter GUI. It contains the logic for the different tabs (Sales, Inventory, etc.) and handles user events.

Sources: pos_app.py:18-654

Database Schema (pos_inventory.db)

The Database class manages a SQLite database (pos_inventory.db) with the following core tables.

This ER diagram shows the relationships between the main tables in the POS database.

Key Features and Workflows

The application provides several key features for retail management.

Sales Workflow

The sales process is initiated from the "Venta/Salida de Inventario" tab.

This flowchart outlines the steps involved in making a sale.

Inventory Management

The "Entrada y Busqueda de Inventario" tab allows for inventory management, including adding stock, editing products, and importing from XLSX files.

Feature	Description	Relevant Functions
Add Stock	Scan a product barcode to increment its quantity by one. If the product doesn't exist, a dialog prompts to create it.	scan_product_inventory(), increment_inventory_quantity()
Product Search	Search for products by partial or exact matches on internal code (Clave) or product barcode.	search_product()
Filtering	Filter the inventory view by category, brand, or out-of-stock status.	apply_filters()
XLSX Import	Bulk import or update products from an .xlsx file. The file must have specific columns like CLAVE, DESCRIPCION, P/VENTA.	import_from_xlsx()
Product Editing	Edit all fields of a selected product, including price, name, and quantity.	edit_product_full()
PDF Reports	Generate daily sales reports in PDF format, summarizing transactions, top-selling products, and out-of-stock items.	generate_sales_report_pdf()
Receipt Generation	After a sale, a receipt is generated in both text and PDF format. The last receipt can be reprinted.	generate_receipt(), generate_receipt_pdf()

Sources: pos_app.py

Telegram Notification Service

The notification service is a standalone Python script (notification_service.py) designed to run continuously in the background. It monitors the pos_inventory.db and sends alerts to a configured Telegram chat. It is packaged as TelegramNotifications.exe.

Sources: notification_service.py, README_Notifications.txt, build_notification_exe.bat

Architecture

The service is composed of several classes, each with a distinct responsibility.

This class diagram shows the structure of the notification service.

• NotificationService: The main orchestrator that starts and stops monitoring threads.
• POSDatabaseReader: Provides read-only access to the pos_inventory.db to fetch product and sales data.
• StateTracker: Manages a separate state database (notification_state.db) to prevent sending duplicate notifications.
• TelegramNotifier: Handles all communication with the Telegram Bot API.

Configuration

The service is configured via a config.json file. A test_telegram.py script is provided to validate the Telegram credentials.

Section	Key	Description
telegram	bot_token	The API token for the Telegram bot.
	chat_id	The ID of the Telegram chat to send notifications to.
polling	zero_stock_interval_seconds	How often (in seconds) to check for out-of-stock products. Default is 300.
daily_report	send_time	The time of day (e.g., "08:00") to send the daily report.
	timezone	The timezone for the report scheduler (e.g., "America/Mexico_City").
database	pos_db_path	Path to the main POS database. Default is pos_inventory.db.
	state_db_path	Path to the notification state database. Default is notification_state.db.
notifications	out_of_stock	Contains the enabled flag and message_template for zero-stock alerts.
	daily_report	Contains the enabled flag and message_template for daily sales reports.

Sources: config.example.json, notification_service.py:461-471, test_telegram.py:13-22

State Management (notification_state.db)

To avoid sending repeated alerts, the service uses a separate SQLite database (notification_state.db) to track its state.

This ER diagram shows the schema for the state-tracking database.

• notified_products: Stores products that have already triggered a zero-stock alert. Products are removed from this table if they are restocked.
• daily_report_log: Logs when a daily report was successfully sent for a given date.

Sources: notification_service.py:31-56, notification_service.py:126-146

Build and Deployment

The project includes batch scripts to package the Python applications into standalone Windows executables using PyInstaller.

• install_dependencies.bat: Installs required Python packages from requirements.txt.
• build_exe.bat: Builds the main POS application into dist/POS_TioAdan.exe. It is a windowed application.
• build_notification_exe.bat: Builds the notification service into dist/TelegramNotifications.exe. It is a console application.

The required dependencies for both applications are listed in requirements.txt.

# POS Application dependencies
fpdf2>=2.7.0
openpyxl>=3.1.0

# Notification Service dependencies (optional)
requests>=2.31.0
pytz>=2023.3

Sources: build_exe.bat, build_notification_exe.bat, install_dependencies.bat, requirements.txt