# aleg94/pricegram architecture

> Architecture diagram of the GitHub repository aleg94/pricegram, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aleg94/pricegram
- Repository: https://github.com/aleg94/pricegram

## Overview

Pricegram is a Telegram bot for tracking Amazon product prices and availability. Users add products through /track, then manage them with /list; a background poller checks saved products and the application sends preference-based alerts. The graph separates Telegram interaction, product retrieval, tracking and alerts, and persistence. Relationships for the main runtime are supported by excerpts and README statements; some unsampled modules are represented by their exact tree paths, with uncertain calls omitted.

Main entry points: [`lib/models/product.model.js`](https://github.com/aleg94/pricegram/blob/master/lib/models/product.model.js) (Product model), [`lib/bot/actions`](https://github.com/aleg94/pricegram/tree/master/lib/bot/actions) (Product actions), [`lib/bot/index.js`](https://github.com/aleg94/pricegram/blob/master/lib/bot/index.js) (Bot runtime), [`lib/price-tracker/handler.js`](https://github.com/aleg94/pricegram/blob/master/lib/price-tracker/handler.js) (Product check handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram interaction"]
  node_bot["Bot runtime<br/>[index.js]"]
  node_commands["Command registry<br/>[index.js]"]
  node_track_command["Track command<br/>[track.js]"]
  node_list_command["List command<br/>[list.js]"]
  node_add_scene["Add product flow<br/>[add-product.js]"]
  node_target_scene["Target price flow"]
  node_actions["Product actions"]
  node_list_action["List action<br/>[list.js]"]
  node_menu_action["Menu action<br/>[menu.js]"]
  node_remove_action["Remove action<br/>[remove.js]"]
  node_price_action["Price action<br/>[price.js]"]
  node_availability_action["Availability action<br/>[availability.js]"]
  node_menu_keyboard["Product menu<br/>[menu.js]"]
end

subgraph group_amazon["Amazon product retrieval"]
  node_http["Page fetcher<br/>[http.js]"]
  node_amazon_page["Amazon page parser"]
  node_validator["URL validator<br/>[validator.js]"]
end

subgraph group_tracking["Tracking and alerts"]
  node_tracker["Tracker coordinator<br/>[index.js]"]
  node_polling["Polling scheduler<br/>[polling.js]"]
  node_handler["Product check handler<br/>[handler.js]"]
  node_alert["Alert formatter<br/>[alert.js]"]
end

subgraph group_persistence["Persistence"]
  node_database["Database connector<br/>[database.js]"]
  node_product[("Product model<br/>[product.model.js]")]
end

node_user(("Telegram user"))
node_mongo[("MongoDB")]
node_telegram_api["Telegram API"]

node_user -->|"sends commands"| node_bot
node_bot -->|"dispatches commands"| node_commands
node_bot -->|"dispatches actions"| node_actions
node_bot -->|"sends messages"| node_telegram_api
node_commands -->|"registers"| node_track_command
node_commands -->|"registers"| node_list_command
node_track_command -->|"starts flow"| node_add_scene
node_list_command -->|"queries products"| node_product
node_list_command -->|"renders options"| node_menu_keyboard
node_actions -->|"dispatches"| node_list_action
node_actions -->|"dispatches"| node_menu_action
node_actions -->|"dispatches"| node_remove_action
node_actions -->|"dispatches"| node_price_action
node_actions -->|"dispatches"| node_availability_action
node_list_action -->|"queries products"| node_product
node_menu_action -->|"queries products"| node_product
node_menu_action -->|"renders options"| node_menu_keyboard
node_remove_action -->|"deletes product"| node_product
node_price_action -->|"starts flow"| node_target_scene
node_availability_action -->|"updates preference"| node_product
node_add_scene -->|"saves product"| node_product
node_add_scene -->|"fetches page"| node_http
node_add_scene -->|"parses page"| node_amazon_page
node_add_scene -->|"validates URL"| node_validator
node_target_scene -->|"updates target"| node_product
node_tracker -->|"starts polling"| node_polling
node_tracker -->|"registers checks"| node_handler
node_polling -->|"dispatches results"| node_handler
node_handler -->|"fetches page"| node_http
node_handler -->|"parses page"| node_amazon_page
node_handler -->|"updates record"| node_product
node_database -->|"connects"| node_mongo
node_handler -->|"emits update"| node_alert
node_alert -->|"formats alert"| node_bot
node_bot -->|"delivers alert"| node_user

click node_bot "https://github.com/aleg94/pricegram/blob/master/lib/bot/index.js"
click node_commands "https://github.com/aleg94/pricegram/blob/master/lib/bot/commands/index.js"
click node_track_command "https://github.com/aleg94/pricegram/blob/master/lib/bot/commands/track.js"
click node_list_command "https://github.com/aleg94/pricegram/blob/master/lib/bot/commands/list.js"
click node_add_scene "https://github.com/aleg94/pricegram/blob/master/lib/bot/scenes/add-product.js"
click node_target_scene "https://github.com/aleg94/pricegram/blob/master/lib/bot/scenes/set-target-price.js"
click node_actions "https://github.com/aleg94/pricegram/tree/master/lib/bot/actions"
click node_list_action "https://github.com/aleg94/pricegram/blob/master/lib/bot/actions/list.js"
click node_menu_action "https://github.com/aleg94/pricegram/blob/master/lib/bot/actions/menu.js"
click node_remove_action "https://github.com/aleg94/pricegram/blob/master/lib/bot/actions/remove.js"
click node_price_action "https://github.com/aleg94/pricegram/blob/master/lib/bot/actions/price.js"
click node_availability_action "https://github.com/aleg94/pricegram/blob/master/lib/bot/actions/availability.js"
click node_menu_keyboard "https://github.com/aleg94/pricegram/blob/master/lib/bot/keyboards/menu.js"
click node_http "https://github.com/aleg94/pricegram/blob/master/lib/helpers/http.js"
click node_amazon_page "https://github.com/aleg94/pricegram/blob/master/lib/amazon/amazon-product-page.js"
click node_validator "https://github.com/aleg94/pricegram/blob/master/lib/helpers/validator.js"
click node_tracker "https://github.com/aleg94/pricegram/blob/master/lib/price-tracker/index.js"
click node_polling "https://github.com/aleg94/pricegram/blob/master/lib/price-tracker/polling.js"
click node_handler "https://github.com/aleg94/pricegram/blob/master/lib/price-tracker/handler.js"
click node_alert "https://github.com/aleg94/pricegram/blob/master/lib/templates/alert.js"
click node_database "https://github.com/aleg94/pricegram/blob/master/lib/database.js"
click node_product "https://github.com/aleg94/pricegram/blob/master/lib/models/product.model.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bot,node_commands,node_track_command,node_list_command,node_add_scene,node_target_scene,node_actions,node_list_action,node_menu_action,node_remove_action,node_price_action,node_availability_action,node_menu_keyboard,node_user toneBlue
class node_http,node_amazon_page,node_validator,node_mongo toneAmber
class node_tracker,node_polling,node_handler,node_alert,node_telegram_api toneMint
class node_database,node_product toneRose
```

## Components

### Telegram interaction

- [Bot runtime](https://github.com/aleg94/pricegram/blob/master/lib/bot/index.js): `lib/bot/index.js`
- [Command registry](https://github.com/aleg94/pricegram/blob/master/lib/bot/commands/index.js): `lib/bot/commands/index.js`
- [Track command](https://github.com/aleg94/pricegram/blob/master/lib/bot/commands/track.js): `lib/bot/commands/track.js`
- [List command](https://github.com/aleg94/pricegram/blob/master/lib/bot/commands/list.js): `lib/bot/commands/list.js`
- [Add product flow](https://github.com/aleg94/pricegram/blob/master/lib/bot/scenes/add-product.js): `lib/bot/scenes/add-product.js`
- [Target price flow](https://github.com/aleg94/pricegram/blob/master/lib/bot/scenes/set-target-price.js): `lib/bot/scenes/set-target-price.js`
- [Product actions](https://github.com/aleg94/pricegram/tree/master/lib/bot/actions): `lib/bot/actions`
- [List action](https://github.com/aleg94/pricegram/blob/master/lib/bot/actions/list.js): `lib/bot/actions/list.js`
- [Menu action](https://github.com/aleg94/pricegram/blob/master/lib/bot/actions/menu.js): `lib/bot/actions/menu.js`
- [Remove action](https://github.com/aleg94/pricegram/blob/master/lib/bot/actions/remove.js): `lib/bot/actions/remove.js`
- [Price action](https://github.com/aleg94/pricegram/blob/master/lib/bot/actions/price.js): `lib/bot/actions/price.js`
- [Availability action](https://github.com/aleg94/pricegram/blob/master/lib/bot/actions/availability.js): `lib/bot/actions/availability.js`
- [Product menu](https://github.com/aleg94/pricegram/blob/master/lib/bot/keyboards/menu.js): `lib/bot/keyboards/menu.js`

### Amazon product retrieval

- [Page fetcher](https://github.com/aleg94/pricegram/blob/master/lib/helpers/http.js): `lib/helpers/http.js`
- [Amazon page parser](https://github.com/aleg94/pricegram/blob/master/lib/amazon/amazon-product-page.js): `lib/amazon/amazon-product-page.js`
- [URL validator](https://github.com/aleg94/pricegram/blob/master/lib/helpers/validator.js): `lib/helpers/validator.js`

### Tracking and alerts

- [Tracker coordinator](https://github.com/aleg94/pricegram/blob/master/lib/price-tracker/index.js): `lib/price-tracker/index.js`
- [Polling scheduler](https://github.com/aleg94/pricegram/blob/master/lib/price-tracker/polling.js): `lib/price-tracker/polling.js`
- [Product check handler](https://github.com/aleg94/pricegram/blob/master/lib/price-tracker/handler.js): `lib/price-tracker/handler.js`
- [Alert formatter](https://github.com/aleg94/pricegram/blob/master/lib/templates/alert.js): `lib/templates/alert.js`

### Persistence

- [Database connector](https://github.com/aleg94/pricegram/blob/master/lib/database.js): `lib/database.js`
- [Product model](https://github.com/aleg94/pricegram/blob/master/lib/models/product.model.js): `lib/models/product.model.js`

### Other components

- **Telegram user**
- **MongoDB**
- **Telegram API**

## Connections

- Telegram user → Bot runtime: sends commands (evidence: `README.md`)
- Bot runtime → Command registry: dispatches commands (evidence: `lib/bot/index.js`)
- Bot runtime → Product actions: dispatches actions (evidence: `lib/bot/index.js`)
- Bot runtime → Telegram API: sends messages (evidence: `lib/bot/index.js`)
- Command registry → Track command: registers (evidence: `lib/bot/commands/index.js`)
- Command registry → List command: registers (evidence: `lib/bot/commands/index.js`)
- Track command → Add product flow: starts flow (evidence: `lib/bot/commands/track.js`)
- List command → Product model: queries products (evidence: `lib/bot/commands/list.js`)
- List command → Product menu: renders options (evidence: `lib/bot/commands/list.js`)
- Product actions → List action: dispatches (evidence: `lib/bot/actions/index.js`)
- Product actions → Menu action: dispatches (evidence: `lib/bot/actions/index.js`)
- Product actions → Remove action: dispatches (evidence: `lib/bot/actions/index.js`)
- Product actions → Price action: dispatches (evidence: `lib/bot/actions/index.js`)
- Product actions → Availability action: dispatches (evidence: `lib/bot/actions/index.js`)
- List action → Product model: queries products (evidence: `lib/bot/actions/list.js`)
- Menu action → Product model: queries products (evidence: `lib/bot/actions/menu.js`)
- Menu action → Product menu: renders options (evidence: `lib/bot/actions/menu.js`)
- Remove action → Product model: deletes product (evidence: `lib/bot/actions/remove.js`)
- Price action → Target price flow: starts flow (evidence: `lib/bot/actions/price.js`)
- Availability action → Product model: updates preference (evidence: `lib/bot/actions/availability.js`)
- Add product flow → Product model: saves product (evidence: `lib/bot/scenes/add-product.js`)
- Add product flow → Page fetcher: fetches page (evidence: `lib/bot/scenes/add-product.js`)
- Add product flow → Amazon page parser: parses page (evidence: `lib/bot/scenes/add-product.js`)
- Add product flow → URL validator: validates URL (evidence: `lib/bot/scenes/add-product.js`)
- Target price flow → Product model: updates target (evidence: `lib/bot/scenes/set-target-price.js`)
- Tracker coordinator → Polling scheduler: starts polling (evidence: `lib/price-tracker/index.js`)
- Tracker coordinator → Product check handler: registers checks (evidence: `lib/price-tracker/index.js`)
- Polling scheduler → Product check handler: dispatches results (evidence: `lib/price-tracker/index.js`)
- Product check handler → Page fetcher: fetches page (evidence: `lib/price-tracker/handler.js`)
- Product check handler → Amazon page parser: parses page (evidence: `lib/price-tracker/handler.js`)
- Product check handler → Product model: updates record (evidence: `lib/price-tracker/handler.js`)
- Database connector → MongoDB: connects (evidence: `lib/database.js`)
- Product check handler → Alert formatter: emits update
- Alert formatter → Bot runtime: formats alert (evidence: `app.js`)
- Bot runtime → Telegram user: delivers alert
