# regisleandro/alfredo_ai architecture

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

- Interactive diagram: https://gitdiagram.com/regisleandro/alfredo_ai
- Repository: https://github.com/regisleandro/alfredo_ai

## Overview

##### Project Type and Purpose
- This is a full‐stack, event-driven chatbot application demonstrating communication via RabbitMQ.
- It provides a Streamlit front-end for user interaction, a Python “api” service that processes messages, and integrations with external systems (MongoDB, GitHub, Trello, Pulpo, Google Chat).

##### High-Level Components
- Streamlit Front-end (streamlit_app.py)
- Message Broker (RabbitMQ service)
- API Worker Service (api/main.py + pkg/ modules)
- Formatter Submodule (api/formatters)
- Integration Clients (pkg/github.py, pkg/trello.py, pkg/mongo.py, pkg/pulpo.py, pkg/file_processor.py, pkg/task_analyst.py)
- External Services (GitHub, Trello, Pulpo API, MongoDB)
- Optional Node Connector (alfredo_rocket/alfredo_rocket.js) for Google Chat webhook

##### Relationships and Data Flow
- User → Streamlit UI: User submits a prompt or file via the Streamlit web app.
- Streamlit → RabbitMQ Exchange: The app publishes messages to a RabbitMQ queue.
- RabbitMQ → API Worker: The API service (api/main.py) consumes messages.
- API Worker → pkg Modules: The worker uses pkg/task_analyst, pkg/file_processor, pkg/constants to interpret the request.
- API Worker → External Clients: It calls pkg/github, pkg/trello, pkg/pulpo, or pkg/mongo to perform actions or store data.
- API Worker → Formatters: It passes results to api/formatters to generate human-readable responses.
- Formatter → RabbitMQ (or Webhook): Formatted responses are published back to RabbitMQ or sent to Google Chat via the Node connector.
- Node Connector → Google Chat: The alfredo_rocket service posts messages to Google Chat.

##### Key Architectural Patterns
- Event-Driven / Message Queue: All requests and responses flow through RabbitMQ to decouple front-end and back-end.
- Modular Service Design: Core logic is split into small, focused modules under pkg.
- Adapter/Formatter Layer: api/formatters isolates all output formatting.
- External-Integration Clients: Each external service has its own client module.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Front-end & UI
    subgraph "Front-end & UI"
        Streamlit["Streamlit Front-end"]:::frontend
    end

    %% Messaging Infrastructure
    subgraph "Messaging Infrastructure"
        RabbitMQ["RabbitMQ Broker"]:::mq
    end

    %% Processing Service
    subgraph "API Worker Service"
        APIWorker["API Worker\n(api/main.py)"]:::processor
        subgraph "Worker Modules"
            TaskAnalyst["Task Analyst\n(pkg/task_analyst.py)"]:::processor
            FileProcessor["File Processor\n(pkg/file_processor.py)"]:::processor
            Constants["Shared Constants\n(pkg/constants.py)"]:::processor
        end
        subgraph "Integration Clients"
            GitHub["GitHub Client\n(pkg/github.py)"]:::external
            Trello["Trello Client\n(pkg/trello.py)"]:::external
            MongoClient["MongoDB Client\n(pkg/mongo.py)"]:::external
            Pulpo["Pulpo Client\n(pkg/pulpo.py)"]:::external
        end
    end

    %% Formatter Submodule
    subgraph "Formatter Submodule\n(api/formatters/)"
        Translator["Response Translator\n(google_chat.py)"]:::formatter
        GChatFmt["Google Chat Adapter\n(google_chat.py)"]:::formatter
    end

    %% Node Connector
    NodeConnector["Node Connector\n(alfredo_rocket.js)"]:::external

    %% External Services
    subgraph "External Systems"
        GitHubAPI["GitHub"]:::service
        TrelloAPI["Trello"]:::service
        PulpoAPI["Pulpo"]:::service
        MongoDB["MongoDB"]:::db
        GoogleChat["Google Chat"]:::service
    end

    %% Deployment
    dockercompose["docker-compose.yml"]:::infra

    %% Request Flow
    Streamlit -->|"ChatMessage\n(HTTP POST)"| RabbitMQ
    RabbitMQ -->|"Consume Message"| APIWorker
    APIWorker -->|"analyzeTask()"| TaskAnalyst
    APIWorker -->|"processFile()"| FileProcessor
    APIWorker -->|"loadConstants()"| Constants
    APIWorker -->|"callClient()"| GitHub
    APIWorker -->|"callClient()"| Trello
    APIWorker -->|"callClient()"| MongoClient
    APIWorker -->|"callClient()"| Pulpo

    GitHub -->|"API Requests"| GitHubAPI
    Trello -->|"API Requests"| TrelloAPI
    Pulpo -->|"API Requests"| PulpoAPI
    MongoClient -->|"DB Operations"| MongoDB

    APIWorker -->|"rawResult"| Translator
    Translator -->|"formattedMsg"| GChatFmt

    %% Response Flow
    GChatFmt -.->|"FormattedResponse"| RabbitMQ
    RabbitMQ -.->|"deliverResponse"| Streamlit
    GChatFmt -->|"WebhookPayload"| NodeConnector
    NodeConnector -->|"POST Message"| GoogleChat

    %% Orchestration
    dockercompose --> Streamlit
    dockercompose --> RabbitMQ
    dockercompose --> APIWorker
    dockercompose --> NodeConnector
    dockercompose --> MongoDB

    %% Click Events
    click Streamlit "https://github.com/regisleandro/alfredo_ai/blob/main/streamlit_app.py"
    click RabbitMQ "https://github.com/regisleandro/alfredo_ai/blob/main/pkg/rabbit.py"
    click APIWorker "https://github.com/regisleandro/alfredo_ai/blob/main/api/main.py"
    click Translator "https://github.com/regisleandro/alfredo_ai/blob/main/api/formatters/response_translator.py"
    click GChatFmt "https://github.com/regisleandro/alfredo_ai/blob/main/api/formatters/google_chat.py"
    click TaskAnalyst "https://github.com/regisleandro/alfredo_ai/blob/main/pkg/task_analyst.py"
    click FileProcessor "https://github.com/regisleandro/alfredo_ai/blob/main/pkg/file_processor.py"
    click Constants "https://github.com/regisleandro/alfredo_ai/blob/main/pkg/constants.py"
    click GitHub "https://github.com/regisleandro/alfredo_ai/blob/main/pkg/github.py"
    click Trello "https://github.com/regisleandro/alfredo_ai/blob/main/pkg/trello.py"
    click MongoClient "https://github.com/regisleandro/alfredo_ai/blob/main/pkg/mongo.py"
    click Pulpo "https://github.com/regisleandro/alfredo_ai/blob/main/pkg/pulpo.py"
    click NodeConnector "https://github.com/regisleandro/alfredo_ai/blob/main/alfredo_rocket/alfredo_rocket.js"
    click dockercompose "https://github.com/regisleandro/alfredo_ai/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#339af0,color:#1c7ed6;
    classDef mq fill:#ffe8cc,stroke:#fd7e14,color:#d9480f;
    classDef processor fill:#d8f5a2,stroke:#51cf66,color:#2b8a3e;
    classDef formatter fill:#e7f5ff,stroke:#74c0fc,color:#1c7ed6;
    classDef external fill:#ffe3e3,stroke:#fa5252,color:#c92a2a;
    classDef service fill:#ffd8a8,stroke:#fd7e14,color:#d9480f;
    classDef db fill:#e5dbff,stroke:#845ef7,color:#5f3dc4;
    classDef infra fill:#f1f3f5,stroke:#868e96,color:#495057;
```
