# mj11rock/poll-story-telegram-bot architecture

> Architecture diagram of the GitHub repository mj11rock/poll-story-telegram-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mj11rock/poll-story-telegram-bot
- Repository: https://github.com/mj11rock/poll-story-telegram-bot

## Overview

##### Project Type and Purpose
- This is a lightweight, scheduled automation script (Python CLI tool) that orchestrates two external services (OpenAI API and Telegram Bot API) to create an interactive, choice-driven story in a Telegram channel.
- It is not a web app or full-stack service; it is a “backend-only” integration utility invoked on a schedule (e.g., via cron).

##### File Structure Analysis
- Top-level files:
- telegram_poster.py      – Core script containing logic to read/write state, call OpenAI, and post to Telegram.
- requirements.txt        – Python dependencies (openai, python-telegram-bot, etc.).
- README.md               – Detailed usage and architecture description.
- story_state.json (runtime) – Local JSON state file storing current story text and last poll ID.
- No additional modules or directories—single-file script.

##### Key Components
a. Scheduler
- cron or any job scheduler that triggers telegram_poster.py at fixed intervals.
b. State Store
- story_state.json on disk for persisting:
- current story text
- last poll ID
c. OpenAI API Integration
- Sends prompts (full story & winning choice) → Receives new story fragment + poll options.
- Configurable endpoint (OPENAI_BASE_URL) and model (OPENAI_MODEL).
d. Telegram Bot API Integration
- Publishes story text as a regular message.
- Creates a new poll with generated options.
e. Configuration
- Environment variables (OPENAI_API_KEY, OPENAI_BASE_URL)
- Hard-coded variables in telegram_poster.py (BOT_TOKEN, CHANNEL_ID, INITIAL_STORY_IDEA).

##### Interactions and Data Flow
1. Scheduler invokes telegram_poster.py.
2. Script loads story_state.json (or initializes with INITIAL_STORY_IDEA).
3. Determines last poll’s winning option.
4. Calls OpenAI API with full story + winning choice → Receives continuation + new options.
5. Calls Telegram Bot API:
a. Post continuation as text message.
b. Create new poll with 4 options.
6. Update story_state.json with new story text and new poll ID.
7. Exit; wait for next scheduled run.

##### Architectural Patterns and Principles
- Single responsibility: script coordinates state, AI, and messaging.
- Sequential flow with clear stages: Load state → AI generation → Messaging → Persist state.
- External integrations are decoupled via explicit API client calls.
- Stateless between runs except for the story_state.json checkpoint.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    Scheduler["Scheduler\n(cron)"]:::scheduler
    Script["telegram_poster.py\n(Orchestration Logic)"]:::script
    State["story_state.json\n(State Store)"]:::state
    OpenAIAPI["OpenAI API"]:::external
    TelegramAPI["Telegram Bot API"]:::external

    subgraph "Documentation & Dependencies"
        Requirements["requirements.txt\n(Dependencies)"]:::config
        Documentation["README.md\n(Documentation)"]:::config
    end

    %% Connections
    Scheduler -->|"trigger"| Script
    Script -->|"load state"| State
    Script -->|"save state"| State
    Script -->|"generate continuation"| OpenAIAPI
    OpenAIAPI -->|"response"| Script
    Script -->|"post message"| TelegramAPI
    Script -->|"create poll"| TelegramAPI
    Script -->|"uses deps"| Requirements
    Script -->|"refer docs"| Documentation

    %% Click Events
    click Script "https://github.com/mj11rock/poll-story-telegram-bot/blob/master/telegram_poster.py"
    click State "https://github.com/mj11rock/poll-story-telegram-bot/blob/master/story_state.json"
    click Requirements "https://github.com/mj11rock/poll-story-telegram-bot/blob/master/requirements.txt"
    click Documentation "https://github.com/mj11rock/poll-story-telegram-bot/blob/master/README.md"

    %% Styles
    classDef scheduler fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef script fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef state fill:#FFA500,stroke:#333,stroke-width:1px,shape:cylinder
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px,shape:cloud
    classDef config fill:#87CEFA,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
