How mallahyari/calibot works
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.