Data Flow

Relevant source files

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

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

The data flow in the pos-tioadan project is centered around a primary SQLite database, pos_inventory.db, which serves as the single source of truth for inventory and sales data. The system is composed of two main components: a monolithic desktop GUI application for direct user interaction (pos_app.py) and a separate, standalone notification service (notification_service.py) that monitors the database asynchronously to send alerts.

Data is primarily generated and modified through the GUI application during sales and inventory management tasks. The notification service operates in a read-only capacity on the main database, using its own state-tracking database (notification_state.db) to manage alerts and prevent duplicates. This decoupled architecture allows the core POS functionality to operate independently while enabling automated, real-time monitoring and reporting.

Core Application Data Flow (pos_app.py)

The main application, built with tkinter, handles all direct data manipulation within the pos_inventory.db database. All database operations are executed via direct SQLite connections managed by the Database class.

Sources: pos_app.py, CLAUDE.md

Database Schema (pos_inventory.db)

The application's data is persisted in a SQLite database file named pos_inventory.db. It contains tables for products, sales, and internal counters.

The following diagram illustrates the schema of the main database.

Sales Transaction Flow

A sale is initiated by scanning a product barcode in the "Venta/Salida de Inventario" tab. The application searches for the product, adds it to an in-memory cart, and upon checkout, updates the database.

The sequence diagram below details the data flow during a typical sales transaction.

Inventory Management Flow

Inventory can be managed in two primary ways: by scanning products to increment their quantity or by importing products in bulk from an XLSX file.

1. Incrementing Stock

In the "Entrada y Busqueda de Inventario" tab, scanning a barcode triggers a search. If the product exists, its quantity is incremented by one. If not, the user is prompted to create a new product.

Sources: pos_app.py:1894-1943

2. XLSX Bulk Import

The application supports bulk import of products from an XLSX file. The import_from_xlsx function reads the file, validates each row, and either creates a new product or updates an existing one based on the CLAVE (barcode).

The expected XLSX file format is as follows:

Column	Header	Description	Required
A	CLAVE	The internal product barcode (unique identifier).	Yes
B	DESCRIPCION	The product name.	Yes
C	COSTO	The cost of the product.	No (defaults to 0)
D	P/VENTA	The selling price of the product.	Yes
E	CANTIDAD	The stock quantity.	No (defaults to 0)
F	CATEGORIA	The product category.	No (defaults to 'General')
G	MARCA	The product brand.	No (defaults to 'General')
H	CODIGO DE BARRAS	The manufacturer's barcode.	No (defaults to empty)

Sources: pos_app.py:1700-1823

The following flowchart illustrates the XLSX import logic.

Notification Service Data Flow (notification_service.py)

A separate service, notification_service.py, runs in the background to monitor the pos_inventory.db and send alerts via Telegram. It uses its own database, notification_state.db, to track sent notifications and avoid duplicates.

Architecture Overview

The service is composed of several classes that work together to read data, manage state, and send notifications.

This diagram shows the main components of the notification service and their interactions with external databases and APIs.

Sources: notification_service.py:440-450

State Management (notification_state.db)

To prevent sending repeated alerts, the service maintains a state database. This database logs which products have been flagged as out-of-stock and which daily reports have been sent.

Zero-Stock Alert Flow

The service periodically polls the pos_inventory.db for products with zero quantity. If a new out-of-stock product is found, it sends a Telegram notification and records the event in notification_state.db.

Daily Sales Report Flow

The service is scheduled to send a daily sales summary at a configured time. It queries the previous day's sales data, formats a report, and sends it via Telegram.

Conclusion

The project's data flow is characterized by a clear separation of concerns. The pos_app.py GUI application handles synchronous, user-driven data entry and modification for sales and inventory. In parallel, the notification_service.py acts as an independent, asynchronous monitor that consumes data from the shared pos_inventory.db to provide automated alerts and reports. This design ensures that the core POS functionality remains fast and responsive, while value-added services like notifications operate without impacting the user-facing application. The use of a separate state database (notification_state.db) is a key architectural choice that makes the notification service robust and prevents alert fatigue.

Sources: CLAUDE.md, pos_app.py, notification_service.py