Profanity Tracking System
Relevant source files
The following files were used as context for generating this wiki page:
The Profanity Tracking System identifies, analyzes, and records the use of obscene language within Telegram chat messages. It employs a hybrid detection strategy combining local regular expression analysis with Cloudflare or OpenAI-powered AI classification to maintain accuracy while managing API costs and performance.
The system tracks metrics at three levels: individual user counts, specific word frequencies, and aggregate chat statistics. These metrics allow the bot to generate daily/weekly/monthly charts and leaderboards of profanity usage.
System Architecture
The architecture consists of a detection pipeline, a result normalization layer, and a durable storage mechanism.
The diagram shows the logic flow from message reception to persistent storage in KV via the hybrid detection pipeline.
Sources: src/api/update.ts:208-270, src/features/profanity/profanity.ts:147-160
Detection Pipeline
The detection process triggers within the recordMessage function. If ENABLE_PROFANITY_ANALYSIS is active, the bot schedules an asynchronous analysis task to avoid blocking the primary message processing loop.
Sources: src/api/update.ts:249-260
- Local Detection: The system first uses
local-detector.tsto scan text for known profanity tokens using regular expressions. This provides immediate results without external API calls.
Sources: src/features/profanity/local-detector.ts:1-20 - AI Analysis: If the
ProfanityAnalyzerdetermines a deeper check is required, it calls anAIProvider. The system utilizes a specificPROFANITY_SYSTEM_PROMPTto instruct the AI to identify only Russian obscene language, ignoring general rudeness or other languages.
Sources: src/core/providers/ai-provider.ts:125-155 - Circuit Breaker: To prevent system degradation during AI provider outages, the
ProfanityAnalyzerimplements a circuit breaker that opens after 5 failures within a short period.
Sources: src/features/profanity/profanity.ts:107-145
Data Model and Storage
Profanity data is stored in Cloudflare KV with specific key patterns to allow efficient prefix-based listing and aggregation.
KV Key Patterns
| Data Type | Key Pattern | Description |
|---|---|---|
| User Totals | profanity:{chatId}:{userId}:{day} | Total profanity count per user per day. |
| Word Stats | profanity_words:{chatId}:{word}:{day} | Frequency of a specific word per chat per day. |
| User-Word Mapping | profanity_word_users:{chatId}:{word}:{day}:{userId} | Tracks which user used which word and how often. |
| Analysis Cache | profanity_cache:{textHash} | Stores AI analysis results to prevent redundant API calls. |
Sources: src/features/stats/stats.ts:252-270, src/features/profanity/profanity.ts:35-40, tests/profanity-counter.test.ts:120-140
Caching Mechanism
The ProfanityAnalyzer caches results in KV with a configurable TTL (defaulting to 4 hours). It also maintains an in-memory LRU cache to speed up repeated lookups within the same Worker execution context.
Sources: src/features/profanity/profanity.ts:220-300
User Commands and Reporting
The stats.ts module provides functions to query and visualize the collected profanity data.
Available Commands
| Command | Function | Description |
|---|---|---|
/profanity_top | profanityTopUsers | Displays the top N users by profanity count for a period. |
/profanity_words | profanityWordsStats | Lists the most frequently used obscene words. |
/my_profanity | myProfanityStats | Shows personal statistics for the calling user. |
/profanity_chart_week | profanityChart | Generates a bar chart of daily counts for the week. |
/profanity_rate | profanityRateChart | Shows the percentage of profanity relative to total words. |
Sources: src/api/update.ts:380-420, src/features/stats/stats.ts:600-650
Visualizations
The system generates ASCII graphs for quick text-based reporting and uses QuickChart.io to generate image-based bar charts for profanityChart and profanityRateChart.
Sequence showing how the bot aggregates KV data to generate a visual chart via an external API.
Sources: src/features/stats/stats.ts:735-820, tests/profanity-charts.test.ts:80-120
Configuration Parameters
The system behavior is controlled via environment variables defined in wrangler.jsonc.
| Variable | Type | Default | Description |
|---|---|---|---|
ENABLE_PROFANITY_ANALYSIS | Boolean | true | Globally toggles the profanity tracking feature. |
PROFANITY_ANALYSIS_CACHE_TTL | Number | 14400 | TTL in seconds for the analysis cache (4 hours). |
PROFANITY_RATE_MIN_WORDS | Number | 100 | Min words a user must speak to be included in rate stats. |
PROFANITY_SYSTEM_PROMPT | String | (Internal) | The system instructions sent to the AI provider. |
Sources: src/api/update.ts:168-180, src/features/profanity/profanity.ts:98-105, src/features/stats/stats.ts:11
Conclusion
The Profanity Tracking System provides a robust framework for monitoring chat etiquette. By leveraging a multi-tier detection approach and durable Cloudflare primitives, it ensures that even high-traffic chats can maintain detailed linguistic statistics without incurring prohibitive costs or latency.