Telegraph

Every Telegram bot project eventually rebuilds the same layer: receive a webhook, work out which flow it belongs to, evaluate some conditions, and perform actions without dropping or double-running anything. Telegraph is that layer as a product — a visual flow builder on top of an orchestrator that treats delivery guarantees as the actual feature.

What it does

• Visual flow builder for Telegram automations — drag triggers, conditions, and actions onto a canvas and wire them together
• Trigger, condition, and action-driven workflow execution
• BullMQ-backed action processing, so async work is queued and retryable rather than fire-and-forget
• Event deduplication and action idempotency for safe replays
• Encrypted bot-token storage with application-level security
• Billing and plan-limit enforcement enforced during orchestration, not just in the UI
• A node catalog spanning messaging, media groups, moderation, and payments — including Telegram invoices, Stars, and Crypto Bot

How it works

It’s a monorepo with a deliberate split. apps/web is the Next.js dashboard, API routes, webhook entrypoint, and builder UI. apps/worker is a BullMQ consumer that executes queued actions. The interesting decision is packages/shared: the orchestrator, Telegram client, validation, and queue contracts all live there, so the web app and the worker run the same domain logic instead of two implementations that drift the first time a node type changes.

Two problems drove most of the design. Telegram redelivers webhooks, so every incoming event is deduplicated and every action is idempotent — a replay has to be a no-op, not a second message to a user. And plan limits have to be checked inside orchestration rather than at the edge, because a flow can fan out into many queued actions long after the request that triggered it has returned.

Postgres via Prisma holds flows and run history, Redis backs the queue, Clerk handles auth, Creem handles billing, S3 stores media, and Vitest covers the orchestrator’s unit and integration paths.

Notes

Run history turned out to matter more than the builder. A visual editor makes a flow easy to write; being able to see exactly which node an execution died on is what makes it possible to fix.