Amul Stock Bot (V2)

A containerized restock monitoring service.

This project polls the external API of Amul's online store on a fixed interval, keeps persistent state in SQLite, and sends notifications only on real stock transitions (out → in) and (in → out). It’s designed as a long-running service with explicit configuration, clear separation of concerns, and predictable behavior under restarts and failures.

This is a system rewrite of an earlier prototype. The focus here is correctness, operability, and discipline rather than speed or cleverness.

---

Core ideas

• Persistent state (no fake alerts on restart)
• Transition-based notifications, not level-based spam
• Explicit intent (what to track is configured, not inferred)
• One process, one loop, no cron
• Docker as the runtime and supervisor

---

Architecture (high level)

• ingest_items.py One-time / occasional configuration. Inserts or updates items to track.

• amul.py Long-running controller. Polls the API, compares state, calls notify.

• SQLite Durable memory. Tracks items, current state, and history.

• Docker + docker-compose Reproducible runtime, restart on crash, no host Python required.

---

---

Notifications

Notifications are sent using ntfy.

When a restock is detected, the service publishes a message to a single ntfy topic via an HTTP POST. Any client subscribed to that topic will receive the alert.

Transport: ntfy (public HTTP)

Semantics: best-effort

Notification failures do not stop the watcher

Default topic in this repo: amulstockbot-qwerty

You can view notifications by:

opening https://ntfy.sh/amulstockbot-qwerty in a browser, or

subscribing to the topic in the ntfy mobile app.

The topic name is configurable via the NTFY_TOPIC environment variable. The topic used in this repository is public and unprotected; for personal use, you should change it to an unguessable value.

---

Prerequisites

• Docker
• Docker Compose

Nothing else is required on the host.

---

Runbook (how to run this)

1. Clone the repo

git clone https://github.com/adot-7/amulstockbot-v2.git
cd amulstockbot-v2

2. Create data directory (persistent storage)

mkdir data

This directory holds the SQLite database. Deleting it resets all state.

---

3. Build the image

docker compose build

Run again only if code or dependencies change.

---

4. Ingest items (explicit step)

docker compose run --rm watcher python ingest_items.py

This:

• runs ingestion inside Docker
• populates the database in data/
• exits cleanly

Run this whenever you want to add or update tracked items.

---

5. Start the watcher

docker compose up -d

The service now runs continuously.

• Survives crashes
• Survives VM reboots
• Keeps state across restarts

---

6. View logs

docker logs -f amul-stock-bot

---

7. Check Items table

sqlite3 data/state_and_history.db

SELECT *
FROM items
.quit

---

---

8. Enable / disable notifications for an item

sqlite3 data/state_and_history.db

UPDATE items
SET notify_enabled = 1
WHERE sku = 'DBDCP45_02';

UPDATE items
SET notify_enabled = 0
WHERE sku = 'DBDCP45_01';
.quit

Changes apply on the next poll cycle.

---

9. Inspect history

sqlite3 data/state.db

SELECT *
FROM history;
.quit

---

10. Stop the service

docker compose down

State is preserved.

---

Configuration

All configuration is done via environment variables in docker-compose.yml, including:

• poll interval
• database path
• notification parameters

No hardcoded values are required.

---

Notes

• This project intentionally avoids frameworks, brokers, and schedulers.
• Notifications are treated as best-effort side effects.
• If there are no items configured, the watcher will refuse to run.

---

License

MIT License.