# Telegram pipeline

How a Telegram post becomes a mood: ingestion, HD images, and the archive mirror.

This document describes the private Telegram ingestion pipeline for mood posts, HD images, and email notifications.

## Scope

The Telegram pipeline affects:

- `POST https://api.buxx.me/webhooks/telegram`
- `https://buxx.me/api/v2/images/*`
- immediate email notify dispatch
- public mood pages that still consume Telegram content during this migration wave

## Current Flow

```mermaid
flowchart TD
  A["Telegram channel post"] --> B["Telegram calls https://api.buxx.me/webhooks/telegram"]
  B --> C["Validate X-Telegram-Bot-Api-Secret-Token"]
  C --> D["Resolve postId/imageIndex"]
  D --> E["Fetch Telegram media bytes"]
  E --> F["site-api writes originals and variants to R2"]
  F --> G["Public reads use private image routes"]
  B --> H["site-api enqueues notify dispatch job"]
  H --> I["Queue consumer calls /v2/notify/dispatch"]
  I --> J["Resend sends immediate notify emails"]
```

## Responsibility Split

### `site-api`

Responsibilities:

- validate Telegram webhook secrets
- parse `channel_post`
- resolve media-group image indexing
- ingest mood images into R2
- enqueue durable immediate notify dispatch jobs
- dispatch notification email through `/v2/notify/dispatch`

### Public `site`

Responsibilities:

- render mood feed and detail pages
- consume `/api/moods` and `/api/comments` from `site-api`
- use `PUBLIC_HD_IMAGE_URL` for primary image URLs
- preserve `/static/...telegram CDN...` fallback behavior

## Key URLs

Canonical private URLs:

- `https://api.buxx.me/webhooks/telegram`
- `https://buxx.me/api/v2/images/*`
- `https://api.buxx.me/v2/notify/dispatch`

Public compatibility:

- `https://buxx.me/api/*` is directly routed to `site-api`

## Failure Modes

**Webhook not configured.** New posts do not enter private ingest, R2 objects do not update, and immediate notification dispatch does not run.

**Image ingest fails.** Public mood pages can use stored Telegram CDN fallbacks when `site-api` returns them, but email links cannot auto-fallback after delivery.

**Notify queue handoff fails.** The webhook should return a retryable failure so Telegram can redeliver the update.