# mrandrew30/linksgenerator architecture

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

- Interactive diagram: https://gitdiagram.com/mrandrew30/linksgenerator
- Repository: https://github.com/mrandrew30/linksgenerator

## Overview

##### Project type and purpose
- This is a lightweight, full-stack “microservice” style application—a Telegram bot (“LinksGenerator”) written in Python.
- Purpose: accept commands from Telegram users, generate and track short links via external services (Google Sheets as a storage layer, VK API for link generation), and return results to the user.

##### File structure
- Top-level:
- Dockerfile, docker-compose.yml, .env_example − containerization and env-config
- data/ − local data or persistent volume (currently empty)
- links_generator/ − Python package containing business logic
- docs/ − Sphinx documentation
- requirements.txt, setup.py − packaging & dependencies
- Inside links_generator/:
- main.py − entrypoint (initializes bot, dispatches commands)
- handler_commands.py − maps Telegram commands to business actions
- databases/databases.py − abstraction for storage (currently Google Sheets)
- googletables/worktables.py − wrapper around Google Sheets API
- vk_api/vk_api.py − wrapper around VK short-link API

##### README for additional insights
- Lists tech integrations: Telegram Bot API, Google Sheets API, optional Google Drive API, VK API.
- Describes process to obtain credentials.json (Google service account) and VK service access key.
- Shows how to build & run via Docker Compose.

##### Main components & interactions
a. Components
1. “Telegram Bot” container (Docker service)
2. Telegram Bot API (external service/“cloud”)
3. Business Logic Layer
- HandlerCommands
- LinkGenerator core modules
4. Storage Layer
- Google Sheets (via Google Sheets API)
- Optional fallback: local data volume (data/)
5. External Link Service
- VK API (via vk_api module)
6. Environment & Config
- .env (Telegram token, spreadsheet ID, VK key, etc.)
b. Data flows & relationships
- Telegram client → Telegram Bot container (receives updates)
- Bot container → HandlerCommands → Business Logic
- Logic → Storage Layer (read/write via Google Sheets API)
- Logic → VK API (request short-link)
- VK API & Storage responses → Handler → Bot container → Telegram API (respond to user)
c. Architectural patterns & design principles
- Separation of concerns: command handling, business logic, external API wrappers
- Adapter/Wrappers: modules abstract over Google Sheets & VK API
- Configuration via environment variables for portability
- Container-based deployment (Docker + Docker Compose)
d. Technologies & frameworks
- Python 3.x
- python-telegram-bot (or built-in Telegram Bot API)
- google-api-python-client (Google Sheets/Drive)
- vk-api or custom VK API wrapper
- Docker, Docker Compose

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    TelegramAPI["Telegram API"]:::external
    VKService["VK API"]:::external

    %% Bot Container
    subgraph "Telegram Bot Container"
        direction TB
        Main["main.py"]:::internal
        Handler["HandlerCommands"]:::internal
        Logic["Business Logic"]:::internal
        Databases["Storage Abstraction"]:::internal
        GSWrapper["Google Sheets Wrapper"]:::internal
        VKWrapper["VK API Wrapper"]:::internal
    end

    %% Storage
    GS["Google Sheets"]:::storage

    %% Infrastructure
    subgraph "Infrastructure & Deployment"
        direction TB
        Env[".env_example"]:::infra
        DataVol["data/ (Persistent Volume)"]:::infra
        DockerfileNode["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
        Req["requirements.txt"]:::infra
        Setup["setup.py"]:::infra
    end

    %% Legend
    subgraph "Legend"
        direction TB
        A[Internal Module]:::internal
        B[Storage]:::storage
        C[External Service]:::external
        D[Infrastructure]:::infra
    end

    %% Connections
    TelegramAPI -->|"updates (HTTPS)"| Main
    Main --> Handler
    Handler --> Logic
    Logic --> Databases
    Databases --> GSWrapper
    GSWrapper --> GS
    Logic --> VKWrapper
    VKWrapper --> VKService
    GS --> Databases
    VKService --> VKWrapper
    Databases --> Handler
    VKWrapper --> Handler
    Handler --> Main
    Main -->|"response (HTTPS)"| TelegramAPI

    %% Infra connections
    Compose --> DockerfileNode
    Compose --> Env
    Compose --> DataVol
    Compose --> Req
    Compose --> Setup
    DockerfileNode -->|"build image"| Main

    %% Click Events
    click Main "https://github.com/mrandrew30/linksgenerator/blob/main/links_generator/main.py"
    click Handler "https://github.com/mrandrew30/linksgenerator/blob/main/links_generator/handler_commands.py"
    click Databases "https://github.com/mrandrew30/linksgenerator/blob/main/links_generator/databases/databases.py"
    click GSWrapper "https://github.com/mrandrew30/linksgenerator/blob/main/links_generator/googletables/worktables.py"
    click VKWrapper "https://github.com/mrandrew30/linksgenerator/blob/main/links_generator/vk_api/vk_api.py"
    click Env "https://github.com/mrandrew30/linksgenerator/blob/main/.env_example"
    click DockerfileNode "https://github.com/mrandrew30/linksgenerator/tree/main/Dockerfile"
    click Compose "https://github.com/mrandrew30/linksgenerator/blob/main/docker-compose.yml"
    click DataVol "https://github.com/mrandrew30/linksgenerator/tree/main/data/"
    click Req "https://github.com/mrandrew30/linksgenerator/blob/main/requirements.txt"
    click Setup "https://github.com/mrandrew30/linksgenerator/blob/main/setup.py"

    %% Styles
    classDef internal fill:#CFE2F3,stroke:#0366d6,color:#000
    classDef storage fill:#D9F2E6,stroke:#2E7D32,color:#000
    classDef external fill:#FCE5CD,stroke:#E65100,color:#000
    classDef infra fill:#EAD1DC,stroke:#9C27B0,color:#000
```
