# sircodak/aguasanfogasta_chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/sircodak/aguasanfogasta_chatbot
- Repository: https://github.com/sircodak/aguasanfogasta_chatbot

## Overview

##### Project Type and Purpose
- This is a backend-heavy, full-stack chat-bot service built in Python.
- It exposes an HTTP endpoint for Microsoft Teams, orchestrates multiple AI and data-storage services, and persists conversational state.

##### Main Components
a. Bot Container
- A Dockerized Python application (app.py entry point) running behind Bot Framework
- Hosts modules:
- Bot_Asistente.py (Teams message handling and orchestration)
- OpenAI_Connection.py (OpenAI Assistants API wrapper)
- AzureGPT.py (Azure OpenAI “question improvement”)
- Redis_Connection.py (state persistence)
- Auth_ApiGraph.py (Microsoft Graph/SharePoint integration)
b. External Services
- Microsoft Teams (client channel)
- Azure Bot Framework endpoint (channel service)
- Azure OpenAI API
- OpenAI Assistants API
- Redis cache for conversation state
- SharePoint/Graph API for documents
- Vector Storage (semantic search index)
c. Cron/Sync Scheduler
- A scheduled job (inside the bot container or separate sidecar) that every 90 minutes pulls docs from SharePoint, processes them into embeddings, and updates vector store.

##### Relationships and Data Flows
- User → Teams client → Bot Framework endpoint → Bot Container (HTTP /api/messages)
- Bot Container:
1. Auth_ApiGraph retrieves user department and SharePoint docs
2. Redis_Connection looks up or initializes conversation state
3. If user question incomplete, AzureGPT module enriches it
4. OpenAI_Connection forwards enriched or original prompt to the correct assistant instance
5. Bot_Asistente formats the AI reply and responds back to Teams
- Sync Scheduler:
- Periodically triggers Auth_ApiGraph → fetch documents → compute embeddings → push to Vector Storage
- All modules read config from environment (config.py)

##### Architectural Patterns and Principles
- Modular service: each major integration (Redis, OpenAI, GraphAPI) is encapsulated in its own module
- Dependency injection via environment-based config classes
- Stateful vs stateless separation: conversation state in Redis, processing logic in the Python container
- Scheduled batch job for document ingestion

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        direction TB
        Teams["Microsoft Teams<br/>(Client)"]:::external
        BotFramework["Azure Bot Framework<br/>(Channel)"]:::external
        AzureOpenAI["Azure OpenAI API"]:::external
        OpenAIAssist["OpenAI Assistants API"]:::external
        SharePoint["SharePoint / Graph API"]:::external
        RedisDB["Redis Cache"]:::datastore
        VectorStore["Vector Storage"]:::datastore
    end

    %% Bot Service Container
    subgraph "Bot Service"
        direction TB
        APP["app.py<br/>(/api/messages)"]:::internal
        BotAsist["Bot_Asistente"]:::internal
        Auth["Auth_ApiGraph"]:::internal
        RedisCon["Redis_Connection"]:::internal
        AzureGPT["AzureGPT"]:::internal
        OpenAIConn["OpenAI_Connection"]:::internal
        Scheduler["Scheduler"]:::scheduler
        Config["config.py"]:::internal
    end

    %% Project Files
    subgraph "Project Files"
        direction TB
        F1["app.py"]:::files
        F2["config.py"]:::files
        F3["Dockerfile"]:::files
        F4["docker-compose.yml"]:::files
        F5["requirements.txt"]:::files
        F6["README.md"]:::files
        F7[".gitignore"]:::files
    end

    %% Real-time Conversation Flow
    Teams -->|"HTTP: /api/messages"| BotFramework
    BotFramework -->|"POST /api/messages"| APP
    APP -->|orchestrates| BotAsist
    BotAsist -->|"getUserInfo"| Auth
    Auth -->|"Graph API call"| SharePoint
    BotAsist -->|"fetchState"| RedisCon
    RedisCon -->|"Redis protocol"| RedisDB
    BotAsist -->|"enrichQuestion"| AzureGPT
    AzureGPT -->|"HTTP request"| AzureOpenAI
    BotAsist -->|"sendPrompt"| OpenAIConn
    OpenAIAssist -->|"HTTP"| OpenAIAssist
    OpenAIAssist -->|"response"| OpenAIConn
    OpenAIConn -->|"AI Response"| BotAsist
    BotAsist -->|"reply"| APP
    APP -->|"HTTP Response"| BotFramework
    BotFramework -->|"delivers"| Teams

    %% Asynchronous Sync Flow
    Scheduler -->|"syncDocs"| Auth
    Auth -->|"fetchDocs"| SharePoint
    Auth -->|"indexEmbeddings"| VectorStore

    %% Config Injection
    Config --> APP
    Config --> BotAsist
    Config --> Auth
    Config --> RedisCon
    Config --> AzureGPT
    Config --> OpenAIConn
    Config --> Scheduler

    %% Click Events
    click F1 "https://github.com/sircodak/aguasanfogasta_chatbot/blob/main/app.py"
    click F2 "https://github.com/sircodak/aguasanfogasta_chatbot/blob/main/config.py"
    click F3 "https://github.com/sircodak/aguasanfogasta_chatbot/tree/main/Dockerfile"
    click F4 "https://github.com/sircodak/aguasanfogasta_chatbot/blob/main/docker-compose.yml"
    click F5 "https://github.com/sircodak/aguasanfogasta_chatbot/blob/main/requirements.txt"
    click F6 "https://github.com/sircodak/aguasanfogasta_chatbot/blob/main/README.md"
    click F7 "https://github.com/sircodak/aguasanfogasta_chatbot/blob/main/.gitignore"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#1E70BF,color:#000;
    classDef external fill:#FFE1B3,stroke:#BF6E1E,color:#000;
    classDef datastore fill:#D4FFD4,stroke:#3E8E3E,color:#000;
    classDef scheduler fill:#E8D0FF,stroke:#6E1EBF,color:#000;
    classDef files fill:#F0F0F0,stroke:#CCCCCC,color:#000;
```
