# kharepratyush/telegram_food_bot architecture

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

- Interactive diagram: https://gitdiagram.com/kharepratyush/telegram_food_bot
- Repository: https://github.com/kharepratyush/telegram_food_bot

## Overview

##### Project type and purpose
- This is a full-stack “bot” application that integrates with Telegram’s API to provide diabetic-friendly meal planning, food logging, and shopping list management.
- It leverages LLMs (OpenAI or Ollama) for conversational meal planning and uses SQLite for persistence.

##### File structure
- Top-level files:
- bot_v2.py – main entrypoint
- run.sh / supervisord.conf – scripts and configs for startup and auto-restart
- requirements*.txt – dependencies
- src/agents/ – encapsulates LLM agent logic:
- food_agent.py – domain logic for meals
- llm.py – LLM abstraction (OpenAI/Ollama selector)
- prompts.py, tools.py – prompt templates and helper functions
- utils/ – configuration and low-level DB helpers
- workflow/ – orchestrator for multi-step tasks
- src/telegram_bot/ – Telegram integration layer:
- config.py – environment and token loading
- handlers/ – per-command/message handlers (start, help, save, shopping_list, etc.)
- utils/ – DB access, table rendering, Telegram API wrappers
- tests/ – unit tests covering agents, handlers, and utilities

##### README for additional insights
- Supervisor integration: supervisord.conf for process management
- SQLite database under data/ (excluded from tree but referenced)
- Uses markdown and table rendering for responses
- Future extensibility points: GI API, knowledge base

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFD580,stroke:#000,stroke-width:1px

    User["User (Telegram Client)"]:::external
    TelegramAPI["Telegram API"]:::external
    RunScript["run.sh"]:::external
    Supervisor["Supervisor"]:::external

    subgraph "Bot Process"
        Entrypoint["bot_v2.py"]:::internal
        subgraph "Handlers"
            Start["start_handler.py"]:::internal
            Help["help_handler.py"]:::internal
            Msg["message_handler.py"]:::internal
            Save["save_handler.py"]:::internal
            Shop["shopping_list_handler.py"]:::internal
        end
        subgraph "Telegram Utils"
            TgDB["db.py"]:::internal
            Renderer["table_renderer.py"]:::internal
            TgUtils["telegram_utils.py"]:::internal
        end
        subgraph "Agent Layer"
            Orchestrator["workflow.py"]:::internal
            LLMAdapter["llm.py"]:::internal
            Domain["food_agent.py"]:::internal
            Prompts["prompts.py"]:::internal
            Tools["tools.py"]:::internal
            subgraph "Agent Utils"
                AgentConfig["config.py"]:::internal
                AgentDB["db.py"]:::internal
            end
        end
    end

    DB["SQLite DB"]:::datastore
    OpenAI["OpenAI API"]:::external
    Ollama["Ollama API"]:::external

    User -->|sends message| TelegramAPI
    TelegramAPI -->|forwards to| Entrypoint
    Entrypoint --> Start
    Entrypoint --> Help
    Entrypoint --> Msg
    Entrypoint --> Save
    Entrypoint --> Shop

    Start -->|uses| TgUtils
    Help -->|uses| TgUtils
    Msg -->|uses| TgUtils
    Save -->|writes| TgDB
    Save -->|uses| TgUtils
    Shop -->|writes| TgDB
    Shop -->|uses| TgUtils

    Msg -->|triggers| Orchestrator
    Orchestrator -->|calls| LLMAdapter
    LLMAdapter -->|requests| OpenAI
    LLMAdapter -->|requests| Ollama
    OpenAI -->|response| LLMAdapter
    Ollama -->|response| LLMAdapter
    LLMAdapter -->|returns| Orchestrator

    Orchestrator -->|processes| Domain
    Domain -->|uses| Prompts
    Domain -->|uses| Tools
    Domain -->|stores/read| AgentDB
    Domain -->|reads| AgentConfig

    Domain -->|result| Renderer
    Renderer -->|formats| Msg
    TgDB -->|persists| DB
    AgentDB -->|persists| DB

    Supervisor -.->|monitors| Entrypoint
    RunScript -.->|starts| Entrypoint

    click Entrypoint "https://github.com/kharepratyush/telegram_food_bot/blob/main/bot_v2.py"
    click Supervisor "https://github.com/kharepratyush/telegram_food_bot/blob/main/supervisord.conf"
    click RunScript "https://github.com/kharepratyush/telegram_food_bot/blob/main/run.sh"
    click LLMAdapter "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/agents/llm.py"
    click Domain "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/agents/food_agent.py"
    click Prompts "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/agents/prompts.py"
    click Tools "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/agents/tools.py"
    click AgentConfig "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/agents/utils/config.py"
    click AgentDB "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/agents/utils/db.py"
    click Orchestrator "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/agents/workflow/workflow.py"
    click TgDB "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/telegram_bot/utils/db.py"
    click Renderer "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/telegram_bot/utils/table_renderer.py"
    click TgUtils "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/telegram_bot/utils/telegram_utils.py"
    click Start "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/telegram_bot/handlers/start_handler.py"
    click Help "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/telegram_bot/handlers/help_handler.py"
    click Msg "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/telegram_bot/handlers/message_handler.py"
    click Save "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/telegram_bot/handlers/save_handler.py"
    click Shop "https://github.com/kharepratyush/telegram_food_bot/blob/main/src/telegram_bot/handlers/shopping_list_handler.py"

    class Entrypoint,Start,Help,Msg,Save,Shop,TgDB,Renderer,TgUtils,Orchestrator,LLMAdapter,Domain,Prompts,Tools,AgentConfig,AgentDB internal
    class User,TelegramAPI,RunScript,Supervisor,OpenAI,Ollama external
    class DB datastore
```
