# kukiman010/tg_gpt architecture

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

- Interactive diagram: https://gitdiagram.com/kukiman010/tg_gpt
- Repository: https://github.com/kukiman010/tg_gpt

## Overview

#### Purpose and execution surface
This is a Python Telegram AI-assistant bot. It accepts user text/media, routes requests to selectable LLM providers, supports speech and localization, and manages subscription/payment state. The likely application bootstrap is `main.py`, with setup centralized in `configure.py` and cross-component events in `signals.py`.

#### Telegram interaction and user state
The control layer represents bot-facing domain state: user identity, active environment/model settings, subscription data, payment records, and media context. These objects form the boundary between Telegram handlers and persistence/provider calls.
Paths: `Control/user.py`, `Control/environment.py`, `Control/context_model.py`, `Control/user_media.py`.

#### Conversation/model orchestration
`main.py` coordinates incoming commands/messages with user configuration and model invocation. `data_models.py` defines shared data structures, while `signals.py` likely decouples state changes or asynchronous workflow notifications. Model-specific modules are isolated behind provider adapters rather than embedded in bot handling.
Paths: `main.py`, `data_models.py`, `signals.py`.

#### Multi-provider AI gateway
The `Gpt_models` package is the external-model boundary. Separate adapters cover OpenAI/GPT, Claude, Google, YandexGPT, Sber GigaChat, DeepSeek, xAI, and MetaGPT. The runtime selects an adapter based on user/environment settings, sends prompts and context, and returns provider responses to the Telegram interaction layer.
Paths: `Gpt_models/gpt_api.py`, `Gpt_models/claude_api.py`, `Gpt_models/yandexgpt.py`, `Gpt_models/sbergpt.py`.

#### Persistence and database boundary
PostgreSQL is the intended persistent store; README requires UTF-8 setup and the repository includes a schema. Database access is separated into connection/core and API-facing layers. Persistent concerns include user profiles, environment/model choices, subscriptions, and payment information.
Paths: `database.py`, `databaseapi.py`, `tools/tg_base.sql`, `Control/subscription_data.py`.

#### Billing and entitlement flow
Payments are abstracted by a base provider contract and coordinated by a payment manager. Provider implementations include YooKassa and Crypto Pay. A successful payment should update payment/subscription domain state through the database boundary, enabling or extending access controls for AI services.
Paths: `payments/base_pay_system.py`, `payments/payment_manager.py`, `payments/yookassa_api.py`, `payments/crypto_pay_api.py`.

#### Supporting content services and deployment
Speech processing and file handling sit alongside the primary text flow, likely converting or processing user audio/uploads before response generation. Localization is gettext-style catalog based and translated through a dedicated module. The service is containerized with Docker Compose; deployment requires Python 3.8–3.10, PostgreSQL dependencies, and provider credentials/certificates for Yandex and Sber integrations.
Paths: `speech.py`, `file_worker.py`, `translator.py`, `locale/LC_MESSAGES`, `Dockerfile`, `docker-compose.yml`.

Main entry points: [`main.py`](https://github.com/kukiman010/tg_gpt/blob/master/main.py) (Telegram bot coordinator), [`databaseapi.py`](https://github.com/kukiman010/tg_gpt/blob/master/databaseapi.py) (Persistence API), [`payments/payment_manager.py`](https://github.com/kukiman010/tg_gpt/blob/master/payments/payment_manager.py) (Payment manager), [`payments/base_pay_system.py`](https://github.com/kukiman010/tg_gpt/blob/master/payments/base_pay_system.py) (Payment provider contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Bot runtime"]
  node_main["Telegram bot coordinator<br/>Python entrypoint<br/>[main.py]"]
  node_configure["Application setup<br/>configuration bootstrap<br/>[configure.py]"]
  node_signals["Event signals<br/>event bus<br/>[signals.py]"]
  node_models["Shared data models<br/>data contracts<br/>[data_models.py]"]
end

subgraph group_domain["Domain and persistence"]
  node_user["User identity<br/>domain model<br/>[user.py]"]
  node_environment["Active model settings<br/>domain model<br/>[environment.py]"]
  node_context["Conversation context<br/>domain model<br/>[context_model.py]"]
  node_media["User media context<br/>domain model<br/>[user_media.py]"]
  node_subscription["Subscription state<br/>domain model"]
  node_dbapi["Persistence API<br/>repository layer<br/>[databaseapi.py]"]
  node_database[("PostgreSQL connection<br/>database access<br/>[database.py]")]
  node_schema["Database schema<br/>SQL schema<br/>[tg_base.sql]"]
end

subgraph group_ai["AI services"]
  node_gateway{{"LLM provider gateway<br/>provider adapters<br/>[gpt_api.py]"}}
end

subgraph group_billing["Billing"]
  node_paymentmanager["Payment manager<br/>billing orchestrator<br/>[payment_manager.py]"]
  node_paymentcontract["Payment provider contract<br/>billing interface<br/>[base_pay_system.py]"]
  node_yookassa["YooKassa adapter<br/>payment provider<br/>[yookassa_api.py]"]
  node_cryptopay["Crypto Pay adapter<br/>payment provider<br/>[crypto_pay_api.py]"]
end

subgraph group_support["Supporting services"]
  node_speech["Speech processing<br/>media service<br/>[speech.py]"]
  node_files["File worker<br/>media service<br/>[file_worker.py]"]
  node_translator["Localization<br/>translation service<br/>[translator.py]"]
  node_deployment["Container deployment<br/>Docker Compose<br/>[docker-compose.yml]"]
end

node_configure -->|"initializes"| node_main
node_main -->|"loads user"| node_user
node_main -->|"reads selection"| node_environment
node_main -->|"uses context"| node_context
node_main -->|"accepts media"| node_media
node_main -->|"sends prompts"| node_gateway
node_gateway -->|"uses provider choice"| node_environment
node_main -->|"processes audio"| node_speech
node_main -->|"processes uploads"| node_files
node_main -->|"localizes replies"| node_translator
node_main -.->|"emits events"| node_signals
node_main -->|"uses contracts"| node_models
node_user -->|"persists through"| node_dbapi
node_environment -->|"persists through"| node_dbapi
node_context -->|"persists through"| node_dbapi
node_media -->|"persists through"| node_dbapi
node_subscription -->|"persists through"| node_dbapi
node_dbapi -->|"queries"| node_database
node_schema -.->|"defines"| node_database
node_main -->|"starts payment"| node_paymentmanager
node_paymentmanager -->|"uses"| node_paymentcontract
node_paymentcontract -.->|"implemented by"| node_yookassa
node_paymentcontract -.->|"implemented by"| node_cryptopay
node_paymentmanager -->|"updates entitlement"| node_subscription
node_deployment -.->|"runs"| node_main

click node_main "https://github.com/kukiman010/tg_gpt/blob/master/main.py"
click node_configure "https://github.com/kukiman010/tg_gpt/blob/master/configure.py"
click node_signals "https://github.com/kukiman010/tg_gpt/blob/master/signals.py"
click node_models "https://github.com/kukiman010/tg_gpt/blob/master/data_models.py"
click node_user "https://github.com/kukiman010/tg_gpt/blob/master/Control/user.py"
click node_environment "https://github.com/kukiman010/tg_gpt/blob/master/Control/environment.py"
click node_context "https://github.com/kukiman010/tg_gpt/blob/master/Control/context_model.py"
click node_media "https://github.com/kukiman010/tg_gpt/blob/master/Control/user_media.py"
click node_subscription "https://github.com/kukiman010/tg_gpt/blob/master/Control/subscription_data.py"
click node_dbapi "https://github.com/kukiman010/tg_gpt/blob/master/databaseapi.py"
click node_database "https://github.com/kukiman010/tg_gpt/blob/master/database.py"
click node_schema "https://github.com/kukiman010/tg_gpt/blob/master/tools/tg_base.sql"
click node_gateway "https://github.com/kukiman010/tg_gpt/blob/master/Gpt_models/gpt_api.py"
click node_speech "https://github.com/kukiman010/tg_gpt/blob/master/speech.py"
click node_files "https://github.com/kukiman010/tg_gpt/blob/master/file_worker.py"
click node_translator "https://github.com/kukiman010/tg_gpt/blob/master/translator.py"
click node_paymentmanager "https://github.com/kukiman010/tg_gpt/blob/master/payments/payment_manager.py"
click node_paymentcontract "https://github.com/kukiman010/tg_gpt/blob/master/payments/base_pay_system.py"
click node_yookassa "https://github.com/kukiman010/tg_gpt/blob/master/payments/yookassa_api.py"
click node_cryptopay "https://github.com/kukiman010/tg_gpt/blob/master/payments/crypto_pay_api.py"
click node_deployment "https://github.com/kukiman010/tg_gpt/blob/master/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_configure,node_signals,node_models toneBlue
class node_user,node_environment,node_context,node_media,node_subscription,node_dbapi,node_database,node_schema toneAmber
class node_gateway toneMint
class node_paymentmanager,node_paymentcontract,node_yookassa,node_cryptopay toneRose
class node_speech,node_files,node_translator,node_deployment toneIndigo
```

## Components

### Bot runtime

- [Telegram bot coordinator](https://github.com/kukiman010/tg_gpt/blob/master/main.py): Python entrypoint · Routes commands, messages, and responses. · `main.py`
- [Application setup](https://github.com/kukiman010/tg_gpt/blob/master/configure.py): configuration bootstrap · `configure.py`
- [Event signals](https://github.com/kukiman010/tg_gpt/blob/master/signals.py): event bus · Decouples cross-component state and workflow events. · `signals.py`
- [Shared data models](https://github.com/kukiman010/tg_gpt/blob/master/data_models.py): data contracts · `data_models.py`

### Domain and persistence

- [User identity](https://github.com/kukiman010/tg_gpt/blob/master/Control/user.py): domain model · `Control/user.py`
- [Active model settings](https://github.com/kukiman010/tg_gpt/blob/master/Control/environment.py): domain model · Stores user environment and provider selection. · `Control/environment.py`
- [Conversation context](https://github.com/kukiman010/tg_gpt/blob/master/Control/context_model.py): domain model · `Control/context_model.py`
- [User media context](https://github.com/kukiman010/tg_gpt/blob/master/Control/user_media.py): domain model · `Control/user_media.py`
- [Subscription state](https://github.com/kukiman010/tg_gpt/blob/master/Control/subscription_data.py): domain model · `Control/subscription_data.py`
- [Persistence API](https://github.com/kukiman010/tg_gpt/blob/master/databaseapi.py): repository layer · Persists users, settings, subscriptions, and payments. · `databaseapi.py`
- [PostgreSQL connection](https://github.com/kukiman010/tg_gpt/blob/master/database.py): database access · `database.py`
- [Database schema](https://github.com/kukiman010/tg_gpt/blob/master/tools/tg_base.sql): SQL schema · `tools/tg_base.sql`

### AI services

- [LLM provider gateway](https://github.com/kukiman010/tg_gpt/blob/master/Gpt_models/gpt_api.py): provider adapters · Selects and invokes the configured external model. · `Gpt_models/gpt_api.py`

### Billing

- [Payment manager](https://github.com/kukiman010/tg_gpt/blob/master/payments/payment_manager.py): billing orchestrator · Coordinates payment providers and entitlement updates. · `payments/payment_manager.py`
- [Payment provider contract](https://github.com/kukiman010/tg_gpt/blob/master/payments/base_pay_system.py): billing interface · `payments/base_pay_system.py`
- [YooKassa adapter](https://github.com/kukiman010/tg_gpt/blob/master/payments/yookassa_api.py): payment provider · `payments/yookassa_api.py`
- [Crypto Pay adapter](https://github.com/kukiman010/tg_gpt/blob/master/payments/crypto_pay_api.py): payment provider · `payments/crypto_pay_api.py`

### Supporting services

- [Speech processing](https://github.com/kukiman010/tg_gpt/blob/master/speech.py): media service · `speech.py`
- [File worker](https://github.com/kukiman010/tg_gpt/blob/master/file_worker.py): media service · `file_worker.py`
- [Localization](https://github.com/kukiman010/tg_gpt/blob/master/translator.py): translation service · `translator.py`
- [Container deployment](https://github.com/kukiman010/tg_gpt/blob/master/docker-compose.yml): Docker Compose · Runs the bot with PostgreSQL dependencies. · `docker-compose.yml`

## Connections

- Application setup → Telegram bot coordinator: initializes
- Telegram bot coordinator → User identity: loads user
- Telegram bot coordinator → Active model settings: reads selection
- Telegram bot coordinator → Conversation context: uses context
- Telegram bot coordinator → User media context: accepts media
- Telegram bot coordinator → LLM provider gateway: sends prompts
- LLM provider gateway → Active model settings: uses provider choice
- Telegram bot coordinator → Speech processing: processes audio
- Telegram bot coordinator → File worker: processes uploads
- Telegram bot coordinator → Localization: localizes replies
- Telegram bot coordinator → Event signals: emits events
- Telegram bot coordinator → Shared data models: uses contracts
- User identity → Persistence API: persists through
- Active model settings → Persistence API: persists through
- Conversation context → Persistence API: persists through
- User media context → Persistence API: persists through
- Subscription state → Persistence API: persists through
- Persistence API → PostgreSQL connection: queries
- Database schema → PostgreSQL connection: defines
- Telegram bot coordinator → Payment manager: starts payment
- Payment manager → Payment provider contract: uses
- Payment provider contract → YooKassa adapter: implemented by
- Payment provider contract → Crypto Pay adapter: implemented by
- Payment manager → Subscription state: updates entitlement
- Container deployment → Telegram bot coordinator: runs