Component Interaction

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
• README_Notifications.txt
• CLAUDE.md

This document outlines the interaction between the main Point of Sale (POS) application and the external Telegram notification service. The system is designed with a core monolithic POS application responsible for all sales and inventory management, and a decoupled notification service that monitors the POS database for specific events, such as products running out of stock.

The primary point of interaction is the shared SQLite database, pos_inventory.db. The POS application has read/write access, while the notification service performs read-only operations to gather data for alerts. A separate state database, notification_state.db, is used exclusively by the notification service to prevent duplicate alerts. Configuration is managed via config.json, which acts as the glue between these components.

System Architecture

The overall architecture consists of two main, independent processes that share a common database.

1. POS Application (pos_app.py): A monolithic Tkinter GUI application that handles all user-facing operations, including sales, inventory updates, and reporting. It directly modifies the pos_inventory.db.
2. Notification Service (notification_service.py): A standalone Python script that runs as a background service. It periodically polls pos_inventory.db for changes and sends alerts via the Telegram API.

The diagram below illustrates the high-level interaction between these components.

This diagram shows that pos_app.py writes to pos_inventory.db, while notification_service.py reads from it and writes to its own state database before sending messages to the Telegram API.
Sources: pos_app.py, notification_service.py, README_Notifications.txt

Component Responsibilities

Component	File	Description
POSApplication	pos_app.py	The main Tkinter GUI application. Manages user interaction for sales, inventory management, and report generation.
Database	pos_app.py	Handles all direct SQLite read/write operations on pos_inventory.db for the POSApplication.
NotificationService	notification_service.py	The main orchestrator for the notification system. Runs monitoring tasks in separate threads.
POSDatabaseReader	notification_service.py	Provides read-only access to pos_inventory.db for the notification service.
StateTracker	notification_service.py	Manages notification_state.db to track sent alerts and prevent duplicates.
TelegramNotifier	notification_service.py	Formats and sends messages to the Telegram API using credentials from config.json.

Sources: pos_app.py:588-591, notification_service.py:708-718

Data Layer Interaction

The two systems are decoupled at the application layer but coupled at the data layer through the pos_inventory.db file. The notification service also maintains its own private database, notification_state.db.

Database Schemas

The following ER diagram shows the tables in both databases and their relationships.

This diagram illustrates that pos_inventory.db contains core business data, while notification_state.db is used solely by the notification service for its operational state.
Sources: pos_app.py:28-111, notification_service.py:40-70

POS Application Data Flow (Sale Process)

When a sale is completed in the POSApplication, it follows a sequence of database interactions to update inventory and record the transaction.

This sequence shows the checkout function orchestrating calls to the Database class to get a new folio number, update product quantities, and record each sale item.
Sources: pos_app.py:1650-1685

Notification Subsystem

The notification service runs independently and is configured via config.json. It does not interact directly with the POS application code but reads from its database.

Configuration

The config.json file is crucial for defining the behavior and connectivity of the notification service.

Section	Key	Description	Default Value
telegram	bot_token	The API token for the Telegram bot.	123...-EXAMPLE
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
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
notifications	out_of_stock.enabled	Toggles the out-of-stock alerts.	true
notifications	out_of_stock.message_template	The template for out-of-stock alert messages.	"⚠️ ALERTA: ..."
daily_report	send_time	The time of day to send the daily report (HH:MM).	"08:00"

Sources: config.example.json:1-36

Zero-Stock Monitoring Flow

The zero_stock_monitor thread is a core feature of the notification service. It periodically checks for products with a quantity of zero and sends an alert if it hasn't already done so for that product.

This flow demonstrates how the service uses both pos_inventory.db (to get stock levels) and notification_state.db (to check notification status) to decide whether to send an alert.
Sources: notification_service.py:734-751

The interaction with the Telegram API is handled by the TelegramNotifier class, which makes HTTP POST requests to the sendMessage endpoint.

# Source: notification_service.py:461-466
def send_message(self, text, parse_mode='Markdown'):
    """Send a message via Telegram with retry logic"""
    url = f"{self.base_url}/sendMessage"
    data = {
        "chat_id": self.chat_id,
        "text": text,
        "parse_mode": parse_mode
    }

The test_telegram.py script confirms this interaction pattern by sending a pre-formatted test message to the configured chat ID.
Sources: notification_service.py:461-466, test_telegram.py:64-71

Summary

The pos-tioadan project is composed of two primary, decoupled components: a GUI-based POS application and a command-line notification service. The main point of interaction is the pos_inventory.db SQLite database, which the POS application actively manages and the notification service passively monitors. This design allows the notification service to be deployed, updated, or run independently of the main sales terminal, providing resilience and flexibility. The config.json file serves as the essential link, enabling the notification service to locate the shared database and connect to the external Telegram API.