# manikanta7cheruku/showtime-sentinel architecture

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

- Interactive diagram: https://gitdiagram.com/manikanta7cheruku/showtime-sentinel
- Repository: https://github.com/manikanta7cheruku/showtime-sentinel

## Overview

Movie Ticket Monitor watches user-defined movie and theatre criteria, checks availability through interchangeable source adapters, normalizes observations into availability states, deduplicates actionable transitions, persists monitoring history, and notifies users. The main runtime path is CLI/Telegram setup → scheduler → checker → source and state processing → notification and SQLite persistence. README documents a Playwright BookMyShow adapter, fake scenarios, and an optional read-only dashboard; relationships for unsampled dashboard wiring are not asserted here.

Main entry points: [`app/monitoring/checker.py`](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/checker.py) (Availability checker), [`app/database/repositories.py`](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/database/repositories.py) (SQLite repositories), [`app/main.py`](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/main.py) (CLI and wiring), [`app/notifications/base.py`](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/notifications/base.py) (Notification service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI and wiring<br/>[main.py]"]
  node_telegram_commands["Bot commands<br/>[commands.py]"]
  node_bot_runner["Bot runner<br/>[runner.py]"]
  node_dashboard["Local dashboard<br/>[dashboard.py]"]
end

subgraph group_monitor["Monitoring pipeline"]
  node_scheduler["Watch scheduler<br/>[scheduler.py]"]
  node_checker["Availability checker<br/>[checker.py]"]
  node_normalizer["Observation normalizer<br/>[normalizer.py]"]
  node_filters["Watch filters<br/>[filters.py]"]
  node_state["Availability states<br/>[state.py]"]
  node_detector["Transition deduplicator<br/>[change_detector.py]"]
  node_models["Domain contracts<br/>[result.py]"]
end

subgraph group_sources["Availability sources"]
  node_source_registry["Source registry<br/>[base.py]"]
  node_bookmyshow["BookMyShow adapter<br/>[bookmyshow.py]"]
  node_fake_source["Fake scenarios<br/>[fake.py]"]
end

subgraph group_notify["Notification delivery"]
  node_notifier["Notification service<br/>[base.py]"]
  node_formatter["Message formatter<br/>[formatter.py]"]
  node_telegram_delivery["Telegram delivery<br/>[telegram.py]"]
  node_console_delivery["Console delivery<br/>[console.py]"]
end

subgraph group_storage["Persistence"]
  node_repositories["SQLite repositories<br/>[repositories.py]"]
  node_database[("SQLite database<br/>[connection.py]")]
end

node_settings["Runtime settings<br/>[config.py]"]
node_telegram_user(("Telegram user"))
node_telegram_api{{"Telegram API"}}

node_cli -->|"starts"| node_scheduler
node_cli -->|"starts"| node_bot_runner
node_cli -->|"loads"| node_settings
node_bot_runner -->|"registers"| node_telegram_commands
node_telegram_user -->|"sends commands"| node_telegram_commands
node_telegram_commands -->|"manages watches"| node_repositories
node_telegram_commands -->|"runs checks"| node_checker
node_scheduler -->|"loads watches"| node_repositories
node_scheduler -->|"runs checks"| node_checker
node_checker -->|"selects source"| node_source_registry
node_source_registry -->|"dispatches"| node_fake_source
node_source_registry -->|"dispatches"| node_bookmyshow
node_checker -->|"normalizes outcome"| node_normalizer
node_normalizer -->|"applies filters"| node_filters
node_normalizer -->|"derives state"| node_state
node_checker -->|"decides transition"| node_detector
node_checker -->|"records results"| node_repositories
node_checker -->|"sends alert"| node_notifier
node_notifier -->|"formats messages"| node_formatter
node_notifier -->|"delivers"| node_telegram_delivery
node_notifier -->|"delivers"| node_console_delivery
node_telegram_delivery -->|"sends messages"| node_telegram_api
node_repositories -->|"queries"| node_database
node_dashboard -->|"reads status"| node_repositories
node_cli -.->|"optionally starts"| node_dashboard

click node_cli "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/main.py"
click node_telegram_commands "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/bot/commands.py"
click node_bot_runner "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/bot/runner.py"
click node_dashboard "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/web/dashboard.py"
click node_scheduler "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/scheduler.py"
click node_checker "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/checker.py"
click node_normalizer "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/normalizer.py"
click node_filters "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/filters.py"
click node_state "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/state.py"
click node_detector "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/change_detector.py"
click node_models "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/models/result.py"
click node_source_registry "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/sources/base.py"
click node_bookmyshow "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/sources/bookmyshow.py"
click node_fake_source "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/sources/fake.py"
click node_notifier "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/notifications/base.py"
click node_formatter "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/notifications/formatter.py"
click node_telegram_delivery "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/notifications/telegram.py"
click node_console_delivery "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/notifications/console.py"
click node_repositories "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/database/repositories.py"
click node_database "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/database/connection.py"
click node_settings "https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/config.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_cli,node_telegram_commands,node_bot_runner,node_dashboard,node_telegram_user toneBlue
class node_scheduler,node_checker,node_normalizer,node_filters,node_state,node_detector,node_models toneAmber
class node_source_registry,node_bookmyshow,node_fake_source,node_telegram_api toneMint
class node_notifier,node_formatter,node_telegram_delivery,node_console_delivery toneRose
class node_repositories,node_database toneIndigo
class node_settings toneTeal
```

## Components

### User interfaces

- [CLI and wiring](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/main.py): `app/main.py`
- [Bot commands](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/bot/commands.py): `app/bot/commands.py`
- [Bot runner](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/bot/runner.py): `app/bot/runner.py`
- [Local dashboard](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/web/dashboard.py): `app/web/dashboard.py`

### Monitoring pipeline

- [Watch scheduler](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/scheduler.py): `app/monitoring/scheduler.py`
- [Availability checker](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/checker.py): `app/monitoring/checker.py`
- [Observation normalizer](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/normalizer.py): `app/monitoring/normalizer.py`
- [Watch filters](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/filters.py): `app/monitoring/filters.py`
- [Availability states](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/state.py): `app/monitoring/state.py`
- [Transition deduplicator](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/monitoring/change_detector.py): `app/monitoring/change_detector.py`
- [Domain contracts](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/models/result.py): `app/models/result.py`

### Availability sources

- [Source registry](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/sources/base.py): `app/sources/base.py`
- [BookMyShow adapter](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/sources/bookmyshow.py): `app/sources/bookmyshow.py`
- [Fake scenarios](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/sources/fake.py): `app/sources/fake.py`

### Notification delivery

- [Notification service](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/notifications/base.py): `app/notifications/base.py`
- [Message formatter](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/notifications/formatter.py): `app/notifications/formatter.py`
- [Telegram delivery](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/notifications/telegram.py): `app/notifications/telegram.py`
- [Console delivery](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/notifications/console.py): `app/notifications/console.py`

### Persistence

- [SQLite repositories](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/database/repositories.py): `app/database/repositories.py`
- [SQLite database](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/database/connection.py): `app/database/connection.py`

### Other components

- [Runtime settings](https://github.com/manikanta7cheruku/showtime-sentinel/blob/main/app/config.py): `app/config.py`
- **Telegram user**
- **Telegram API**

## Connections

- CLI and wiring → Watch scheduler: starts (evidence: `app/main.py`)
- CLI and wiring → Bot runner: starts (evidence: `app/main.py`)
- CLI and wiring → Runtime settings: loads (evidence: `app/main.py`)
- Bot runner → Bot commands: registers (evidence: `app/bot/runner.py`)
- Telegram user → Bot commands: sends commands (evidence: `README.md`)
- Bot commands → SQLite repositories: manages watches (evidence: `app/bot/commands.py`)
- Bot commands → Availability checker: runs checks (evidence: `app/bot/commands.py`)
- Watch scheduler → SQLite repositories: loads watches (evidence: `README.md`)
- Watch scheduler → Availability checker: runs checks (evidence: `app/monitoring/scheduler.py`)
- Availability checker → Source registry: selects source (evidence: `app/monitoring/checker.py`)
- Source registry → Fake scenarios: dispatches (evidence: `app/sources/base.py`)
- Source registry → BookMyShow adapter: dispatches (evidence: `README.md`)
- Availability checker → Observation normalizer: normalizes outcome (evidence: `app/monitoring/checker.py`)
- Observation normalizer → Watch filters: applies filters (evidence: `app/monitoring/normalizer.py`)
- Observation normalizer → Availability states: derives state (evidence: `app/monitoring/normalizer.py`)
- Availability checker → Transition deduplicator: decides transition (evidence: `app/monitoring/checker.py`)
- Availability checker → SQLite repositories: records results (evidence: `app/monitoring/checker.py`)
- Availability checker → Notification service: sends alert (evidence: `app/monitoring/checker.py`)
- Notification service → Message formatter: formats messages (evidence: `app/notifications/console.py`)
- Notification service → Telegram delivery: delivers (evidence: `app/notifications/telegram.py`)
- Notification service → Console delivery: delivers (evidence: `app/notifications/__init__.py`)
- Telegram delivery → Telegram API: sends messages (evidence: `README.md`)
- SQLite repositories → SQLite database: queries (evidence: `app/database/__init__.py`)
- Local dashboard → SQLite repositories: reads status (evidence: `app/web/dashboard.py`)
- CLI and wiring → Local dashboard: optionally starts
