# happytetrahedron/order_bot architecture

> Architecture diagram of the GitHub repository happytetrahedron/order_bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/happytetrahedron/order_bot
- Repository: https://github.com/happytetrahedron/order_bot

## Overview

##### Project Type and Purpose
- This is an open-source Telegram bot (“order_bot”) written in Python.
- Its core purpose is to collect and manage group chat orders (e.g., food orders) via mentions and slash-commands.
- It also features an extensible “mode” system, with built-in support for automating Domino’s Pizza Switzerland orders (via HTTP reverse-engineered endpoints and a MapQuest geocoding integration).

##### File Structure Analysis
- Top-level files:
- orderbot.py       – main entrypoint; sets up Telegram handlers for slash-commands (/start, /mode, /order, /close, etc.) and message updates
- mentions_handler.py – logic for parsing “@bot” mentions and updating in-memory order state or persisting changes
- dominos.py        – external integration module; handles geocoding (MapQuest) and ordering API calls to Domino’s endpoints
- default.py        – fallback logic for “default” (no external supplier) mode; just aggregates orders in a Telegram message
- requirements.txt  – pinned Python dependencies (e.g. python-telegram-bot, requests, sqlite3)
- .gitignore, README – project metadata
- Persistence: SQLite (via standard library or ORM) to store per-chat, per-order state and configuration.
- Configuration: read from a YAML/TOML/JSON file supplied at runtime (with bot token, DB path, “dominos” section).

##### Key Components to Illustrate
a. Telegram Ecosystem
- Chat (Users)
- Telegram Bot API (Webhook or Long-Polling)
b. Core Application
- orderbot.py – dispatcher, command handlers
- mentions_handler.py – mention parsing, order updates
- default.py & dominos.py – mode implementations (strategy pattern)
- Config Loader – loads token, DB path, Domino’s settings, MapQuest key
c. Persistence Layer
- SQLite Database – stores chats, orders, user preferences, mode settings
d. External Services
- MapQuest Geocoding API (for address → lat/long)
- Domino’s HTTP API endpoints (store lookup, menu fetch, order placement)

##### Interactions and Data Flow
1. User sends `/start` or order message (@bot) → Telegram API → Bot receives Update
2. Dispatcher (orderbot.py) routes to the appropriate handler:
– Slash-command handlers create/close an order session or switch modes
– mentions_handler.py parses mention messages, updates the order in SQLite
– default.py or dominos.py composes a response summary message
3. If Domino’s mode is active and user issues `/order`:
– dominos.py calls MapQuest API to geocode the delivery address
– dominos.py retrieves store info, menu, deals via HTTP calls
– dominos.py validates/prices order, then places order (HTTP POST)
4. Bot posts or edits a Telegram message in the group with the current order list or order summary.

##### Architectural Patterns and Design Principles
- Modular “Mode” Strategy Pattern: default vs. supplier-specific logic resides in separate modules.
- Single-process, event-driven design via Telegram update loop (no webserver).
- Clear separation between:
- Command dispatch (orderbot.py)
- Business logic (mentions_handler.py)
- External integration (dominos.py + geocode)
- Persistence (SQLite)
- Configuration-driven extensibility (config file defines supplier endpoints, MapQuest key, DB path).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Users & Telegram API
    subgraph "User Interaction"
        direction TB
        User["Users (Group Chat)"]:::external
        TelegramAPI["Telegram Bot API"]:::external
    end

    User -->|"Telegram update"| TelegramAPI

    %% Middle Layer: Bot Application
    subgraph "Bot Application"
        direction TB
        orderbot["orderbot.py\nDispatcher & Command Handlers"]:::internal
        mentions["mentions_handler.py\nMention Parsing & Order State Updates"]:::internal
        defaultMode["default.py\nDefault Mode (in-memory aggregation)"]:::internal
        dominosMode["dominos.py\nDomino’s Mode (MapQuest & HTTP API)"]:::internal
        configLoader["Config Loader\n(loads token, DB path, supplier settings)"]:::config
        requirements["requirements.txt"]:::config
        readme["README.md"]:::config
        gitignore[".gitignore"]:::config
    end

    TelegramAPI -->|"Update"| orderbot
    orderbot -->|"routes to"| mentions
    orderbot -->|"routes to"| defaultMode
    orderbot -->|"routes to"| dominosMode
    orderbot -->|"loads config"| configLoader
    configLoader --> requirements
    configLoader --> readme
    configLoader --> gitignore

    mentions -->|"SQLite read/write"| SQLiteDB[(SQLite Database)]:::persistence
    defaultMode -->|"compose summary"| orderbot
    dominosMode -->|"compose summary"| orderbot

    %% Bottom Layer: Persistence & External Services
    subgraph "Persistence & External Services"
        direction TB
        SQLiteDB
        MapQuest["MapQuest Geocoding API"]:::external
        DominosAPI["Domino’s HTTP API"]:::external
    end

    dominosMode -->|"HTTP GET (geocode)"| MapQuest
    dominosMode -->|"HTTP GET/POST (store/menu/order)"| DominosAPI

    orderbot -->|"send message/edit"| TelegramAPI
    TelegramAPI -->|"deliver message"| User

    %% Click Events
    click orderbot "https://github.com/happytetrahedron/order_bot/blob/master/orderbot.py"
    click mentions "https://github.com/happytetrahedron/order_bot/blob/master/mentions_handler.py"
    click defaultMode "https://github.com/happytetrahedron/order_bot/blob/master/default.py"
    click dominosMode "https://github.com/happytetrahedron/order_bot/blob/master/dominos.py"
    click requirements "https://github.com/happytetrahedron/order_bot/blob/master/requirements.txt"
    click readme "https://github.com/happytetrahedron/order_bot/blob/master/README.md"
    click gitignore "https://github.com/happytetrahedron/order_bot/blob/master/.gitignore"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef persistence fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef config fill:#eeeeee,stroke:#9e9e9e,color:#424242
```
