# madh93/karakeepbot architecture

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

- Interactive diagram: https://gitdiagram.com/madh93/karakeepbot
- Repository: https://github.com/madh93/karakeepbot

## Overview

##### Project type and purpose
- This is a single-service, backend-only Telegram Bot written in Go that listens for Telegram messages (text, URLs, images), validates and processes them, then forwards bookmarks to a Karakeep instance via its REST API. It also optionally generates AI-based tags.

##### File structure
- Top-level:
- `main.go`: application entry point
- `config.default.toml` & `kodata/config.default.toml`: default configuration
- `Taskfile.yml`, Dockerfile, `.devcontainer`, GitHub workflows, goreleaser, ko and svu configs for CI/CD and releases
- `internal/`: core application packages:
- `internal/config/`: loading & merging config from file/env, parsing allowlists, logging setup, Telegram and Karakeep endpoints
- `internal/filevalidator/`: image and URL validation logic
- `internal/fileprocessor/`: transforms incoming attachments (e.g., download/process an image)
- `internal/karakeepbot/`: main bot logic—handling Telegram updates, mapping to bookmark types, calling Karakeep API
- `internal/logging/`: application-wide logging wrapper
- `internal/validation/`: high-level validation of requests (chat-ID allowlist, message content)
- `internal/secret/`: secure handling of tokens
- `internal/version/`: version information
- CI/CD & Deployment: Dockerfile + docker-compose, GitHub Actions, goreleaser for binary releases

##### README for additional insights
- Describes features (text/URL/image bookmarks, AI tags, chat-ID allowlist)
- Deployment options (Docker, binary, from source)
- Configuration via file or environment variables (prefix `KARAKEEPBOT_`)

a. Main components
- Telegram Client (external service)
- Karakeep API (external service)
- Karakeepbot service
- Config loader
- Logging
- Validation layer
- File processor
- File validator
- Bot core (update receiver, command handler)
- Karakeep API client
b. Relationships & interactions
1. Karakeepbot initializes: loads config (file + env), sets up logging, enforces allowlist
2. Connects to Telegram API (long polling or webhook)
3. Receives Update → passes through validation (chat ID, content)
4. Processes attachments via fileprocessor/validator pipelines
5. Calls Karakeep API client to create bookmark (text/URL/image), optionally fetches AI tags
6. Sends confirmation or error back to Telegram
c. Architectural patterns & principles
- Layered architecture (config → validation → processing → external calls)
- Single responsibility per package
- Use of interfaces (e.g., for HTTP clients, file processors) to enable testing
- CI/CD pipelines for build/test/release automation
d. Key technologies & frameworks
- Go modules (go.mod)
- Telegram Bot API (HTTP long polling)
- Karakeep REST API
- TOML config + environment-variable overrides
- Docker & Docker Compose for containerization
- GitHub Actions, goreleaser, ko for releases

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Karakeepbot Service"
        ConfigLoader["Config Loader"]:::gray
        Logger["Logger"]:::gray
        Validation["Validation Layer"]:::blue
        FileProcessor["File Processor"]:::blue
        FileValidator["File Validator"]:::blue
        BotCore["Bot Core"]:::blue
        APIClient["Karakeep API Client"]:::blue
        Version["Version Info"]:::gray
        Secret["Secret Manager"]:::gray
    end

    Main["Application Entry Point (main.go)"]:::gray
    DefaultConfig["Default Config Templates"]:::gray
    TelegramAPI["Telegram API"]:::green
    KarakeepAPI["Karakeep API"]:::green

    Main -->|"init"| ConfigLoader
    Main -->|"init"| Logger
    Main -->|"init"| Secret
    Main -->|"init"| Version
    Main -->|"load defaults"| DefaultConfig

    ConfigLoader -->|"provides config"| BotCore
    ConfigLoader -->|"provides config"| Validation
    ConfigLoader -->|"provides config"| FileProcessor
    ConfigLoader -->|"provides config"| APIClient

    Logger -->|"logs"| BotCore
    Logger -->|"logs"| Validation
    Logger -->|"logs"| FileProcessor
    Logger -->|"logs"| APIClient

    BotCore -->|"polls"| TelegramAPI
    TelegramAPI -->|"Update"| BotCore

    BotCore -->|"Validated Payload"| Validation
    Validation -->|"valid Update"| FileProcessor

    FileProcessor -->|"Processed file"| FileValidator
    FileValidator -->|"Validation result"| FileProcessor

    FileProcessor -->|"Bookmark payload"| APIClient
    APIClient -->|"API request"| KarakeepAPI
    KarakeepAPI -->|"Response"| APIClient

    APIClient -->|"Bookmark response"| BotCore
    BotCore -->|"Confirmation"| TelegramAPI

    click Main "https://github.com/madh93/karakeepbot/blob/main/main.go"
    click ConfigLoader "https://github.com/madh93/karakeepbot/blob/main/internal/config/config.go"
    click Logger "https://github.com/madh93/karakeepbot/blob/main/internal/logging/logging.go"
    click Validation "https://github.com/madh93/karakeepbot/blob/main/internal/validation/validation.go"
    click FileValidator "https://github.com/madh93/karakeepbot/blob/main/internal/filevalidator/image.go"
    click FileProcessor "https://github.com/madh93/karakeepbot/blob/main/internal/fileprocessor/fileprocessor.go"
    click BotCore "https://github.com/madh93/karakeepbot/blob/main/internal/karakeepbot/karakeepbot.go"
    click APIClient "https://github.com/madh93/karakeepbot/blob/main/internal/karakeepbot/karakeep.go"
    click DefaultConfig "https://github.com/madh93/karakeepbot/blob/main/config.default.toml"
    click DefaultConfig "https://github.com/madh93/karakeepbot/blob/main/kodata/config.default.toml"
    click Version "https://github.com/madh93/karakeepbot/blob/main/internal/version/version.go"
    click Secret "https://github.com/madh93/karakeepbot/blob/main/internal/secret/string.go"

    classDef gray fill:#DDDDDD,stroke:#888,stroke-width:1px
    classDef blue fill:#ADD8E6,stroke:#888,stroke-width:1px
    classDef green fill:#90EE90,stroke:#888,stroke-width:1px

    linkStyle 0,1,2,3,4,13,23 stroke:#f66,stroke-width:2px
    linkStyle 5,6,7,8,9,10,11,12,14,15,16,17,18,19,20,21,22 stroke:#06f,stroke-width:2px
```
