How swapnilsoni1999/amul-notify works
Project Type and Purpose
• This is a single-service, full-stack Node.js application implementing a Telegram bot (“Amul Stock Notification Bot”).
• Purpose: Listen to Telegram commands, fetch stock data from Amul’s public API, let users browse/track products, schedule periodic checks, and send notifications.
File Structure Analysis
• src/app.ts & src/server.ts: Entry points—initializes bot, Express server, scheduler, and database/cache connections.
• src/bot.ts: Configures Telegraf.js with commands, middlewares, wizards.
• src/commands/: Command handlers (e.g., /start, /products, /tracked).
• src/actions/ & src/wizards/: Complex multi-step interactions (inline button handlers, step-by-step flows).
• src/services/: Business logic services (user, amul, track, broadcast, analytics, cache).
• src/models/: Mongoose schemas for MongoDB (User, Product, Activity, Boundary, StockHistory).
• src/queues/: Job queues (Redis-backed) for broadcast or background tasks.
• src/jobs/: Cron-driven background jobs (stock checker, activity reporter).
• src/libs/ & src/utils/: Thin wrappers and shared utilities (HTTP API client, date handling, logging, emoji, formatters).
• Configuration & infra:
• .env files for secrets (Telegram token, MongoDB URI, Redis URL).
• Dockerfile & .github/workflows/deploy.yml for containerized builds & CI/CD.
• PM2/Docker orchestration recommended (see README).
README Insights
• Tech stack: Node.js + TypeScript, Telegraf.js, MongoDB (via Mongoose), Redis (cache + queue), Axios, node-cron, PM2, Docker.
• Features: real-time checks every 3–5 minutes, user-driven pincode scoping, inline Telegram interface.
• External integration: Amul’s public API (via amulApi.lib.ts).
Architectural Components & Interactions
a. User & Telegram Layer
• Users ↔ Telegram clients (mobile/desktop) ↔ Telegram Bot API
b. Bot Server
• Telegraf Bot Instance (handles incoming updates, routes to command handlers and middlewares)
• Express HTTP Server (optional for health checks, webhooks if used)
c. Application Core
• Command Handlers & Wizards → orchestrate requests to services
• Middlewares (analytics, rate limiting, session, admin guard)
• Actions (stateful UI updates via inline buttons)
d. Service Layer
• AmulService → fetch product data from Amul API
• TrackService → register/unregister user tracking
• BroadcastService → enqueue global messages
• AnalyticsService → record usage metrics
• CacheService → read/write from Redis cache
e. Data & Persistence
• MongoDB (persistent storage for users, tracked items, product & stock history, boundaries)
• Redis (caching frequently read data, supporting job queues)
f. Background Processing
• Cron Jobs (checker.job.ts, activityReport.job.ts) → run every N minutes, call service layer, enqueue notifications
• Queues (e.g., Bull or custom Redis queue) → decouple broadcast & heavy tasks
g. External Systems
• Amul Public API (via Axios)
• Telegram Bot API (sendMessage, editMessage, etc.)