# mallahyari/calibot architecture

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

- Interactive diagram: https://gitdiagram.com/mallahyari/calibot
- Repository: https://github.com/mallahyari/calibot

## Overview

##### Main Components
- Backend API Server: Represented by the FastAPI-based server. It serves as the entry point (backend/app/main.py) and orchestrates incoming requests.
- NLP Agent: Located under backend/app/agent; it is responsible for natural language processing and intent recognition.
- AI Service: Part of backend/app/services (ai_service.py) that manages conversation flow and leverages GPT-4o through LiteLLM.
- Google Calendar Service: Found in backend/app/services (google_calendar.py) which interfaces with the Google Calendar API and manages authentication (OAuth 2.0).
- Telegram Service: Located in backend/app/services (telegram.py) which handles communication with the Telegram Bot API.
- API Endpoints: Defined in backend/app/api (routes, models) to expose functionalities and support webhooks (for example, updating backend_url dynamically as required by NGROK tunneling).

##### Relationships and Data Flow
- Entry Point & API Layer: The FastAPI application (from main.py) receives incoming HTTP requests. Using defined routes in the API folder, these requests might trigger different services.
- NLP Agent Interaction: User messages flowing from the Telegram Service are forwarded to the NLP Agent to extract intents and necessary details.
- AI & Service Coordination: Based on NLP output, the AI Service processes conversation context and determines the next steps, possibly coordinating with Google Calendar Service for calendar operations.
- External Integrations: Include connections to external systems such as Google Calendar (using OAuth 2.0) and Telegram (via webhooks and Telegram Bot API).

##### Architectural Patterns and Notable Design Choices
- Modular Separation: The system is clearly separated into functional modules (agent, services, API, and utils). This promotes reusability and easy maintenance.
- Service-Oriented: Each service (e.g., AI, Google Calendar, Telegram) is encapsulated in its own module, with each service interacting through well-defined endpoints.
- Integration Focus: The architecture emphasizes external API integrations (Google Calendar API and Telegram Bot API) and natural language processing.

##### Relevant Technologies and Frameworks
- FastAPI: Underpins the backend server and API endpoints.
- LiteLLM: Provides the AI and language model integration.
- Google API Client: For handling interactions with the Google Calendar API.
- Python-Telegram-Bot: Manages the Telegram communication layer.
- OAuth 2.0: Implements secure authentication with Google.

## Diagram (Mermaid)

```mermaid
flowchart TD
    H["Telegram API"]:::external
    A["FastAPI Server"]:::server
    subgraph "API Endpoints"
        routes["API Routes"]:::api
        models["API Models"]:::api
    end
    C["NLP Agent"]:::agent
    D["AI Service"]:::service
    E["Google Calendar Service"]:::service
    F["Telegram Service"]:::service
    G["Google Calendar API"]:::external

    H -->|"Webhook_HTTP"| A
    A -->|"exposes_endpoints"| routes
    A -->|"processes_message"| C
    C -->|"extracts_intent"| D
    D -->|"create_event"| E
    D -->|"send_response"| F
    E -->|"calendar_API_call"| G
    F -->|"send_message"| H

    click A "https://github.com/mallahyari/calibot/blob/main/backend/app/main.py"
    click C "https://github.com/mallahyari/calibot/blob/main/backend/app/agent/nlp_agent.py"
    click D "https://github.com/mallahyari/calibot/blob/main/backend/app/services/ai_service.py"
    click E "https://github.com/mallahyari/calibot/blob/main/backend/app/services/google_calendar.py"
    click F "https://github.com/mallahyari/calibot/blob/main/backend/app/services/telegram.py"
    click routes "https://github.com/mallahyari/calibot/blob/main/backend/app/api/routes.py"
    click models "https://github.com/mallahyari/calibot/blob/main/backend/app/api/models.py"

    classDef server fill:#f9f,stroke:#333,stroke-width:2px;
    classDef agent fill:#bbf,stroke:#333,stroke-width:2px;
    classDef service fill:#bfb,stroke:#333,stroke-width:2px;
    classDef api fill:#ff9,stroke:#333,stroke-width:2px;
    classDef external fill:#fcc,stroke:#333,stroke-width:2px;
```
