Configuration (config.json)

Relevant source files

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

• config.example.json
• notification_service.py
• test_telegram.py
• README_Notifications.txt
• install_dependencies.bat
• build_notification_exe.bat

Introduction

The config.json file is the central configuration hub for the Telegram Notification Service (notification_service.py), a standalone component of the POS Tio Adan project. This file is not used by the main graphical POS application (pos_app.py). Its primary purpose is to externalize all operational parameters, credentials, and settings, allowing the notification service to be configured and deployed without any code modifications.

The service relies on this file to define its connection to the Telegram API, specify the location of the databases it monitors, control the frequency of its monitoring tasks, and customize the content of the notifications it sends. A template file, config.example.json, is provided in the repository, which must be copied and renamed to config.json and filled with the appropriate values before the service can run.

Sources: notification_service.py:469-478, README_Notifications.txt:10-15, install_dependencies.bat:37-47

Configuration Loading

The NotificationService class loads the config.json file upon instantiation. If the file is not found or contains invalid JSON, the service will fail to start and exit with an error message.

This diagram shows the loading process:

The core loading logic is handled by the _load_config method in the NotificationService class.

# notification_service.py:470-478
    def _load_config(self, config_path):
        """Load configuration from JSON file"""
        try:
            with open(config_path, 'r', encoding='utf-8') as f:
                return json.load(f)
        except FileNotFoundError:
            print(f"Error: Configuration file '{config_path}' not found!")
            print("Please copy config.example.json to config.json and configure your settings.")
            sys.exit(1)

Sources: notification_service.py:470-478

Configuration Parameters

The config.json file is structured into several key objects. The following table details each parameter found in config.example.json.

Section	Key	Type	Description	Default Value
telegram	bot_token	string	The API token for the Telegram bot, obtained from @BotFather.	"123...-EXAMPLE"
telegram	chat_id	string	The unique identifier for the target chat where notifications will be sent.	"123456789"
polling	zero_stock_interval_seconds	integer	The interval in seconds for how often the service checks for out-of-stock products.	300
polling	health_check_interval_seconds	integer	The interval in seconds for the service to log a health check message.	60
daily_report	send_time	string	The time of day (HH:MM format) to send the daily sales report.	"08:00"
daily_report	timezone	string	The IANA timezone for scheduling the daily report (e.g., "America/Mexico_City").	"America/Mexico_City"
daily_report	top_products_count	integer	The number of top-selling products to include in the daily report.	10
daily_report	metric	string	The metric to determine top products ('quantity' or 'revenue').	"quantity"
database	pos_db_path	string	The file path to the main POS inventory database.	"pos_inventory.db"
database	state_db_path	string	The file path for the service's state-tracking database.	"notification_state.db"
logging	log_level	string	The minimum level of logs to record (e.g., "INFO", "DEBUG").	"INFO"
logging	log_file	string	The path for the main service log file.	"logs/notification_service.log"
logging	error_log_file	string	The path for the file that only logs errors.	"logs/notification_errors.log"
logging	max_bytes	integer	The maximum size in bytes for a log file before it rotates.	10485760
logging	backup_count	integer	The number of old log files to keep.	5
notifications	out_of_stock	object	Contains settings for out-of-stock alerts.	See below
notifications	daily_report	object	Contains settings for daily report notifications.	See below

Sources: config.example.json

telegram

This section contains the credentials for the Telegram bot. The test_telegram.py script is provided to verify these settings.

Sources: test_telegram.py, config.example.json:2-5

polling

This object controls the timing of the service's background monitoring threads.

• zero_stock_interval_seconds: Used by the zero_stock_monitor thread to determine how long to wait between checks of the products table for items with a quantity of 0.
• health_check_interval_seconds: Used by the health_monitor thread to periodically log a status message, confirming the service is still running.

Sources: notification_service.py:532, notification_service.py:620, config.example.json:6-9

daily_report

This section configures the automated daily sales report. The daily_report_scheduler thread uses these values to determine when and what to send.

• send_time and timezone: Define the exact time the report for the previous day should be generated and sent.
• top_products_count and metric: Control the data query for top-selling products, allowing customization of the report's content.

Sources: notification_service.py:560-563, notification_service.py:590-594, config.example.json:10-15

database

This section defines the paths to the SQLite databases used by the service.

• pos_db_path: The path to the main application's database (pos_inventory.db). The service reads product and sales data from here.
• state_db_path: The path to a separate database (notification_state.db) created and managed by the notification service. It stores which out-of-stock products have already been reported to avoid sending repeated alerts.

Sources: notification_service.py:22, notification_service.py:221, config.example.json:16-19

logging

Configures the Python logging module, specifically using RotatingFileHandler to manage log file size and rotation.

Sources: notification_service.py:491-522, config.example.json:20-26

notifications

This section contains the message templates for the different alert types.

out_of_stock

• enabled: A boolean to globally enable or disable out-of-stock alerts.
• message_template: A string with placeholders ({name}, {barcode}, etc.) that are dynamically replaced with product data before sending the notification.

# notification_service.py:410-418
    def send_out_of_stock_alert(self, product):
        """Send zero-stock alert notification"""
        if not self.templates['out_of_stock']['enabled']:
            return None

        template = self.templates['out_of_stock']['message_template']
        message = template.format(
            name=product.get('name', 'N/A'),
            barcode=product.get('barcode', 'N/A'),
            # ... other fields
        )
        return self.send_message(message)

Sources: notification_service.py:410-423, config.example.json:28-32

daily_report

• enabled: A boolean to globally enable or disable the daily sales report.
• message_template: A template for the daily report summary, with placeholders for the date, product list, and sales totals.

Sources: notification_service.py:425-452, config.example.json:33-37

Conclusion

The config.json file is a critical component for the operation of the Telegram Notification Service. It effectively decouples the service's logic from its environment-specific settings, such as API keys, database locations, and user preferences for notification timing and content. This design, centered around a simple JSON file, makes the service portable, easy to configure for non-developers, and maintainable without requiring changes to the Python source code. The inclusion of config.example.json and helper scripts like test_telegram.py further simplifies the setup process for end-users.