# andresroblesb/crewai-assistant-google-tools architecture

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

- Interactive diagram: https://gitdiagram.com/andresroblesb/crewai-assistant-google-tools
- Repository: https://github.com/andresroblesb/crewai-assistant-google-tools

## Overview

Para dibujar un diagrama de arquitectura claro y preciso para este proyecto “Asistente IA con Google Calendar y Gmail”, sigue estos pasos adaptados a su tipología de bot conversacional con agentes AI:

##### Identificar el tipo y propósito del proyecto
- Este es un bot conversacional en Python que actúa como asistente personal: recibe comandos en lenguaje natural vía Telegram (o consola), los envía a un motor de agentes AI (CrewAI), procesa las respuestas y llama a las APIs de Gmail y Calendar de Google.
- Emplea también la API de OpenAI para procesamiento de lenguaje natural y OAuth2 para autenticación con Google.

##### Analizar la estructura de carpetas
- bot.py: punto de entrada para Telegram (o pruebas directas).
- crew.py: configuración y orquestación de los agentes de CrewAI.
- tools/: módulos que encapsulan la lógica de llamadas a servicios externos:
- gmail_tools.py
- calendar_tools.py
- utils/: utilidades transversales, p.ej. google_auth.py para manejar OAuth2 con Google.
- img/, requirements.txt, .env/.gitignore, etc.

##### Extraer insights del README
- Diagrama lógico: Usuario ←→ Telegram Bot ←→ CrewAI Agents ←→ Herramientas (Gmail/Calendar) ←→ Google APIs.
- Dependencias clave: Python 3.10+, python-telegram-bot, openai, google-auth, CrewAI.

##### Componentes principales y sus interacciones
a) Frontend de mensajería:
- Componente “Telegram Bot” (bot.py) recibe mensajes del usuario y los envía al motor AI.
b) Orquestador AI:
- “CrewAI Engine” (crew.py) configura agentes y tareas, envía prompts a OpenAI y decide qué herramienta invocar.
c) Capa de herramientas:
- Módulos gmail_tools.py y calendar_tools.py implementan las llamadas a las APIs de Google.
d) Autenticación:
- google_auth.py gestiona el flujo OAuth2, almacenamiento y renovación de tokens.
e) Servicios externos:
- OpenAI API (LLM), Google Gmail API, Google Calendar API.

Las flechas de datos son:
Usuario → Telegram Bot → CrewAI Engine → (OpenAI API + herramientas) → Google APIs → CrewAI → Telegram Bot → Usuario

##### Patrones y principios arquitectónicos
- Separación de responsabilidades:
- Bot (entrada/salida)
- Orquestación de agentes
- Adaptadores de servicios externos (tools/)
- Gestión de autenticación (utils/)
- “Pipelines” de procesamiento de mensaje en fases: recepción, análisis/decisión, ejecución externa, respuesta.
- Uso de “command pattern” o “tool invocation pattern” de CrewAI para aislar cada tarea (p.ej. buscar correos vs crear eventos).

##### Tecnologías y librerías clave
- Python 3.10+, python-telegram-bot
- crewai (motor de agentes)
- openai (procesamiento de lenguaje)
- google-auth, google-api-python-client (Gmail y Calendar)
- asyncio para pruebas directas

##### Guía para plasmar el diagrama
- Divide el diagrama en capas horizontales o verticales según tu preferencia:
Capa Usuario → Capa Bot → Capa AI / LLM → Capa Herramientas → Capa Servicios Externos.
- Usa rectángulos o cajas para cada componente: “Telegram Bot”, “CrewAI Engine”, “google_auth”, “gmail_tools”, “calendar_tools”, “OpenAI API”, “Google Gmail API”, “Google Calendar API”.
- Dibuja flechas direccionadas que indiquen el flujo de información y las dependencias:
- Desde el usuario al bot y de vuelta.
- Del bot a CrewAI Engine.
- Del engine a OpenAI API y/o a los módulos tools.
- De tools a Google APIs y de regreso.
- Emplea colores o formas distintas para diferenciar:
- Componentes internos (blanco o gris claro).
- Servicios de terceros (azul).
- Lógica de negocio / agentes AI (verde).

##### Elementos esenciales a incluir
- Etiquetas claras con nombre de cada módulo o servicio.
- Flechas con anotaciones breves como “API call”, “Prompt”, “OAuth2 token”.
- Leyenda de colores o formas.
- Notas sobre puertos/endpoints relevantes (p.ej. webhook de Telegram).

Con este esquema tendrás un diagrama detallado que refleja fielmente la arquitectura del asistente: la interacción del usuario, la capa conversacional, la orquestación de agentes AI, la autenticación y las integraciones con Google y OpenAI.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    Usuario("Usuario"):::external

    %% Bot Layer
    subgraph "Bot Layer"
        TelegramBot["Telegram Bot"]:::internal
    end

    %% AI Layer
    subgraph "AI Layer"
        CrewAIEngine["CrewAI Engine"]:::ai
    end

    %% Tools Layer
    subgraph "Tools Layer"
        ToolsInit["tools/__init__.py"]:::tool
        GmailTools["gmail_tools.py"]:::tool
        CalendarTools["calendar_tools.py"]:::tool
        UtilsInit["utils/__init__.py"]:::auth
        GoogleAuth["google_auth.py"]:::auth
    end

    %% External Services
    subgraph "External Services"
        OpenAIAPI["OpenAI API"]:::thirdparty
        GoogleGmailAPI["Google Gmail API"]:::thirdparty
        GoogleCalendarAPI["Google Calendar API"]:::thirdparty
    end

    %% Connections
    Usuario -->|"mensaje"| TelegramBot
    TelegramBot -->|"prompt"| CrewAIEngine
    CrewAIEngine -->|"API call"| OpenAIAPI
    CrewAIEngine -->|"invoke tool"| GmailTools
    CrewAIEngine -->|"invoke tool"| CalendarTools
    GmailTools -->|"API call"| GoogleGmailAPI
    CalendarTools -->|"API call"| GoogleCalendarAPI
    GoogleGmailAPI -->|"response"| GmailTools
    GoogleCalendarAPI -->|"response"| CalendarTools
    OpenAIAPI -->|"respuesta LLM"| CrewAIEngine
    CrewAIEngine -->|"respuesta procesada"| TelegramBot
    TelegramBot -->|"mensaje respuesta"| Usuario

    %% Authentication flow
    GmailTools -->|"request token"| GoogleAuth
    CalendarTools -->|"request token"| GoogleAuth
    GoogleAuth -->|"token"| GmailTools
    GoogleAuth -->|"token"| CalendarTools
    GoogleAuth -->|"init"| UtilsInit
    GmailTools -->|"init"| ToolsInit
    CalendarTools -->|"init"| ToolsInit

    %% Click Events
    click TelegramBot "https://github.com/andresroblesb/crewai-assistant-google-tools/blob/main/bot.py"
    click CrewAIEngine "https://github.com/andresroblesb/crewai-assistant-google-tools/blob/main/crew.py"
    click GmailTools "https://github.com/andresroblesb/crewai-assistant-google-tools/blob/main/tools/gmail_tools.py"
    click CalendarTools "https://github.com/andresroblesb/crewai-assistant-google-tools/blob/main/tools/calendar_tools.py"
    click GoogleAuth "https://github.com/andresroblesb/crewai-assistant-google-tools/blob/main/utils/google_auth.py"
    click ToolsInit "https://github.com/andresroblesb/crewai-assistant-google-tools/blob/main/tools/tools_init.py"
    click UtilsInit "https://github.com/andresroblesb/crewai-assistant-google-tools/blob/main/utils/utils_init.py"

    %% Styles
    classDef internal fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef ai fill:#d4f4dd,stroke:#333,stroke-width:1px
    classDef tool fill:#fff4d6,stroke:#333,stroke-width:1px
    classDef auth fill:#ffe4b2,stroke:#333,stroke-width:1px
    classDef thirdparty fill:#d6eaff,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
```
