# canopyflick/manon-pa_bot architecture

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

- Interactive diagram: https://gitdiagram.com/canopyflick/manon-pa_bot
- Repository: https://github.com/canopyflick/manon-pa_bot

## Overview

##### Main Components
- Telegram Bot Interface: This is the entry point for messages coming in from the Telegram API. Although the Telegram API isn’t inside the repository, the telegram_helpers directory (e.g., delete_message.py, emoji_reactions.py, security.py) indicates that specific functions for interacting with Telegram are encapsulated here.
- Main Application (main.py): Serves as the central orchestrator that ties together incoming commands, routing, and initialization (connecting to the database and external services as specified in the .env configuration).
- Feature Command Handlers: Under the “features” folder, there are multiple subdirectories (bitcoin, diceroll, evening_message, goals, help, morning_message, obsidian, philosophy, reminders, start, stats, stopwatch) each representing a specific functionality of the Telegram bot. Each of these contains command handlers, schedulers, formatters, and sometimes even registration services.
- LLMs Layer: The “LLMs” directory contains the orchestration logic for handling prompts, templates, command configurations, and structured outputs using language models. This module is likely called upon by feature components that require natural language processing or integration with external AI APIs.
- Models & Database: The “models” directory (with files like bitcoin.py, goal.py, user.py, goals_report.py) defines the core data structures. The “utils/db.py” and “utils/db_helpers.py” indicate that these models are persisted to a PostgreSQL database (with connection instructions provided in the README).
- Utilities & Logging: Various utility modules (from “utils” and “logs”) provide shared helper functions like scheduling, session management, listeners, and logging. These ensure that cross-cutting concerns are cleanly separated from feature logic.

##### Relationships and Data Flow
- A user’s interaction starts at the Telegram API and is received by the bot.
- main.py then acts as the central dispatcher: it interprets incoming messages (with the help from telegram_helpers), identifies the corresponding feature (by checking the command or message patterns) from the “features” directory, and routes the request.
- Specific feature modules handle the command logic and may invoke additional functionality or data models as required.
- When natural language processing or advanced orchestration is required, the feature modules call into the LLMs layer to obtain AI-powered responses or to manage prompts.
- Database operations are abstracted away to the “utils” modules (db.py, db_helpers.py) and possibly interact with models defined in the “models” directory.
- Logging (from the “logs” folder) captures system events and errors throughout these operations.

##### Architectural Patterns & Design Principles
- Modularity: The project is clear on being modular. Each major feature is isolated under its own directory.
- Separation of Concerns: Command handling, language model orchestration, database operations, and utility functions are distinctly partitioned.
- Extensibility: With each feature in its own sub-directory and a dedicated LLMs orchestration module, new features or integrations can be added in a plug-and-play manner.
- Integration of External Services: The use of environment variables to configure external services like OpenAI and LangChain (detailed in the .env section) is central to the architecture.

- Clearly labeled components for every major module (Main, Features, LLMs, Models / Database, Utilities, Telegram Helpers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    TBot["Telegram API Interface & Helpers"]:::external
    Main["Main Application (main.py)"]:::main
    Features["Feature Command Handlers"]:::feature
    LLMs["LLMs Layer"]:::llm
    ModelsDB["Models & Database"]:::database
    UtilLog["Utilities & Logging"]:::utility

    TBot -->|"receives_messages"| Main
    Main -->|"routes_commands"| Features
    Main -->|"invokes_NLP"| LLMs
    Features -->|"calls_LLM_for_processing"| LLMs
    Main -->|"database_operations"| ModelsDB
    Features -->|"database_interaction"| ModelsDB
    UtilLog -->|"logs_and_monitoring_feedback"| Main

    click TBot "https://github.com/canopyflick/manon-pa_bot/tree/main/telegram_helpers/"
    click Main "https://github.com/canopyflick/manon-pa_bot/blob/main/main.py"
    click Features "https://github.com/canopyflick/manon-pa_bot/tree/main/features/"
    click LLMs "https://github.com/canopyflick/manon-pa_bot/tree/main/LLMs/"
    click ModelsDB "https://github.com/canopyflick/manon-pa_bot/tree/main/models/"
    click UtilLog "https://github.com/canopyflick/manon-pa_bot/tree/main/utils/"

    classDef external fill:#BDE0FE,stroke:#333,stroke-width:2px;
    classDef main fill:#FFECB3,stroke:#333,stroke-width:2px;
    classDef feature fill:#FFE0B2,stroke:#333,stroke-width:2px;
    classDef llm fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef database fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef utility fill:#F8BBD0,stroke:#333,stroke-width:2px;
```
