# raykov-git/hacaton_2025 architecture

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

- Interactive diagram: https://gitdiagram.com/raykov-git/hacaton_2025
- Repository: https://github.com/raykov-git/hacaton_2025

## Overview

##### Project Components
- Bot Service (located under the “bot” directory):
- Core chatbot logic (ClinicBot.py, abstractBot.py)
- LLM integration (bot/llm directory containing create_prompt.py, db_to_texts.py, find.py)
- Data source management (bot/files folder with CSVs, a SQLite database for clinic scheduling, embeddings in pickle format)
- Additional utilities (scraper.py for data gathering)
- The primary API endpoint (bot/main.py) which accepts POST requests (e.g., /qa endpoint for questions)
- Messenger Integration (found in the “mesengers” directory):
- The Telegram message handler using aiohttp (telegram_aiohttp.py)
- This component likely retrieves user messages from Telegram and then passes them to the bot service
- Feedback Service (located under the “feedback_service” folder):
- A separate API (feedback_service/main.py) for handling user feedback
- Database initialization / maintenance script (script.sql)
- Documentation or additional detail (text.md)
- External Documentation and OpenAPI Specs:

##### Relationships and Data Flows
- The User interacts with the system in two primary ways:
- Through web API calls (as demonstrated by the CURL example with JSON payload)
- Via Telegram through the messenger integration
- The Bot Service receives questions and processes them using combined logic from the LLM modules. It retrieves/updates data from its local files (CSV and SQLite database) and may further interact with provided embeddings.
- The Messenger component acts as a bridge for Telegram communications, funneling messages into the Bot Service.
- The Feedback Service runs as a parallel, independent API for handling feedback and storing it in a dedicated database (configured via the provided SQL script).
- Infrastructure endpoints are noted in the README, e.g. the main API endpt at “/api” and the direct question endpoint “/qa”.

##### Detail the Architectural Patterns
- Service Separation / Microservice-like Approach: The bot core, messenger integration, and feedback processing are each in separate directories and executed independently.
- API-based communication: Clear endpoints accepting JSON (with documented curl examples) using HTTP for both Q&A and feedback.
- Data-Driven Operations: Use of CSV files, SQLite databases, and serialized embeddings indicate a design that uses lightweight data storage mechanisms.
- LLM or prompt-based processing is a key feature, which is encapsulated under the “llm” directory – emphasizing modularity in how natural language queries are processed.

##### Relevant Technologies and Frameworks
- Python for all services (as evidenced by the .py files)
- AIOHTTP for asynchronous message handling in the Telegram messenger script
- SQLite (or similar lightweight DB) for scheduling and possibly feedback storage
- CSV and pickle files for handling various data inputs and machine learning embeddings
- OpenAPI specification as documented in openAPI.json to guide API interactions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    U("User"):::userStyle

    %% Bot Service Subgraph
    subgraph "Bot Service"
        BA("Primary API Endpoint (bot/main.py)"):::botStyle
        CORE("Core Chatbot Logic"):::botStyle
        CL("ClinicBot.py"):::botStyle
        AB("abstractBot.py"):::botStyle
        LLM("LLM Integration"):::botStyle
        DS("Data Source Management"):::botStyle
        UTIL("Additional Utilities (bot/scraper.py)"):::botStyle
    end

    %% Messenger Integration Subgraph
    subgraph "Messenger Integration"
        M("Telegram Messenger (mesengers/telegram_aiohttp.py)"):::messengerStyle
    end

    %% Feedback Service Subgraph
    subgraph "Feedback Service"
        FA("Feedback API (feedback_service/main.py)"):::feedbackStyle
        DB("Database Script (feedback_service/script.sql)"):::feedbackStyle
        DOC("Documentation (feedback_service/text.md)"):::feedbackStyle
    end

    %% External Documentation
    EXT("OpenAPI Spec (openAPI.json)"):::externalStyle

    %% Data Flow arrows
    U -->|"sendsAPIRequest"| BA
    U -->|"sendsTelegramMsg"| M
    M -->|"forwardsMessage"| BA
    U -->|"sendsFeedback"| FA

    BA -->|"processes"| CORE
    CORE -->|"invokesLLM"| LLM
    CORE -->|"accessesData"| DS
    CORE -->|"utilizes"| UTIL

    FA -->|"initializes"| DB
    FA -->|"documents"| DOC

    %% Click Events for Bot Service Core Chatbot Logic Files
    click CL "https://github.com/raykov-git/hacaton_2025/blob/main/bot/ClinicBot.py"
    click AB "https://github.com/raykov-git/hacaton_2025/blob/main/bot/abstractBot.py"

    %% Click Event for LLM Integration Directory
    click LLM "https://github.com/raykov-git/hacaton_2025/tree/main/bot/llm"

    %% Click Event for Data Source Management Directory
    click DS "https://github.com/raykov-git/hacaton_2025/tree/main/bot/files"

    %% Click Event for Primary API Endpoint
    click BA "https://github.com/raykov-git/hacaton_2025/blob/main/bot/main.py"

    %% Click Event for Additional Utilities
    click UTIL "https://github.com/raykov-git/hacaton_2025/blob/main/bot/scraper.py"

    %% Click Event for Messenger Integration
    click M "https://github.com/raykov-git/hacaton_2025/blob/main/mesengers/telegram_aiohttp.py"

    %% Click Events for Feedback Service
    click FA "https://github.com/raykov-git/hacaton_2025/blob/main/feedback_service/main.py"
    click DB "https://github.com/raykov-git/hacaton_2025/blob/main/feedback_service/script.sql"
    click DOC "https://github.com/raykov-git/hacaton_2025/blob/main/feedback_service/text.md"

    %% Click Event for External Documentation
    click EXT "https://github.com/raykov-git/hacaton_2025/blob/main/openAPI.json"

    %% Styles
    classDef userStyle fill:#FFE4B5,stroke:#333,stroke-width:2px;
    classDef botStyle fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef messengerStyle fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef feedbackStyle fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef externalStyle fill:#D2B4DE,stroke:#333,stroke-width:2px;
```
