# hu553in/telekilogram architecture

> Architecture diagram of the GitHub repository hu553in/telekilogram, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hu553in/telekilogram
- Repository: https://github.com/hu553in/telekilogram

## Overview

##### Project type and purpose
- Telekilogram is a single-service, backend-only Telegram bot written in Go.
- Purpose: allow users to follow RSS/Atom/JSON feeds and public Telegram channels, store feed subscriptions, schedule and send 24h digests or individual posts back to users via Telegram.

##### File structure
- Top level:
- main.go – application entry point
- justfile, scripts/ – build/deploy automation
- .env.example – environment configuration
- Package directories:
- bot/ – transport layer: Telegram API handlers (commands, callbacks, messages)
- feed/ – core business logic: fetching, parsing RSS/Atom/JSON, integrating with siftrss filters
- scheduler/ – job scheduler for daily digests
- database/ – persistence layer: migrations, DB connection, SQL queries
- models/ – domain models shared across layers
- ratelimiter/ – cross-cutting concern to throttle external API calls or message sends
- markdown/ – helper utilities to format content
- Support files:
- .github/workflows/ci.yml – CI pipeline
- scripts/ – systemd or Docker deployment scripts

##### README
- Describes functionality: follow/unfollow feeds, daily digest, manual digest, settings.
- Technical stack: Go, PostgreSQL (implied by SQL migrations), Telegram Bot API, Just, golangci-lint.
- Workflow: user → Telegram → Bot → Feed fetcher/parser → Database → Scheduler triggers digest → Bot → user.

1. Telegram Bot Interface (bot package)
2. Feed Processor (feed package + markdown helpers)
3. Scheduler (scheduler package)
4. Database (PostgreSQL + database/migrations + queries)
5. Rate Limiter (ratelimiter package)
6. External Services:
– Telegram API
– RSS/Atom/JSON feed endpoints
– Optional siftrss filter service
– User ↔ Telegram API ↔ Bot Interface
– Bot Interface → Database (read/write subscriptions & settings)
– Scheduler → Feed Processor (trigger fetch/parse)
– Feed Processor → Rate Limiter → External feeds
– Feed Processor → siftrss (optional filtering)
– Feed Processor → Database (store/update feed entries)
– Scheduler/On-demand commands → Bot Interface (render & send messages)
c. Architectural patterns & principles:
– Layered architecture:
- Transport layer (bot)
- Application/business layer (feed, scheduler)
- Data access layer (database)
- Cross-cutting (ratelimiter, logging)
– Modular monolith: packages grouped by functionality
– Dependency injection via package globals or passed contexts
d. Technologies & frameworks:
– Go modules (go.mod)
– PostgreSQL with SQL migrations (database/migrations)
– Telegram Bot API (bot.go handlers)
– Job scheduling (custom scheduler in scheduler package)
– Just build tool & shell scripts for deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External entities
    User((User)):::external
    TelegramAPI["Telegram API"]:::external
    ExternalFeeds(("RSS/Atom/JSON Feeds")):::external
    Siftrss["siftrss Filter Service"]:::external

    %% Telekilogram Service Container
    subgraph "Telekilogram Service"
        direction TB
        Main["Application Entry Point (main.go)"]:::internal
        Bot["Bot Interface (bot/)"]:::internal
        Feed["Feed Processor (feed/)"]:::internal
        Scheduler["Scheduler (scheduler/)"]:::internal
        RateLimiter["Rate Limiter (ratelimiter/)"]:::internal
        Markdown["Markdown Formatter (markdown/)"]:::internal
        Database["Database Layer (database/)"]:::db
        Models["Domain Models (models/)"]:::internal

        Main --> Bot
        Bot --> Database
        Scheduler --> Feed
        Feed --> RateLimiter
        RateLimiter --> ExternalFeeds
        Feed --> Siftrss
        Feed --> Database
        Feed --> Markdown
        Scheduler --> Bot
        Bot --> TelegramAPI
    end

    %% DevOps / Support
    subgraph "DevOps & Config"
        direction TB
        Env["Environment Configuration (.env.example)"]:::devops
        CI["CI Pipeline (.github/workflows/ci.yml)"]:::devops
        Justfile["Build Scripts (justfile)"]:::devops
        ScriptsCD["Configure Env Script"]:::devops
        ScriptsDeploy["Deploy Script"]:::devops
    end

    %% User interactions
    User --> TelegramAPI
    TelegramAPI --> Bot

    %% Click Events
    click Bot "https://github.com/hu553in/telekilogram/tree/main/bot/"
    click Feed "https://github.com/hu553in/telekilogram/tree/main/feed/"
    click Markdown "https://github.com/hu553in/telekilogram/blob/main/markdown/helpers.go"
    click Scheduler "https://github.com/hu553in/telekilogram/blob/main/scheduler/scheduler.go"
    click Database "https://github.com/hu553in/telekilogram/tree/main/database/"
    click Models "https://github.com/hu553in/telekilogram/blob/main/models/models.go"
    click Main "https://github.com/hu553in/telekilogram/blob/main/main.go"
    click Env "https://github.com/hu553in/telekilogram/blob/main/.env.example"
    click CI "https://github.com/hu553in/telekilogram/blob/main/.github/workflows/ci.yml"
    click Justfile "https://github.com/hu553in/telekilogram/tree/main/justfile"
    click ScriptsCD "https://github.com/hu553in/telekilogram/blob/main/scripts/configure-env-and-service.sh"
    click ScriptsDeploy "https://github.com/hu553in/telekilogram/blob/main/scripts/deploy.sh"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef db fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef devops fill:#D3D3D3,stroke:#333,stroke-width:1px
```
