We are still grieving Google Reader.
Not the product specifically — the idea behind it. A single chronological surface where everything you subscribed to showed up, in order, without anyone deciding for you what was important. Twitter killed RSS in the 2010s, then algorithms killed Twitter, and the rest of the decade has been a slow rediscovery of the fact that humans actually do read better when nothing is being optimized at them.
A lot of people drifted to Telegram for this reason. Telegram is honest in a way most platforms forgot how to be — chronological order, no ranking, you read what you subscribed to. But there's one thing it doesn't do: a unified feed across channels. Twenty channels means twenty separate inboxes. Every morning you tap through them one by one, and by the tenth you've already forgotten what was in the first.
I built Televizor to fix exactly that. You log in with your Telegram account, pick the channels you follow, and their messages get forwarded into a single destination chat inside your own Telegram. You read it like a feed. Chronological, no algorithm, lives in a regular chat — no separate client, no extension, no new app to install.
- Repo: github.com/s0larpunk/televizor (GPL-3)
- Hosted: televizor.click
What follows is a tour of the architectural decisions, with a section at the end about how this was actually built (it was vibe-coded with Claude Code, and that matters for how you read the code).
Telethon vs Bot API: the decision that shaped everything else
The first instinct when you start building anything that reads Telegram channels is to reach for the Bot API. It's well-documented, the SDKs are good, and Telegram itself recommends it for most automation. The problem is that it's structurally useless for aggregation.
Bots in Telegram exist as a separate identity from users. A bot can only read messages in channels where it has been added as an administrator. To aggregate a public news channel through a bot, you'd need to convince the channel owner to grant your bot admin rights. Nobody is going to do that for a third-party tool. So bot-based aggregators are a dead end for any channel you don't already control.
Telethon takes the other path: it's an MTProto client that authenticates as the user. Same protocol the official Telegram apps use, same protocol Unigram and every other third-party client uses. When you log in via Telethon, you have access to every channel your account is subscribed to — exactly the same access the official client has, because it is functionally the same client.
The tradeoff is real: this is the user API, and it sits in a grey area of the ToS. Telegram doesn't ban third-party MTProto clients (doing so would kill its own third-party ecosystem overnight), but they do flag automation that looks like spam or mass scraping. The mitigations that have kept my instance clean for months:
- 15-second forward delay (configurable, intentionally non-instant)
- Per-source and per-feed rate limiting via Redis
- Event-driven handlers, not polling
- Graceful handling of
SessionRevokedErrorandAuthKeyError
Event-driven vs polling: why this isn't optional
When you read about Telethon for the first time, the natural impulse is to write a loop that asks each channel for new messages every N seconds. This is polling, and it has two structural problems for this use case.
First, latency. With polling at interval N, the average latency for a new message is N/2. At a 30-second poll interval, your median message lands 15 seconds late. For news channels, fine. For trading signals or breaking news, useless.
Second, scaling. Polling N channels for M users is N×M API calls per cycle. Telegram rate-limits you per account, so this hits a wall quickly as you add users. The math doesn't work past a few dozen accounts.
Telethon supports a real event-driven model via events.NewMessage — a persistent connection that receives updates the moment they happen. One connection per user, regardless of channel count. Forward latency is then determined entirely by the deliberate 15-second delay, not by polling interval.
@client.on(events.NewMessage())
async def handler(event):
normalized_id = utils.get_peer_id(event.message.peer_id, add_mark=False)
if normalized_id not in source_to_feeds:
return
valid_feeds = []
for feed in source_to_feeds[normalized_id]:
if feed.filters and not check_filters(event.message, feed.filters):
continue
if not check_rate_limit(user_id, feed.id, feed.filters):
continue
valid_feeds.append(feed)
for dest_id, feeds in group_by_destination(valid_feeds):
asyncio.create_task(
forward_message(client, source_id, dest_id, event.message.id)
)
The source_to_feeds dict is the in-memory routing table. It maps a source channel ID to all feeds that have subscribed to it. Updated via PostgreSQL LISTEN/NOTIFY so config changes propagate instantly without restart.
Albums: the bug that took a week to notice
Telegram delivers albums (grouped photos or videos in a single post) as N separate messages sharing a grouped_id. If you forward each message independently, the album falls apart at the destination — they arrive as unrelated standalone media, no caption.
The fix is a 2-second debounce buffer keyed on (source_id, grouped_id). Every new part of the album resets the timer. After 2 seconds of quiet, flush the whole batch via forward_messages(messages=[ids]), and the destination reconstructs the album as a single grouped post.
if grouped_id:
key = (source_channel_id, grouped_id)
if key not in pending_albums:
pending_albums[key] = {
'message_ids': set(),
'feeds': valid_feeds,
'timer': None,
'source_peer': await event.get_input_chat()
}
pending_albums[key]['message_ids'].add(event.message.id)
if pending_albums[key]['timer']:
pending_albums[key]['timer'].cancel()
pending_albums[key]['timer'] = asyncio.create_task(
wait_and_flush(key, flush_album)
)
In production, album parts arrive within 500ms–1.5s. Two seconds is conservative but I've never seen a split album.
Referral concurrency
The referral flow updates two rows — referrer and referred — and grants both a week of Premium. Done naively, two concurrent referrals using the same code can double-count.
Fix: SELECT FOR UPDATE with a deterministic lock order (always lock the user row first, then the referrer). This is the standard way to avoid ABBA deadlocks where two transactions lock the same rows in opposite order and wait for each other forever.
The increment is done at the SQL level — User.referral_count = User.referral_count + 1 — not as a read-modify-write through the ORM. ORM caches read stale values during concurrent transactions, and Python-side arithmetic silently loses updates.
Rate limiting via Redis: tumbling windows
All anti-flood logic lives in Redis. For each user and action type, two keys: an hourly counter and a daily counter. Keys auto-expire via TTL, so no cleanup job is needed.
The "sliding" window is implemented by dividing the unix timestamp by the window length: now // 3600 is the current hour as an integer, now // 86400 is the current day. When the hour rolls over, the old key stops being incremented and dies via TTL. Technically a tumbling window, not a true sliding one, but close enough for rate-limiting at these granularities.
Threat model — the unredacted version
Session strings are functionally equivalent to Telegram auth tokens. This is the most sensitive thing in the architecture, and I describe it directly rather than burying it in fine print.
Stored in the DB: phone number, Telegram ID, Telethon session string, feed configs, subscription tier and expiry. Not stored: message content, chat history, contacts, media, usage analytics.
If the database leaks, an attacker gets session strings and can connect to Telegram as the affected users. Mitigation: any user can revoke all sessions from Telegram settings instantly, which deactivates the string. Televizor doesn't request the 2FA password, so an attacker with a session string alone cannot change the password or delete the account.
Session strings are encrypted at rest using Fernet (AES-128-CBC + HMAC-SHA256). Encryption is gated on SESSION_ENCRYPTION_KEY in the environment — if the key is set, ciphertext goes to the DB; if not, plaintext (kept for backwards compatibility with legacy rows). For self-hosters: generate a key, drop it in .env, all new sessions are encrypted.
If the threat model is still uncomfortable, self-host. The session never leaves your machine.
How this was built: Claude Code agents
I'm going to be honest about this section because it's relevant to how you should read the code.
I didn't start with an architecture document and decompose tasks into sprints. I opened Claude Code, described the problem, looked at what came back, fixed it, iterated. Most of the codebase was written that way.
Different parts of the project benefited from different kinds of agent interaction. Backend logic was a conversation around concrete problems — "here's Telethon, here's a list of channels, I need event-driven forwarding with filters." The agent proposed structures, I asked questions about concurrency or rate-limiting edge cases, we iterated. Architectural decisions like SELECT FOR UPDATE for the referral flow or the album debounce came out of these conversations — not because I knew the answer in advance, but because the agent surfaced the failure modes of the naive solution.
The Next.js frontend with i18n and RTL Farsi support was a different kind of work. There the agent functioned more like a pair programmer fluent in the ecosystem. The four-language localization with proper RTL would have taken me weeks to build manually.
Where agents are bad: holding context across multi-day sessions, noticing conflicts between modules built in separate sessions, generating tests for code they don't fully model. Refactoring across separate-session output to enforce consistency is manual work. Tests are still a debt — writing tests for code you didn't fully internalize turns out to be harder than I expected.
I open-sourced this from the first commit specifically because it was vibe-coded. When you're building with agents, external review becomes more important, not less. The fewer decisions that pass through your head as a complete model, the more you need a second pair of eyes.
Self-host
git clone https://github.com/s0larpunk/televizor
cd televizor
cp .env.example .env # TELEGRAM_API_ID / TELEGRAM_API_HASH from my.telegram.org
docker compose up -d
Four containers: frontend, backend, postgres, redis. Idle ~180MB RAM, active ~350MB. Set SESSION_ENCRYPTION_KEY in .env for at-rest encryption (generate with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"). Reverse proxy with TLS for production. Back up postgres_data — losing it means every user has to log in again.
What's next
-
Worker sharding — single process today, fine for hundreds of users. Bottleneck is per-account
FloodWait, not CPU. Becomes relevant past 1000+ active users. - Cross-feed dedup — if two feeds share a source channel, the same message is forwarded twice. Fixable with a fingerprint table, but adds a write per delivery to fix a problem nobody's reported. Deferred.
- Test coverage — thin, honest debt of vibe-coding. The hardest one to retrofit because writing tests for code you don't fully model is harder than it sounds.
PRs welcome, especially on tests, sharding, and the dedup problem.
