User Activity & Statistics
Relevant source files
The following files were used as context for generating this wiki page:
The User Activity & Statistics system tracks, aggregates, and visualizes engagement metrics within Telegram chats. It collects raw message data to generate insights into user behavior, linguistic patterns (profanity), and compliance with criminal codes. The system uses a multi-tier storage approach involving Cloudflare KV for short-term caching, Durable Objects for atomic counters, and Cloudflare D1 for long-term historical aggregation.
Sources: README.md:3-15, src/features/stats/stats.ts:1-25
Architecture and Data Flow
The statistics engine operates on a dual-write and deferred aggregation model. When a message arrives via webhook, the bot increments real-time counters and records the event for future analysis.
Statistics Processing Pipeline
The diagram shows the flow from message reception to storage and eventual consumption via the dashboard or commands.
Sources: src/features/stats/d1-aggregate-writer.ts:15-35, README.md:7-14
The CountersDO Durable Object ensures atomic increments of user message counts, word counts, and media durations (voice and video notes). These increments are then pushed to D1 via the D1AggregateWriter to maintain permanent daily aggregates.
Sources: src/features/stats/d1-aggregate-writer.ts:70-100
Key Statistic Components
1. General Activity
Activity tracking measures the volume of interaction. It includes message counts, word counts, and media usage (voice messages and video notes).
- Hourly Activity: Buckets messages into 24-hour periods to identify peak engagement times.
- User Activity: Identifies top contributors based on message frequency or total word count.
- Participant Rhythm: Analyzes "talkative" vs. "active" levels across days of the week.
Sources: src/features/stats/stats.ts:150-180, src/api/admin-html.ts:500-550
2. Profanity Analysis
The system identifies and counts profane vocabulary. It tracks both the frequency of specific words and the "profanity rate" (percentage of profane words relative to total words) per user.
Sources: src/features/stats/stats.ts:350-400
3. Criminal Code Violations
Optionally, the bot analyzes messages for potential violations of the Russian Criminal Code (UK RF). It assigns severity levels (1-10) and confidence scores to detected violations.
Sources: tests/models/statistics.test.ts:10-30, src/features/stats/stats.ts:750-800
Data Models
Statistical Structures
| Interface | Purpose | Key Fields |
|---|---|---|
UserStats | Aggregate data for a specific user | totalViolations, averageSeverity, riskLevel, mostCommonViolation |
PeriodStats | Data for a chat over a timeframe | startDate, endDate, uniqueUsers, comparisonWithPreviousPeriod |
Violation | Details of a single detected offense | article, quote, punishment, severity, confidence |
ActivityDateRange | Period definition for queries | startDate, endDate, dayCount, label |
Sources: tests/models/statistics.test.ts:70-150, src/features/stats/stats.ts:13-20
D1 Storage Schema
The d1-aggregate-writer.ts module manages several key tables for persistence:
stats_daily_user: Tracks daily totals for messages, words, and violations per user.stats_daily_hour: Stores message counts per hour for a specific chat.stats_daily_profanity_word: Aggregates the usage of specific profane terms.stats_daily_coverage: Tracks the status of data processing (e.g., 'live' vs 'complete').
Sources: src/features/stats/d1-aggregate-writer.ts:80-160
Bot Commands for Statistics
The bot provides interactive commands to retrieve statistical data directly within Telegram.
| Command | Argument | Description |
|---|---|---|
/top | <n> | Shows the top N active users for the current day. |
/activity_week | - | Generates an ASCII/Image chart of chat activity for the last 7 days. |
/profanity_top | [n] [period] | Lists users with the most profanity usage (today/week/month). |
/criminal_stats | [period] | Returns aggregated stats on criminal code violations. |
/summary | <days> | Generates an AI-powered summary of chat activity. |
Sources: README.md:20-40, src/features/stats/stats.ts:185-210
Reporting and Notifications
The notification-settings.ts module defines how statistics are delivered automatically.
The notification engine allows administrators to enable or disable specific reports and set thresholds for delivery (e.g., only notify if violations > 5).
Sources: src/core/models/notification-settings.ts:85-110, src/features/stats/stats.ts:310-330
Notification Thresholds and Frequency
Administrators can configure the system to send reports at specific intervals: daily, weekly, monthly, or instant (for high-severity criminal violations).
Sources: src/core/models/notification-settings.ts:25-45
Conclusion
The User Activity & Statistics module transforms raw message logs into actionable intelligence. By leveraging a multi-tier storage architecture and AI summarization, it provides both real-time moderation tools and long-term engagement analytics while maintaining a 7-day data retention policy for raw messages to ensure privacy.
Sources: README.md:1-10, src/features/stats/stats.ts:900-920