How madh93/karakeepbot works
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