High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
GentelmeN-CorE (GeNCorE) is a modular Telegram bot framework built with Python. It integrates Large Language Models (LLMs) via Groq, cryptocurrency exchange data via KuCoin, and various external search and generation APIs. The system is designed for high availability, utilizing a persistent PostgreSQL database for user preferences and price alerts, and is optimized for deployment on the Railway platform.
The architecture follows a functional design where a central bot instance dispatches tasks to specific command handlers. These handlers interact with a database layer for persistence and an integrations layer for external API communication. A dedicated background thread monitors cryptocurrency prices to trigger asynchronous user notifications.
Sources: core/bot.py, core/commands.py, railway.json
System Components
The system is divided into several core modules that handle specific responsibilities:
| Component | Responsibility | Relevant Files |
|---|---|---|
| Entry Point | Bootstraps the application by running the core bot logic. | bot.py |
| Core Engine | Initializes API clients (Groq, KuCoin, TeleBot), starts background threads, and manages the polling loop. | core/bot.py |
| Command Handlers | Defines the logic for user interactions, including AI chat, crypto queries, and image generation. | core/commands.py |
| Database Layer | Manages PostgreSQL connections and provides an abstraction for user data and alert storage. | core/database.py |
| Integrations | Houses external API wrappers for Brave Search and Hugging Face. | core/integrations.py |
| Helpers | Provides utility functions for standardized bot responses. | core/helpers.py |
Sources: bot.py:1-6, core/bot.py:12-40, core/commands.py:236-258
Data Flow and Interaction
GeNCorE processes user input through a central dispatcher. Depending on the input type (command, voice, or plain text), it routes the request to specialized handlers.
Request Handling Flow
The following diagram illustrates how a user request moves through the system:
This flow ensures that user preferences (like language or preferred AI model) are applied to every interaction.
Sources: core/bot.py:42-45, core/commands.py:171-233, core/integrations.py:1-45
Price Monitoring System
The bot maintains a separate execution context for monitoring cryptocurrency price thresholds.
The monitor thread runs as a daemon, ensuring that price checks occur independently of the main message polling loop.
Sources: core/bot.py:47-91
Database Schema
The system uses PostgreSQL to store persistent data. The schema consists of two primary tables: users for settings and alerts for the price notification system.
Table Definitions
| Table | Field | Type | Description |
|---|---|---|---|
| users | user_id | BIGINT | Primary key (Telegram ID). |
language | TEXT | 'EN' or 'PL' (Default: 'EN'). | |
model_name | TEXT | Selected Groq model. | |
| alerts | symbol | TEXT | Trading pair (e.g., BTC/USDT). |
target_price | NUMERIC | Price threshold to trigger alert. | |
direction | TEXT | 'UP' or 'DOWN'. |
Sources: core/database.py:13-35
External Integrations
GeNCorE leverages several third-party services to extend its functionality beyond basic chat.
API Configuration
Configurations are managed via environment variables, ensuring security and flexibility for deployment.
# Sources: core/integrations.py:6-7, core/bot.py:12-14
BRAVE_KEY = os.environ.get("BRAVE_API_KEY")
HF_TOKEN = os.environ.get("HF_TOKEN")
TOKEN = os.environ.get("TELEGRAM_TOKEN")
GROQ_KEY = os.environ.get("GROQ_KEY")
Supported Services
- Groq Cloud: Used for high-speed LLM inference. Supported models include
llama-3.3-70b-versatile,llama-3.1-8b-instant, andqwen-2.5-32b. - KuCoin: Accessed via the
ccxtlibrary for market data and balance checking. - Brave Search: Provides real-time web context to the AI when users ask about news or current prices.
- Hugging Face: Uses the
FLUX.1-schnellmodel via the Inference API for text-to-image generation.
Sources: core/integrations.py:9-45, core/commands.py:108-115, core/bot.py:27-34
Deployment Architecture
The application is configured for the Railway V2 runtime using Railpack.
| Option | Value |
|---|---|
| Start Command | python bot.py |
| Restart Policy | ON_FAILURE (Max 10 retries) |
| Replicas | 1 |
| Build System | RAILPACK |
Sources: railway.json:1-15
Summary
The GeNCorE High-Level Architecture is a robust, thread-based system that balances real-time user interaction with background monitoring tasks. By offloading heavy processing (AI inference, image generation) to specialized APIs and maintaining state in a PostgreSQL database, the bot achieves a responsive and personalized user experience. The modular structure of core/ allows for easy expansion of features and integrations.