# xditya/geminibot architecture

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

- Interactive diagram: https://gitdiagram.com/xditya/geminibot
- Repository: https://github.com/xditya/geminibot

## Overview

##### Project type and purpose
- From the file tree and README, this is a Deno-based Telegram chatbot (“GeminiChatBot”) that proxies user messages from Telegram to Google’s Gemini API and returns responses. It’s essentially a small, single-service backend (an open-source bot) rather than a traditional full-stack web application.

##### File structure
- Top-level files and their roles:
- main.ts – Entry point, initializes the bot and ties modules together.
- bot.ts – Contains logic for interacting with the Telegram Bot API (receiving updates, sending messages).
- gemini.ts – Wrapper for Google’s Gemini API calls (request/response handling).
- db.ts – Database layer or persistence (e.g., storing chat history, user state).
- env.ts – Loads and exposes environment variables (API keys, DB connection strings).
- import_map.json + deno.json – Deno configuration and module resolution.
- README.md – Project overview.
- .gitignore/.vscode – Dev tooling config.

##### README for additional insights
- It confirms use of Google’s Gemini API (free tier) and the Telegram Bot platform. No other external services are mentioned.

##### Detailed capture of essential elements
- Config Loader
- Telegram Handler
- Business Logic / Orchestrator
- Gemini Client
- Data Store
- This granularity will help onboard engineers see where to add features (e.g., plug in another LLM adapter) and understand failure points (e.g., DB down, Gemini API rate limit).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Services"
        Telegram["Telegram Platform"]:::external
        Gemini["Google Gemini API"]:::external
    end

    subgraph "Deno Bot Service"
        Env["Env Loader"]:::config
        Bot["Telegram Adapter"]:::internal
        Orch["Application Orchestrator"]:::internal
        GeminiAdapter["Gemini Adapter"]:::internal
        DB["Persistence Layer"]:::db
    end

    subgraph "Configuration & Docs"
        DenoConfig["deno.json"]:::config
        ImportMap["import_map.json"]:::config
        README["README.md"]:::docs
        GitIgnore[".gitignore"]:::configs
        VSCode[".vscode"]:::configs
    end

    Telegram -->|"Update via Webhook/Long Polling"| Bot
    Bot -->|"Parsed message event"| Orch
    Orch -->|"Load environment variables"| Env
    Orch -->|"Log/fetch user context"| DB
    Orch -->|"Forward message"| GeminiAdapter
    GeminiAdapter -->|"REST API call"| Gemini
    Gemini -->|"Generated response"| GeminiAdapter
    Orch -->|"Store response"| DB
    Orch -->|"Send response to user"| Bot

    click Env "https://github.com/xditya/geminibot/blob/main/env.ts"
    click Bot "https://github.com/xditya/geminibot/blob/main/bot.ts"
    click Orch "https://github.com/xditya/geminibot/blob/main/main.ts"
    click GeminiAdapter "https://github.com/xditya/geminibot/blob/main/gemini.ts"
    click DB "https://github.com/xditya/geminibot/blob/main/db.ts"
    click DenoConfig "https://github.com/xditya/geminibot/blob/main/deno.json"
    click ImportMap "https://github.com/xditya/geminibot/blob/main/import_map.json"
    click README "https://github.com/xditya/geminibot/blob/main/README.md"
    click GitIgnore "https://github.com/xditya/geminibot/blob/main/.gitignore"
    click VSCode "https://github.com/xditya/geminibot/blob/main/.vscode"

    classDef external fill:#f3e5f5,stroke:#9c27b0,stroke-width:1px;
    classDef internal fill:#e3f2fd,stroke:#1976d2,stroke-width:1px;
    classDef db fill:#e8f5e9,stroke:#388e3c,stroke-width:1px;
    classDef config fill:#fff9c4,stroke:#fbc02d,stroke-width:1px;
    classDef docs fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px;
    classDef configs fill:#eeeeee,stroke:#757575,stroke-width:1px;
```
