ARCHITECTURE_OVERVIEW.md

TGist Architecture Overview

Goal

TGist ingests posts from selected Telegram channels, creates one daily digest with OpenAI, and sends it to a configured Telegram target chat.

High-Level Components

1) API Layer (controller)

• Admin endpoints for:
  • channel management,
  • TDLib auth flow,
  • manual ingestion/run/summary triggers.

2) Application Services (service)

• ChannelService: manage channel config.
• IngestionService: fetch and persist daily channel messages.
• DigestComposerService: build prompt + request OpenAI + persist digest.
• DigestDeliveryService: send digest via Telegram and mark delivery.

3) Integration Adapters (client / service.telegram)

• TDLib adapter:
  • native client lifecycle,
  • auth state handling,
  • chat/message operations.
• OpenAI adapter:
  • API call abstraction for summary generation.

4) Persistence (model, repository)

• JPA models for channels/messages/runs/summaries.
• Repository layer for read/write and idempotency queries.
• Flyway migrations as schema source of truth.

5) Scheduling (scheduler)

• Periodic ingestion job.
• Daily digest job.
• Overlap/lock protection to avoid concurrent runs.

Runtime Flow

1. Scheduler (or manual endpoint) starts ingestion.
2. TDLib fetches channel posts for configured window.
3. Messages are normalized + deduplicated and saved.
4. Daily digest run aggregates previous local day messages.
5. OpenAI generates final digest text.
6. Digest is saved and sent to configured target chat.
7. Run status/metrics stored in daily_runs and run_items.

Data Flow

• Input: Telegram channel posts (via TDLib).
• Process: Store raw posts -> aggregate/filter -> summarize via OpenAI.
• Output: Telegram digest message + persisted digest history.

Operational Principles

• Secrets from environment variables only.
• Idempotent ingestion and delivery.
• Fail-fast config validation on startup.
• Structured logs with sensitive value redaction.