Data Flow & State Management

Relevant source files

The following files were used as context for generating this wiki page:

• core/database.py
• core/commands.py
• core/bot.py
• core/integrations.py
• core/helpers.py
• bot.py

Data flow and state management in GentelmeN-CorE (GeNCorE) revolve around a hybrid architecture that combines persistent PostgreSQL storage for user settings and price alerts with volatile in-memory caching for active AI conversation histories. The system acts as a central hub, orchestrating data between the Telegram Bot API, LLM providers (Groq), cryptocurrency exchanges (KuCoin), and external search or generation tools (Brave Search, Hugging Face).

Sources: core/bot.py:10-25, core/commands.py:13-22, core/database.py:4-10

Persistence Layer & Database Schema

The persistent state is managed through a PostgreSQL database. Upon initialization, the system ensures the existence of two primary tables: users for profile management and alerts for asynchronous price monitoring.

Database Tables Summary

Table	Field	Type	Description
users	user_id	BIGINT (PK)	Unique Telegram User ID
	username	TEXT	Telegram username
	language	TEXT	Preferred AI response language (Default: 'EN')
	model_name	TEXT	Selected LLM model (Default: 'llama-3.3-70b-versatile')
	joined_at	TIMESTAMP	Record creation timestamp
alerts	id	SERIAL (PK)	Unique alert identifier
	user_id	BIGINT	ID of the user who set the alert
	symbol	TEXT	Trading pair (e.g., BTC/USDT)
	target_price	NUMERIC	Price threshold to trigger alert
	direction	TEXT	Trigger condition ('UP' or 'DOWN')

Sources: core/database.py:15-35

Schema Relationship

The following Entity-Relationship diagram illustrates the data structures used for persistence:

In-Memory State & Caching

GeNCorE utilizes local Python dictionaries to cache user preferences and maintain conversational context to reduce database latency and manage AI token limits.

Conversational Context

The user_history dictionary in core/commands.py stores a list of message objects (role and content) for each user. This history is capped at a MAX_HISTORY of 40 messages to prevent memory exhaustion and context window overflow.
Sources: core/commands.py:16-17, core/commands.py:228-232

Preference Caching

The core/database.py module maintains user_prefs and user_models dictionaries. When get_user_data(user_id) is called, the system first checks these caches before querying the PostgreSQL database.
Sources: core/database.py:40-60

Command & Logic Flow

The data flow for a standard user interaction follows a specific path from the Telegram gateway through the processing engine to external integrations.

Sequence of an AI Chat Request

This diagram demonstrates how data moves when a user sends a message to the bot:

Asynchronous Data Monitoring

A background thread manages the state of cryptocurrency prices independently of user commands. It periodically queries the database for all active alerts, fetches current market data via the ccxt KuCoin integration, and triggers notifications when conditions are met.

Price Monitor Logic

1. Fetch: Queries alerts table for all rows.
2. Filter: Aggregates unique symbols and fetches tickers from KuCoin.
3. Compare: Iterates through alerts. If direction is 'UP' and curr_price >= target, or 'DOWN' and curr_price <= target, it marks a "hit".
4. Notify & Cleanup: Sends a Telegram message to the user and deletes the alert from the database to prevent duplicate triggers.

Sources: core/bot.py:40-77

Configuration & Environment State

The system state is heavily influenced by environment variables defined at runtime, primarily within core/bot.py and core/commands.py.

Variable	Usage	Source File
DATABASE_URL	Connection string for PostgreSQL	core/bot.py:14
TELEGRAM_TOKEN	Bot authentication	core/bot.py:12
GROQ_KEY	AI Model API access	core/bot.py:13
ADMIN_ID	Restricted command access	core/commands.py:13
OWNER_USER_ID	KuCoin balance access authorization	core/commands.py:91

Sources: core/bot.py:12-14, core/commands.py:13, 91

The architecture ensures that while individual modules handle specific logic (e.g., integrations.py for API calls, commands.py for request handling), the central state remains consistent across the PostgreSQL database and the in-memory cache managed by database.py.