# dvorobiev/bridge-status-bot architecture

> Architecture diagram of the GitHub repository dvorobiev/bridge-status-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dvorobiev/bridge-status-bot
- Repository: https://github.com/dvorobiev/bridge-status-bot

## Overview

#### Purpose and Runtime

A Python 3.10+ Telegram bot that reports the live operational state of the Mityaevsky pontoon bridge in Kolomna. It derives bridge position, traffic-light color, and countdown timer from a camera stream using Google Gemini.

The executable entry point is `bridge_bot.py`, started with `python3 bridge_bot.py`.

#### Application Boundary

The repository is intentionally single-process and single-module: Telegram interaction, camera-frame acquisition, AI analysis, and response formatting are expected to be orchestrated in `bridge_bot.py`.

Core runtime dependencies are declared in `requirements.txt`; local secrets are supplied via `.env` based on `.env.example`.

#### Telegram Interaction Layer

The bot receives `/start` and `/status` commands in private chats and groups, and exposes an inline button for status refresh. This layer handles Telegram updates, command/button routing, and sends the formatted status response.

Primary path:
- `bridge_bot.py`

External service:
- Telegram Bot API, authenticated by `TELEGRAM_TOKEN`.

#### Camera Capture Stage

On a status request, the bot obtains a current image/frame from the bridge camera video stream. `ffmpeg` is an OS-level required dependency, indicating frame extraction likely occurs through a subprocess rather than a Python-native decoder.

Boundary: camera/video input is transformed into a still image suitable for AI inspection.

Primary path:
- `bridge_bot.py`

External/runtime dependency:
- `ffmpeg` installed on the host.

#### AI Vision Analysis Stage

The captured frame is submitted to Google Gemini, which is responsible for extracting three domain values: bridge state (joined/open versus separated), traffic-light color, and any visible countdown.

The API key is environment-provided, keeping model credentials outside source control.

Primary paths:
- `bridge_bot.py`
- `.env.example`

External service:
- Google Gemini API, authenticated by `GEMINI_API_KEY`.

#### Status Interpretation and Presentation

The bot converts model output into a concise human-facing result, including semantic bridge status, color/icon-based traffic signal status, optional countdown seconds, and observation time. The response format is designed for immediate operational use in Telegram rather than persistent storage or a web UI.

Primary path:
- `bridge_bot.py`

#### Control Flow and Failure Boundaries

The request path is synchronous in intent: Telegram command/callback → retrieve camera frame → Gemini analysis → normalize/format result → Telegram reply. Network and subprocess boundaries are the likely failure points: Telegram delivery, camera availability, `ffmpeg` execution, HTTP transport, and Gemini response quality/availability.

No database, queue, scheduler, or deployment infrastructure is represented in the repository tree; each status check is expected to be live/on-demand.

Main entry points: [`bridge_bot.py`](https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py) (Bot entry point), [`.env.example`](https://github.com/dvorobiev/bridge-status-bot/blob/main/.env.example) (Environment contract), [`requirements.txt`](https://github.com/dvorobiev/bridge-status-bot/blob/main/requirements.txt) (Python dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot Runtime"]
  node_bot_entry["Bot entry point<br/>Python executable<br/>[bridge_bot.py]"]
  node_command_router["Command &amp; callback routing<br/>Telegram handler<br/>[bridge_bot.py]"]
  node_status_flow["Live status workflow<br/>request orchestrator<br/>[bridge_bot.py]"]
  node_captured_frame["Captured frame<br/>image payload<br/>[bridge_bot.py]"]
  node_status_interpreter["Status interpretation<br/>domain formatter<br/>[bridge_bot.py]"]
  node_telegram_reply["Telegram status reply<br/>formatted message<br/>[bridge_bot.py]"]
  node_env_example["Environment contract<br/>secret template<br/>[.env.example]"]
  node_requirements["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]
end

subgraph group_external["External Boundaries"]
  node_telegram_updates{{"Telegram updates<br/>Telegram Bot API"}}
  node_camera_stream{{"Bridge camera stream<br/>video input"}}
  node_ffmpeg["ffmpeg<br/>host subprocess"]
  node_gemini{{"Google Gemini API<br/>vision service"}}
end

node_telegram_updates -->|"delivers updates"| node_bot_entry
node_bot_entry -->|"registers handlers"| node_command_router
node_command_router -->|"status request"| node_status_flow
node_status_flow -->|"requests live video"| node_camera_stream
node_camera_stream -->|"video stream"| node_ffmpeg
node_ffmpeg -->|"extracts frame"| node_captured_frame
node_captured_frame -->|"image inspection"| node_gemini
node_gemini -->|"bridge observations"| node_status_interpreter
node_status_interpreter -->|"formats result"| node_telegram_reply
node_telegram_reply -->|"sends response"| node_telegram_updates
node_env_example -.->|"TELEGRAM_TOKEN, GEMINI_API_KEY"| node_bot_entry
node_requirements -.->|"runtime packages"| node_bot_entry

click node_bot_entry "https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py"
click node_command_router "https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py"
click node_status_flow "https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py"
click node_captured_frame "https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py"
click node_status_interpreter "https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py"
click node_telegram_reply "https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py"
click node_env_example "https://github.com/dvorobiev/bridge-status-bot/blob/main/.env.example"
click node_requirements "https://github.com/dvorobiev/bridge-status-bot/blob/main/requirements.txt"

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_entry,node_command_router,node_status_flow,node_captured_frame,node_status_interpreter,node_telegram_reply,node_env_example,node_requirements toneBlue
class node_telegram_updates,node_camera_stream,node_ffmpeg,node_gemini toneAmber
```

## Components

### Bot Runtime

Single-process request orchestration in bridge_bot.py.

- [Bot entry point](https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py): Python executable · Starts the Telegram bot and coordinates status requests. · `bridge_bot.py`
- [Command & callback routing](https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py): Telegram handler · Handles /start, /status, and inline refresh actions. · `bridge_bot.py`
- [Live status workflow](https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py): request orchestrator · Runs capture, analysis, interpretation, and reply for each request. · `bridge_bot.py`
- [Captured frame](https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py): image payload · Still image passed to vision analysis. · `bridge_bot.py`
- [Status interpretation](https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py): domain formatter · Normalizes model output into bridge and signal status. · `bridge_bot.py`
- [Telegram status reply](https://github.com/dvorobiev/bridge-status-bot/blob/main/bridge_bot.py): formatted message · Includes semantic status, icons, optional countdown, and observation time. · `bridge_bot.py`
- [Environment contract](https://github.com/dvorobiev/bridge-status-bot/blob/main/.env.example): secret template · Documents Telegram and Gemini credential variables. · `.env.example`
- [Python dependencies](https://github.com/dvorobiev/bridge-status-bot/blob/main/requirements.txt): dependency manifest · Declares runtime packages. · `requirements.txt`

### External Boundaries

- **Telegram updates**: Telegram Bot API · Receives commands and refresh callbacks.
- **Bridge camera stream**: video input · Live source for the pontoon bridge image.
- **ffmpeg**: host subprocess · Extracts a still frame from the camera stream.
- **Google Gemini API**: vision service · Extracts bridge position, signal color, and countdown.

## Connections

- Telegram updates → Bot entry point: delivers updates
- Bot entry point → Command & callback routing: registers handlers
- Command & callback routing → Live status workflow: status request
- Live status workflow → Bridge camera stream: requests live video
- Bridge camera stream → ffmpeg: video stream
- ffmpeg → Captured frame: extracts frame
- Captured frame → Google Gemini API: image inspection
- Google Gemini API → Status interpretation: bridge observations
- Status interpretation → Telegram status reply: formats result
- Telegram status reply → Telegram updates: sends response
- Environment contract → Bot entry point: TELEGRAM_TOKEN, GEMINI_API_KEY
- Python dependencies → Bot entry point: runtime packages