# ffariseee-ux/movie-alert architecture

> Architecture diagram of the GitHub repository ffariseee-ux/movie-alert, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ffariseee-ux/movie-alert
- Repository: https://github.com/ffariseee-ux/movie-alert

## Overview

Movie-Alert periodically checks configured BookMyShow targets and alerts a Telegram chat when booking availability changes. The workflow begins with an external cron trigger, runs the poller, expands and validates movie/date targets, fetches each booking page, detects availability or newly added shows, and tracks last-seen state. The README also documents date-wide and venue-specific detection, optional proxy routing, and show/session monitoring. The graph reflects the documented runtime; source excerpts are partial, so some internal call ownership is not independently visible.

Main entry points: [`poller.py`](https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py) (Booking-page fetch), [`.github/workflows/booking-watch.yml`](https://github.com/ffariseee-ux/movie-alert/blob/main/.github/workflows/booking-watch.yml) (Actions workflow), [`state.json`](https://github.com/ffariseee-ux/movie-alert/blob/main/state.json) (Last-seen state), [`config.json`](https://github.com/ffariseee-ux/movie-alert/blob/main/config.json) (Target configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Scheduled runtime"]
  node_workflow["Actions workflow<br/>[booking-watch.yml]"]
end

subgraph group_watcher["Booking watcher"]
  node_poller["Polling entrypoint<br/>[poller.py]"]
  node_config["Target configuration<br/>[config.json]"]
  node_target_setup["Target preparation<br/>[poller.py]"]
  node_page_fetch["Booking-page fetch<br/>[poller.py]"]
  node_availability["Availability detectors<br/>[poller.py]"]
  node_change_tracking["Change tracking<br/>[poller.py]"]
  node_state[("Last-seen state<br/>[state.json]")]
  node_message["Alert message<br/>[poller.py]"]
end

subgraph group_integrations["External services"]
  node_bookmyshow["BookMyShow"]
  node_scraperapi["ScraperAPI"]
  node_proxy["India proxy"]
  node_telegram["Telegram"]
end

node_cron(("Cron trigger"))

node_cron -->|"dispatches"| node_workflow
node_workflow -->|"runs"| node_poller
node_poller -->|"loads"| node_config
node_poller -->|"prepares targets"| node_target_setup
node_target_setup -->|"supplies target URL"| node_page_fetch
node_poller -->|"loads and updates"| node_state
node_page_fetch -->|"routes requests"| node_scraperapi
node_scraperapi -->|"fetches page"| node_bookmyshow
node_page_fetch -->|"fetches directly"| node_bookmyshow
node_page_fetch -.->|"may route through"| node_proxy
node_page_fetch -->|"passes page text"| node_availability
node_availability -->|"reports availability"| node_change_tracking
node_change_tracking -->|"updates last-seen data"| node_state
node_change_tracking -->|"triggers alert"| node_message
node_message -->|"sends message"| node_telegram

click node_workflow "https://github.com/ffariseee-ux/movie-alert/blob/main/.github/workflows/booking-watch.yml"
click node_poller "https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py"
click node_config "https://github.com/ffariseee-ux/movie-alert/blob/main/config.json"
click node_target_setup "https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py"
click node_page_fetch "https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py"
click node_availability "https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py"
click node_change_tracking "https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py"
click node_state "https://github.com/ffariseee-ux/movie-alert/blob/main/state.json"
click node_message "https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py"

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_workflow toneBlue
class node_poller,node_config,node_target_setup,node_page_fetch,node_availability,node_change_tracking,node_state,node_message toneAmber
class node_bookmyshow,node_scraperapi,node_proxy,node_telegram toneMint
class node_cron toneIndigo
```

## Components

### Scheduled runtime

- [Actions workflow](https://github.com/ffariseee-ux/movie-alert/blob/main/.github/workflows/booking-watch.yml): `.github/workflows/booking-watch.yml`

### Booking watcher

- [Polling entrypoint](https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py): `poller.py`
- [Target configuration](https://github.com/ffariseee-ux/movie-alert/blob/main/config.json): `config.json`
- [Target preparation](https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py): `poller.py`
- [Booking-page fetch](https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py): `poller.py`
- [Availability detectors](https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py): `poller.py`
- [Change tracking](https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py): `poller.py`
- [Last-seen state](https://github.com/ffariseee-ux/movie-alert/blob/main/state.json): `state.json`
- [Alert message](https://github.com/ffariseee-ux/movie-alert/blob/main/poller.py): `poller.py`

### External services

- **BookMyShow**
- **ScraperAPI**
- **India proxy**
- **Telegram**

### Other components

- **Cron trigger**

## Connections

- Cron trigger → Actions workflow: dispatches (evidence: `README.md`)
- Actions workflow → Polling entrypoint: runs (evidence: `README.md`)
- Polling entrypoint → Target configuration: loads (evidence: `poller.py`)
- Polling entrypoint → Target preparation: prepares targets (evidence: `poller.py`)
- Target preparation → Booking-page fetch: supplies target URL (evidence: `README.md`)
- Polling entrypoint → Last-seen state: loads and updates (evidence: `README.md`)
- Booking-page fetch → ScraperAPI: routes requests (evidence: `poller.py`)
- ScraperAPI → BookMyShow: fetches page (evidence: `README.md`)
- Booking-page fetch → BookMyShow: fetches directly (evidence: `poller.py`)
- Booking-page fetch → India proxy: may route through (evidence: `README.md`)
- Booking-page fetch → Availability detectors: passes page text (evidence: `poller.py`)
- Availability detectors → Change tracking: reports availability (evidence: `poller.py`)
- Change tracking → Last-seen state: updates last-seen data (evidence: `README.md`)
- Change tracking → Alert message: triggers alert (evidence: `poller.py`)
- Alert message → Telegram: sends message (evidence: `README.md`)
