# swapnilsoni1999/amul-notify architecture

> Architecture diagram of the GitHub repository swapnilsoni1999/amul-notify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swapnilsoni1999/amul-notify
- Repository: https://github.com/swapnilsoni1999/amul-notify

## Overview

##### 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.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User (Telegram Client)"]:::external
    TelegramAPI["Telegram Bot API"]:::external

    subgraph "Bot Server (Node.js Container)"
        direction TB
        AppInit["Init (app.ts & server.ts)"]:::core
        BotConfig["Bot Config (Telegraf)"]:::core
        ExpressServer["Express HTTP Server"]:::core

        subgraph "Presentation Layer"
            direction TB
            Cmd["Command Handlers"]:::core
            Act["Actions"]:::core
            Wiz["Wizards"]:::core
            Mid["Middlewares"]:::core
        end

        subgraph "Service Layer"
            direction TB
            AmulSvc["AmulService"]:::core
            TrackSvc["TrackService"]:::core
            BroadcastSvc["BroadcastService"]:::core
            AnalyticsSvc["AnalyticsService"]:::core
            CacheSvc["CacheService"]:::core
            UserSvc["UserService"]:::core
            ActivitySvc["ActivityService"]:::core
        end

        subgraph "Background Processing"
            direction TB
            Scheduler["Cron Jobs"]:::utility
            Queue["Queue Worker"]:::utility
        end

        RedisConn["Redis Connection"]:::data
        Models["Data Models"]:::data
    end

    Mongo["MongoDB"]:::data
    Redis["Redis"]:::data
    AmulAPI["Amul Public API"]:::external

    User --> TelegramAPI --> BotConfig --> Cmd
    BotConfig --> Mid
    Cmd --> AmulSvc
    Cmd --> TrackSvc
    Cmd --> BroadcastSvc
    Act --> TrackSvc
    Wiz --> UserSvc
    Mid --> AnalyticsSvc

    AmulSvc --> Redis
    AmulSvc --> AmulAPI
    TrackSvc --> Mongo
    BroadcastSvc --> Queue
    AnalyticsSvc --> Mongo
    CacheSvc --> Redis
    UserSvc --> Mongo
    ActivitySvc --> Mongo

    Scheduler -.-> AmulSvc
    Scheduler -.-> ActivitySvc
    Scheduler --> Queue
    Queue -->|"Process Jobs"| TelegramAPI

    RedisConn --> Redis
    Models --> Mongo

    click AppInit "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/app.ts"
    click AppInit "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/server.ts"
    click BotConfig "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/bot.ts"
    click Cmd "https://github.com/swapnilsoni1999/amul-notify/tree/main/src/commands/"
    click Act "https://github.com/swapnilsoni1999/amul-notify/tree/main/src/actions/"
    click Wiz "https://github.com/swapnilsoni1999/amul-notify/tree/main/src/wizards/"
    click Mid "https://github.com/swapnilsoni1999/amul-notify/tree/main/src/middlewares/"
    click AmulSvc "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/services/amul.service.ts"
    click TrackSvc "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/services/track.service.ts"
    click BroadcastSvc "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/services/broadcast.service.ts"
    click AnalyticsSvc "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/services/analytics.service.ts"
    click CacheSvc "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/services/cache.service.ts"
    click UserSvc "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/services/user.service.ts"
    click ActivitySvc "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/services/activity.service.ts"
    click Scheduler "https://github.com/swapnilsoni1999/amul-notify/tree/main/src/jobs/"
    click Queue "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/queues/broadcast.queue.ts"
    click RedisConn "https://github.com/swapnilsoni1999/amul-notify/blob/main/src/redis.ts"
    click Models "https://github.com/swapnilsoni1999/amul-notify/tree/main/src/models/"

    classDef external fill:#D6EAF8,stroke:#85C1E9
    classDef core fill:#D5F5E3,stroke:#27AE60
    classDef data fill:#FCF3CF,stroke:#F4D03F
    classDef utility fill:#E5E7E9,stroke:#ABB2B9
```
