Documentation · 11 October 2026

BMS Poller field guide

Four guides for the program that watches BookMyShow and tells you when seats free up: how it works today, what is broken, and how to build the website and the phone app that come next.

  • 4 guides
  • 61 min in total
  • 44 words explained
B4–5
Every guide is about one moment: two free seats appearing side by side.
01 · 15 min

Getting started

Install it, run it, and see how it works today, with an architecture drawing and a step-by-step flow of one minute in the poller's life.

  • Setup
  • Git
  • Settings
  • 2 diagrams
  • Troubleshooting
02 · 12 min

Bug guide

Ten problems found in the code and logs, including blank alerts and the hand-pasted token. Each has where to look, how to prove it, and the fix.

  • 10 bugs
  • Fixes with code
  • Debug steps
  • Reading list
03 · 18 min

Version 2 plan

The next version: a website where you pick a theatre and then a movie, alerts checked against the seat map, and no tokens on any account.

  • Tech stack
  • Theatre-first picker
  • Features
  • Research
  • Build order
04 · 16 min

Mobile app

The same thing as an Android and iPhone app with Expo: what to install, the screens, push notifications, and how to get it onto phones.

  • Expo
  • Push
  • Android
  • iPhone
  • Stores

Not getting alerts? The most common cause is a show date in the settings that is already in the past. The fix takes a minute and is in Getting started, section 9.

Words used in these guides

Every underlined word in the guides shows a short definition when you point at it. They are all collected here, with a link to learn more.

44 words

API

A way for one program to ask another program for data over the internet, without a web page in between. BookMyShow's website calls its own API to get showtimes; the poller calls the same API.

Frontend

The part the user sees and clicks: a web page or an app screen.

same link

Token

A long random string that proves you are logged in. BookMyShow puts one inside the ud cookie. Today the poller needs it pasted by hand.

HTTP status code

A number a website sends back with every answer. 200 means fine. 400 means your request made no sense. 401 means not logged in. 403 means blocked. 429 means too many requests.

JSON

A text format for data that both humans and programs can read, with curly braces and quotes. BookMyShow's API answers in JSON, and the poller's state files are JSON.

Headless browser

A real Chrome browser running without a window, controlled by a program. The poller uses one to open the seat map page.

Playwright

The library that controls the headless browser from Python.

same link

Canvas

A drawing area on a web page. BookMyShow paints the seat map as a picture on a canvas, so there is no text to read; the poller records the drawing commands instead.

Virtual environment (venv)

A private folder of Python packages for one project, so projects do not break each other.

.env file

A text file of settings and passwords, one per line, that the program reads at start. Never put it in git.

Git / GitHub

Git keeps a history of your code. GitHub stores that history online. A "commit" is one saved change. A "branch" is a side copy to work on. A "pull request" asks to merge a branch.

SSH key

A pair of files that lets your computer log in to GitHub without a password.

Package manager

A program that installs other programs with one command. Homebrew (brew) on macOS, apt on Ubuntu and Debian Linux, winget on Windows.

Log file

A text file where the program writes what it is doing, one line per event. The first place to look when something is wrong.

Traceback

The block of text Python prints when it crashes, showing which line failed.

Cloudflare

A protection service in front of BookMyShow that blocks programs that look like robots or send too many requests.

ntfy

A free service and phone app for push notifications. You post a message to a "topic" and every phone subscribed to that topic buzzes.

SMTP / app password

SMTP is how programs send email. Gmail needs a special 16-character "app password" instead of your real password.

Unit test / pytest

A small program that checks one piece of your code gives the right answer. pytest runs them.

Database

A program that stores tables of data safely, even when many things write at once. Version 2 uses PostgreSQL.

Server

A computer that is always on and reachable from the internet. Yours is the free Oracle Cloud VM.

Docker

A way to package a program with everything it needs so it runs the same on your Mac and on the server. "docker compose" starts several packages together.

HTTPS / TLS

The padlock in the browser. Required for push notifications and for the mobile app to talk to your server.

Reverse proxy

A small program (Caddy) that sits in front of your server, handles the padlock, and forwards requests to the right place.

Push notification

A message that pops up on a phone or in a browser even when the app is closed. Android uses Google's FCM, iPhone uses Apple's APNs, browsers use Web Push. Expo wraps all three.

JWT / sign-in token

A token your own backend gives a user after login, sent with every request to prove who they are.

OTP

One-time password: the code BookMyShow texts to your phone when you log in.

Web view

A browser window shown inside a mobile app. Used so a user can log in to BookMyShow inside your app.

React / React Native / Expo

React builds web pages from small pieces called components. React Native does the same for phone apps. Expo is a toolkit that makes React Native easy to build and ship.

FastAPI

A Python library for building a backend API quickly, with a free documentation page generated for you.

Scheduler

A part of a program that runs jobs on a timer, like "poll this show every 60 seconds".

APK / AAB

An APK is an Android app file you can install directly. An AAB is the format the Play Store wants.

TestFlight

Apple's app for testing iPhone apps before they are in the App Store.

Encryption key (Fernet)

A secret used to scramble stored cookies so a database leak does not leak logins.