Pombot - Finance & Store Management Bot

Automated Sales, Expenses & Inventory Management System for pgoriginal.com.

---

Architecture & Design Principles

🧩 Key Patterns Implemented

• Layered Architecture: Strict separation of concerns:
  • Handlers (handlers/): Telegram interaction & state management (Controller).
  • Services (services/): Business logic & data integration (Model).
  • Lambdas (lambdas/): Background tasks & webhooks (Async Workers).
• Dependency Injection: Service dependencies are injected or factored out to allow easy mocking during tests.
• Factory Pattern: Centralized creation of complex test objects (tests/helpers/telegram_factories.py) ensuring consistent test data.
• Async/Await: Fully asynchronous core to handle high-concurrency Telegram updates efficiently.

Features & Capabilities

1. 📊 Comprehensive Management

• Sales & Wholesale: Record transactions, manage payments (partial/full), and track inventory.
• Expenses: Categorized expense tracking (Suppliers, Services, Personal) with sub-category logic.
• Debts: Track and update outstanding debts with modification flows.

2. 🔄 Background Synchronization (Lambda)

• TiendaNube Sync: Automatically syncs product stock and prices from TiendaNube to Google Sheets.
• Webhooks: Real-time order processing (Order Paid -> Record Sale).
• Scheduler: Daily expiration checks for Checks and Future Payments, sending Telegram alerts.

3. 🛡️ Robust Testing Suite

• Unit Tests: >75% coverage across all modules.
• Mocking: Extensive use of unittest.mock to isolate business logic from external APIs (Telegram, Google Sheets).
• Regression: Dedicated suite to prevent re-occurrence of critical bugs.

Project Structure

├── handlers/               # 📍 Telegram Handlers (Controllers)
│   ├── sales.py            #    - Sales Flow
│   ├── expenses.py         #    - Expense Tracking
│   ├── wholesale.py        #    - Wholesale & Payments
│   └── ...
├── services/               # 🧠 Business Logic
│   ├── products_service.py #    - Inventory & Options
│   ├── sheets_connectio... #    - Database
│   └── ...
├── lambdas/                # ⚡ AWS Lambda Functions
│   ├── lambda_sync.py      #    - Config & Sync Logic
│   └── webhook_handler.py  #    - Event Processing
├── config/                 # ⚙️ Configuration
│   ├── settings.py         #    - Env Vars & Secrets
│   └── definitions.py      #    - Business Constants
├── common/                 # 🔧 Shared Utilities
│   └── utils.py            #    - Parsing & Formatting
├── tests/                  # 🧪 Test Suite
│   ├── unit/               #    - Unit Tests
│   ├── integration/        #    - Flow Tests
│   └── helpers/            #    - Test Factories
└── requirements.txt        # 📦 Dependencies

Setup & Execution

Prerequisites

• Python 3.12+
• Google Service Account (JSON)
• AWS Credentials (Secrets Manager)

Installation

git clone https://github.com/MiltonKlun/Pombot_PG_Original.git
cd Pombot_PG_Original
python -m venv venv
# Windows
venv\Scripts\activate
# Mac/Linux
source venv/bin/activate

pip install -r requirements.txt

Running Tests

Run All Tests:

pytest tests/

Run Coverage Report:

scripts/run_coverage.bat

📑 Reports & Logs

• Coverage: Generated in htmlcov/
• Logs: System logs in error.log

---

Author

Milton Klun
QA Automation Engineer | Backend Developer