Durable Objects Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Durable Objects Architecture provides stateful, serialized processing for chat statistics, message aggregation, and content analysis. This system ensures data integrity and consistency by utilizing Cloudflare Durable Objects to handle concurrent requests and maintain state across different worker invocations.
The architecture primarily supports three areas: idempotent counter management, parallelized message fetching for summaries, and stateful criminal/profanity analysis. By using the blockConcurrencyWhile method, Durable Objects serialize operations to prevent race conditions during heavy traffic.
Core Durable Object Components
CountersDO
CountersDO manages chat-level and user-level statistics. It tracks message counts, word counts, media metrics, and violation stats (profanity and criminal code). It implements a day-local monotonic sequence allocation to ensure idempotency for retried Telegram updates.
Sources: [src/durable-objects/counters-do.ts:109-115](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/durable-objects/counters-do.ts#L109-L115), [src/durable-objects/counters-do.ts:258-270](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/durable-objects/counters-do.ts#L258-L270)
Key Storage Prefixes in CountersDO
| Prefix | Description |
|---|---|
stats | Legacy user-day activity counts. |
stats_v2 | Optimized chat-day-user activity counts. |
word_stats_v2 | Total word counts per user per day. |
seq | Day-local monotonic sequence watermarks. |
integrity | D1 write integrity and poisoning states. |
Sources: [src/durable-objects/counters-do.ts:23-45](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/durable-objects/counters-do.ts#L23-L45)
CriminalCodeAnalyzerDO
This component handles the stateful analysis of chat messages against legal regulations. It leverages a caching mechanism in KV and D1 to store analysis results, reducing redundant AI provider calls. It aggregates user violation history over specified periods (today, week, month).
Sources: [tests/integration/criminal-code-integration.test.ts:85-115](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/tests/integration/criminal-code-integration.test.ts#L85-L115)
DayBlockManagerDO
The DayBlockManagerDO manages the lifecycle of raw message data stored in blocks. Its primary responsibility is the cleanup of historical data older than the configured retention period (default 7 days).
Sources: [src/features/stats/stats.ts:1124-1135](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/features/stats/stats.ts#L1124-L1135)
Processing Logic and Data Flow
Increment Flow and Idempotency
When a message arrives, the bot calls CountersDO.incrementCounters. The DO allocates a sequence number and checks the msgseq key to prevent double-counting if the same messageId is processed again.
The integrity fence arms a D1 attempt before writing to KV. If the D1 write fails, the DO marks the state as "poisoned" to signal that aggregate data is no longer exact.
Sources: [src/durable-objects/counters-do.ts:316-350](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/durable-objects/counters-do.ts#L316-L350), [src/durable-objects/counters-do.ts:404-415](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/durable-objects/counters-do.ts#L404-L415)
Optimized Summary Flow
The Optimized Summary System uses Durable Objects (MessageFetcherDO and MessageAggregatorDO) to improve performance for large chat histories.
- Parallel Fetching: Uses DOs to fetch messages concurrently in batches.
- Hierarchical Processing: The
HierarchicalProcessorchunks messages and generates intermediate per-user summaries. - Aggregation: A DO aggregates these summaries before the final AI generation stage.
Sources: [README.md:47-55](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/README.md#L47-L55), [src/features/summary/optimization/hierarchical-processor.ts:34-60](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/features/summary/optimization/hierarchical-processor.ts#L34-L60)
Data Integrity and Recovery
Pipeline Integrity State
The system tracks the progress of asynchronous pipelines (like Profanity and Criminal analysis) using IntegrityState. A stream is considered "clean" only if no D1 write attempts are currently active or failed.
Recovery logic ensures that a stale active attempt (from a worker crash) is converted into a sticky "ambiguous" poison state rather than silently ignored.
Sources: [src/durable-objects/counters-do.ts:173-188](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/durable-objects/counters-do.ts#L173-L188), [src/durable-objects/counters-do.ts:219-225](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/durable-objects/counters-do.ts#L219-L225)
API Endpoints for CountersDO
CountersDO exposes internal POST endpoints for interaction with the main Worker:
/inc: Standard activity and media metric increments./profanity: Updates profanity word counts and user stats./criminal: Updates criminal violation stats and severity./ack: Acknowledges progress for asynchronous analysis tasks./pipeline-snapshot: Returns the current integrity and sequence state for a specific day./batch: Processes multiple increments in a single serialized block.
Sources: [src/durable-objects/counters-do.ts:241-304](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/durable-objects/counters-do.ts#L241-L304)
Summary of Operational significance
Durable Objects act as the source of truth for all real-time metrics. While D1 serves as a long-term analytical store, Durable Objects provide the low-latency serialization required to handle Telegram's high-frequency webhook updates without losing data or creating race conditions during concurrent KV writes.
Sources: [README.md:12-18](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/README.md#L12-L18), [AGENTS.md:10-15](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/AGENTS.md#L10-L15)