# abhinavexists/relay architecture

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

- Interactive diagram: https://gitdiagram.com/abhinavexists/relay
- Repository: https://github.com/abhinavexists/relay

## Overview

##### Project Type & Purpose
- This is a workflow automation platform that uses artificial intelligence (starting with Google’s Gemini API, with future plans for LangChain and OpenAI) to generate, manage, and execute automated workflows.
- The project integrates a Telegram bot as the user interaction layer, a FastAPI-based backend handling core business logic and data persistence, and external AI services for natural language processing and workflow generation.

##### Main Components & Their Roles
a. Telegram Bot Service (directory: telegram_bot/)
- Manages user interactions (commands, messages, callbacks).
- Integrates with the backend API to process requests and display responses.
- Handles command and message routing via dedicated handlers.

b. Backend API Service (directory: backend/)
- Provides REST endpoints (using FastAPI).
- Contains business logic for workflow orchestration, user authentication, and state management.
- Manages core modules such as API routes, data models, configuration, and utility functions.
- Maintains integrations with databases and internal AI support services.

c. Database
- MongoDB is used for persistent storage (see backend/database/mongodb.py).
- Manages records for users, workflows, and tracking execution history.

d. AI Service
- The current integration is with Google Gemini API under the backend services (e.g., ai_service.py).
- Future design intents include enhancements with LangChain and OpenAI which can be denoted as a modular service that supports natural language processing and command interpretation.

e. Docker & Deployment Scripts
- Dockerfiles (in the docker/ directory) and docker-compose.yml define the containerized deployment of both the backend and Telegram bot.
- Additional scripts like run.sh and setup.sh streamline deployment and configuration.

##### Key Relationships & Interactions
- The Backend encapsulates the AI Service integrations, meaning any business logic requiring natural language processing or command interpretation routes through the AI service module.
- External services (such as Google Gemini API and future AI providers) should be shown as external integrations that feed into the AI Service module.
- Deployment and orchestration components (Docker) can be illustrated as an outer layer that encompasses both the Telegram Bot and Backend API services.

##### Architectural Patterns & Design Principles
- Microservices Architecture: Separate planes for the Telegram bot and Backend API services.
- Modular design: The project separates core logic (business rules, tool orchestration, workflow management) from API routes and Telegram handlers.
- Clear separation of concerns: Dedicated folders for API routes, models, services, and utility functions.
- Use of containerization (with Docker) to achieve isolation and scalability.

##### Detailed Component Breakdown
- Within the Backend API, show subdivisions such as “API Routes” (under backend/api/routes), “Core Business Logic” (backend/core), “Services” (backend/services), “Data Models” (backend/models), and “Utilities” (backend/utils).
- For the Telegram Bot, breakdown handlers (commands and callbacks) and utility functions, which can be depicted as submodules.
- Use notes or legends if necessary to indicate configuration files (like backend/config.py, telegram_bot/config.py) that manage the overall settings and environment variables.

- The Telegram Bot Service as the interface layer that interacts with users.
- The Backend API as the central business logic and RESTful service provider.
- The MongoDB database as the persistence layer.
- The integration with Google Gemini (and the roadmap for LangChain/OpenAI) as the AI service layer.
- The deployed containerized environment using Docker.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment & Orchestration
    subgraph "Deployment & Orchestration"
        D1("Backend Dockerfile"):::deployment
        D2("Bot Dockerfile"):::deployment
        D3("Deployment Scripts"):::deployment
    end

    %% Telegram Bot Service Subgraph
    subgraph "Telegram Bot Service"
        TB1("Bot Entry"):::module
        TB2("Bot Config"):::module
        TB3("Handlers"):::module
        TB4("Utils"):::module
    end

    %% Backend API Service Subgraph
    subgraph "Backend API Service"
        BA1("API Routes"):::module
        BA2("App Startup"):::module
        BA3("Core Business Logic"):::module
        BA4("Configuration"):::module
    end

    %% Database Node
    DB("MongoDB Database"):::database

    %% AI Service Node
    AI("AI Service"):::module

    %% External AI Providers Node
    EXT("External AI Providers"):::external

    %% Connections between Telegram Bot and Backend API
    TB1 <-->|"command"| BA2

    %% Deployment orchestration connections
    D3 -->|"orchestrates"| TB1
    D3 -->|"orchestrates"| BA2

    %% Backend connections
    BA2 -->|"data-persistence"| DB
    BA2 -->|"workflow-processing"| AI

    %% External AI integration
    EXT -->|"NLP-integration"| AI

    %% Styles
    classDef deployment fill:#fff3cd,stroke:#664d03,stroke-width:2px;
    classDef module fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef database fill:#d1e7dd,stroke:#0f5132,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#842029,stroke-width:2px;

    %% Click Events for Telegram Bot Service
    click TB1 "https://github.com/abhinavexists/relay/blob/master/telegram_bot/bot.py"
    click TB2 "https://github.com/abhinavexists/relay/blob/master/telegram_bot/config.py"
    click TB3 "https://github.com/abhinavexists/relay/tree/master/telegram_bot/handlers/"
    click TB4 "https://github.com/abhinavexists/relay/tree/master/telegram_bot/utils/"

    %% Click Events for Backend API Service
    click BA1 "https://github.com/abhinavexists/relay/tree/master/backend/api/routes"
    click BA2 "https://github.com/abhinavexists/relay/blob/master/backend/main.py"
    click BA3 "https://github.com/abhinavexists/relay/tree/master/backend/core/"
    click BA4 "https://github.com/abhinavexists/relay/blob/master/backend/config.py"

    %% Click Event for Database
    click DB "https://github.com/abhinavexists/relay/blob/master/backend/database/mongodb.py"

    %% Click Event for AI Service
    click AI "https://github.com/abhinavexists/relay/blob/master/backend/services/ai_service.py"

    %% Click Events for Deployment & Orchestration
    click D1 "https://github.com/abhinavexists/relay/tree/master/docker/backend/Dockerfile"
    click D2 "https://github.com/abhinavexists/relay/tree/master/docker/bot/Dockerfile"
    click D3 "https://github.com/abhinavexists/relay/blob/master/docker-compose.yml"
```
