Skip to content
activeBackendStarted: Sep 10, 2026

WA Reminder Companion: Headless Due Notification Bridge

A lightweight, headless automation daemon that sends scheduled due payment reminders and invoice receipts to retail pharmacy clients with zero paid API overhead.

View Source

Technology Stack

PythonPlaywrightFastAPISQLitesystemd

My Role

Solo Developer

System Architecture
  1. 1POS Due Ledger Webhook
  2. 2SQLite Transaction Queue
  3. 3Rate-Limiting & Jitter Scheduler
  4. 4Headless Browser Controller
  5. 5Telegram Audit Dispatcher
  • 1POS Due Ledger Webhook──▶2SQLite Transaction Queue
  • 2SQLite Transaction Queue──▶3Rate-Limiting & Jitter Scheduler
  • 3Rate-Limiting & Jitter Scheduler──▶4Headless Browser Controller
  • 4Headless Browser Controller──▶5Telegram Audit Dispatcher

Overview

Official business messaging APIs typically charge per-template conversation fees ($0.05–$0.08 per message), which quickly becomes prohibitive for small rural pharmacies and SME retailers who need to notify 400+ customers each month regarding overdue store balances.

WA Reminder Companion is an automated microservice designed to act as an un-metered notification dispatcher. It runs as a resilient Linux systemd background service, listens for invoice due triggers from local POS systems, and dispatches courteous, formatted reminder messages with PDF receipts.

Key Design Principles

  • Idempotency by Default: Every reminder job carries a unique hash based on (invoice_id, customer_id, due_month). Even if the POS sends duplicate webhook triggers, each customer receives at most one reminder per billing cycle.
  • Human Jitter & Rate Limiting: Rather than blasting bulk messages simultaneously, the dispatcher injects random jitter delays (18 to 45 seconds between messages) to ensure polite delivery.
  • Fail-Safe Audit Logging: Dispatched messages, delivery timestamps, and failure events are captured in an append-only SQLite database and mirrored to a private Telegram channel for instant operator visibility.

Interactive Source Explorer & Live CLI Sandbox

Browse source implementation and execute in-browser sandbox simulation.

GitHub Repo
$python -m wa_companion.cli --due-days 7 --dry-run
Source Tree (1 Files)
dispatcher.pypython
import time
import random

def dispatch_reminder(customer: str, amount_due: float, dry_run: bool = True):
    jitter = random.uniform(15.0, 45.0)
    print(f"Holding for {jitter:.1f}s jitter before notifying {customer}...")
    if not dry_run:
        # headless browser dispatch
        pass

Project Changelog

Queue Design

Built the SQLite-backed task queue with exponential backoff and idempotency keys.

Headless Session Persistence

Implemented secure user-data-dir encryption and QR-reconnect alerting via Telegram.

Knowledge Graph

Timeline

PreviousKhata2Sheet AI: Local OCR & Bengali Ledger DigitizerNextS.A.R.A. Task Control Plane & Telegram Relay

Conceptually Related

S.A.R.A. Task Control Plane & Telegram RelayVia: Python, FastAPI, SQLite...NetPulse TG — ISP Watchdog & Telegram Incident RelayVia: Python, FastAPI, DevOps...Khata2Sheet AI: Local OCR & Bengali Ledger DigitizerVia: Python, FastAPI, Python...StudyOS (Local AI Prototype)Via: Python, FastAPI, Python...