# nicoeugui/telegram-bank-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/nicoeugui/telegram-bank-assistant
- Repository: https://github.com/nicoeugui/telegram-bank-assistant

## Overview

##### Project type and purpose
- This is a conversational banking assistant bot (“Asistente NicoBank”) built in Python.
- It integrates with Telegram, LangChain, OpenAI (GPT-4 and Whisper), Redis, and is packaged with Docker.
- Purpose: receive text or voice messages, route them through a LangChain “conversation agent,” invoke domain-specific “tools” (balance, transactions, loan simulation), persist state in Redis, and return responses to the user.

##### File structure
- Top-level:
- bot/ – the application code
– agent/ (conversation_agent.py) – orchestrates LangChain chains & tool routing
– handlers/ – Telegram update handlers (text, audio, errors)
– prompts/ – system prompt templates
– services/ – glue code for Redis, interaction counting, humanization, transcription
– tools/ – LangChain-exposed business logic functions (authenticate, get_balance, etc.)
– utils/ – FFmpeg audio conversion, time utilities
- main.py – entrypoint, initializes Telegram Bot and LangChain agent
- config.py – environment loader and validation
- Dockerfile + docker-compose-*.yml – container definitions for dev & prod
- .github/workflows/deploy.yml – CI/CD pipeline
- tests/ – pytest suites for services and tools

##### README for additional insights
- The architecture section already shows a high-level flow:
User → Telegram → Handler → LangChain Agent → Tools → Redis
- It also mentions external calls to OpenAI APIs (GPT, Whisper) and FFmpeg for audio.

##### Detail
- TTL and state keys in Redis (e.g., auth_state:{user_id}).
- Docker Compose layering (dev vs prod) if space allows.
- CI/CD pipeline at the bottom: GitHub Actions → SSH-action → Production Docker Compose.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    User["User (Telegram Client)"]:::external
    TelegramAPI["Telegram API"]:::external
    OpenAIGPT["OpenAI GPT-4/GPT-4o"]:::external
    OpenAIWhisper["OpenAI Whisper API"]:::external
    RedisDB[(Redis Database)]:::datastore
    FFmpeg["FFmpeg Service"]:::external
    GitHubActions["GitHub Actions"]:::external
    ProdServer["Production Server"]:::external

    %% Bot Service Container
    subgraph "Bot Service (Docker Container)" 
        direction TB
        Config["Config Loader\n(config.py)"]:::internal
        Prompts["System Prompts\n(bot/prompts)"]:::internal
        Main["Entrypoint\n(main.py)"]:::internal

        subgraph "Handlers Module" 
            direction TB
            MessageHandler["Message Handler\n(bot/handlers/message_handler.py)"]:::internal
            AudioHandler["Audio Handler\n(bot/handlers/audio_handler.py)"]:::internal
            ErrorHandler["Error Handler\n(bot/handlers/global_error_handler.py)"]:::internal
        end

        Agent["LangChain Conversation Agent\n(bot/agent/conversation_agent.py)"]:::internal

        subgraph "Tools Module" 
            direction TB
            AuthUser["Authenticate User\n(bot/tools/authenticate_user.py)"]:::internal
            CheckAuth["Check Authentication\n(bot/tools/check_authentication.py)"]:::internal
            GetBalance["Get Balance\n(bot/tools/get_balance.py)"]:::internal
            GetTransactions["Get Transactions\n(bot/tools/get_transactions.py)"]:::internal
            GetLoanHistory["Get Loan History\n(bot/tools/get_loan_history.py)"]:::internal
            LoanSimulation["Loan Simulation\n(bot/tools/loan_simulation.py)"]:::internal
        end

        subgraph "Services Module" 
            direction TB
            RedisService["Redis Service\n(bot/services/redis_service.py)"]:::internal
            InteractionTracker["Interaction Tracker\n(bot/services/interaction_tracker.py)"]:::internal
            ResponseHumanizer["Response Humanizer\n(bot/services/response_humanizer.py)"]:::internal
            WhisperTranscriber["Whisper Transcriber\n(bot/services/whisper_transcriber.py)"]:::internal
        end

        subgraph "Utils Module" 
            direction TB
            AudioConverter["Audio Converter\n(bot/utils/audio_converter.py)"]:::internal
            TimeHelpers["Time Helpers\n(bot/utils/time_helpers.py)"]:::internal
        end
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        direction TB
        GH[".github/workflows/deploy.yml"]:::internal
        DevCompose["docker-compose-development.yml"]:::internal
        ProdCompose["docker-compose-production.yml"]:::internal
        Dockerfile["Dockerfile"]:::internal
    end

    %% Flows
    User -->|"sends message"| TelegramAPI
    TelegramAPI -->|"Webhook"| MessageHandler
    TelegramAPI -->|"Webhook"| AudioHandler
    TelegramAPI -->|"Error"| ErrorHandler

    AudioHandler -->|"ogg file"| AudioConverter
    AudioConverter -->|"wav file"| WhisperTranscriber
    WhisperTranscriber -->|"text transcript"| Agent

    MessageHandler -->|"text message"| Agent
    ErrorHandler -->|"error| logs"| Agent

    Agent -->|"uses config"| Config
    Agent -->|"loads prompts"| Prompts
    Agent -->|"calls tool"| AuthUser
    Agent -->|"calls tool"| CheckAuth
    Agent -->|"calls tool"| GetBalance
    Agent -->|"calls tool"| GetTransactions
    Agent -->|"calls tool"| GetLoanHistory
    Agent -->|"calls tool"| LoanSimulation

    Agent -->|"calls service"| RedisService
    Agent -->|"calls service"| InteractionTracker
    Agent -->|"calls service"| ResponseHumanizer
    Agent -->|"calls service"| WhisperTranscriber

    Agent -->|"HTTP API calls"| OpenAIGPT
    WhisperTranscriber -->|"POST /transcriptions"| OpenAIWhisper

    RedisService -->|"GET/SET user:auth_state"| RedisDB
    InteractionTracker -->|"LOG usage"| RedisDB

    AudioConverter -->|"ffmpeg CLI"| FFmpeg

    %% CI/CD Flow
    GH -->|runs tests| Tests["Pytest Suites"]:::internal
    Tests -->|on success| DevCompose
    DevCompose -->|build container| Dockerfile
    Dockerfile -->|deploy via SSH| ProdServer
    ProdServer -->|runs| ProdCompose

    %% Click events
    click MessageHandler "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/handlers/message_handler.py"
    click AudioHandler "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/handlers/audio_handler.py"
    click ErrorHandler "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/handlers/global_error_handler.py"
    click Agent "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/agent/conversation_agent.py"
    click AuthUser "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/tools/authenticate_user.py"
    click CheckAuth "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/tools/check_authentication.py"
    click GetBalance "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/tools/get_balance.py"
    click GetTransactions "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/tools/get_transactions.py"
    click GetLoanHistory "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/tools/get_loan_history.py"
    click LoanSimulation "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/tools/loan_simulation.py"
    click RedisService "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/services/redis_service.py"
    click InteractionTracker "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/services/interaction_tracker.py"
    click ResponseHumanizer "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/services/response_humanizer.py"
    click WhisperTranscriber "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/services/whisper_transcriber.py"
    click AudioConverter "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/utils/audio_converter.py"
    click TimeHelpers "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/utils/time_helpers.py"
    click Prompts "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/bot/prompts/system_prompts.py"
    click Config "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/config.py"
    click Main "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/main.py"
    click Dockerfile "https://github.com/nicoeugui/telegram-bank-assistant/tree/main/Dockerfile"
    click DevCompose "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/docker-compose-development.yml"
    click ProdCompose "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/docker-compose-production.yml"
    click GH "https://github.com/nicoeugui/telegram-bank-assistant/blob/main/ .github/workflows/deploy.yml"

    %% Styles
    classDef internal fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef external fill:#fff3e0,stroke:#e65100,color:#bf360c
    classDef datastore fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
```
