# assimon/captcha-bot architecture

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

- Interactive diagram: https://gitdiagram.com/assimon/captcha-bot
- Repository: https://github.com/assimon/captcha-bot

## Overview

##### Project Type and Purpose
- This project is a bot application designed to authenticate users joining Telegram groups by challenging them with a captcha. It integrates with Telegram’s API using the Telebot Framework.
- Its purpose is twofold: it provides a deployable verification tool for group administrators and serves as an example for developers learning to interact with Telegram in Go.

##### Analyzing the File Structure
- Key top-level files and directories:
- main.go: The entry point for the application.
- bootstrap: Contains initialization code (bootstrap/bootstrap.go) to set up the application.
- config: Houses configuration files (e.g., example.config.toml) necessary for bot configuration.
- model: Contains data models (such as advertise.go, base.go, user_captcha_record.go) which likely represent the database schema or business data.
- service: Implements business logic (e.g., advertiseService.go, userCaptchaRecord.go) that supports functionalities like adding, removing and retrieving advertisements.
- telegram: Contains command handling and Telegram-specific logic (command.go, handle.go, root.go, sync.go) that interact with Telegram’s API.
- util: A collection of helper libraries that manage aspects such as captcha generation, configuration management, error handling, logging, ORM integration (using GORM), and sensitive word filtering.
- dict: Provides encrypted dictionaries for sensitive words, with instructions on decrypting these files using openssl.
- Docker-related files (Dockerfile, docker-compose.yml, .goreleaser.yml) indicate containerized deployment and release processes.

##### Components and Their Responsibilities
a. Core Application Entry:
- main.go acts as the starting point. It likely initializes the bootstrap process, which in turn sets up configuration, logging, and dependency injection.
b. Bootstrapping Layer:
- The bootstrap package ensures that the application's foundational services and configuration are loaded before initiating business logic.
c. Configuration Management:
- The config directory and util/config package manage the bot’s settings (e.g., Telegram API keys, database connections).
d. Business Logic and Models:
- The model directory defines the data structures (such as user records and advertisement data).
- The service directory encapsulates the logic for handling verification workflows (like processing captcha responses or managing ad data).
e. Telegram API Integration:
- The telegram package implements command processing (e.g., /ping, /add_ad) and interaction with Telegram’s API.
f. Utility Functions:
- The util directory includes several helper modules:
- Captcha generation (util/captcha)
- ORM handling using GORM (util/orm)
- Custom error definitions (util/error)
- Logging (util/log)
- Sensitive words filtering (util/sensitiveword)
g. Deployment and Containerization:
- Dockerfile and docker-compose.yml enable containerization for consistent deployment across environments.

##### Relationships and Interaction Flow
- The entry point (main.go) triggers the bootstrap process, which sets up configuration and logging.
- The telegram package listens for incoming Telegram commands. Upon receiving a command (such as /ping or /add_ad), it utilizes functions from the service layer to handle business logic.
- The service layer interacts with models for data persistence and uses the util packages (e.g., for ORM and logging) to record events and handle errors.
- For sensitive word checking, the util/sensitiveword module relies on decrypted dictionaries stored in the dict directory.
- Docker configuration files indicate how the bot is deployed (either via pre-built binaries or containerized instance).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project cleanly separates configuration, business logic, Telegram integration, and utilities into different directories.
- Modularity: Each package (bootstrap, service, telegram, etc.) encapsulates a specific aspect of the system, making it maintainable and testable.
- Extensibility: The clear division between command handling and business logic allows new commands or features to be added with minimal interference in other modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Initialization and Configuration Layer
    subgraph "Initialization and Configuration"
        id_main["main.go"]:::entry
        id_bootstrap["bootstrap (bootstrap.go)"]:::boot
        id_main --> id_bootstrap

        subgraph "Configuration"
            id_config["Config Files (example.config.toml)"]:::config
            id_util_config["Util Config (config.go)"]:::config
        end
        id_bootstrap --> id_config
        id_bootstrap --> id_util_config

        subgraph "Utilities"
            id_util_log["Util Log (log.go)"]:::util
            id_util_captcha["Util Captcha (captcha.go)"]:::util
            id_util_orm["Util ORM (gorm.go)"]:::util
            id_util_error["Util Error (error.go)"]:::util
            id_util_sensitive["Util Sensitiveword (sensitiveword.go)"]:::util
        end
        id_bootstrap --> id_util_log
        id_bootstrap --> id_util_captcha
        id_bootstrap --> id_util_orm
        id_bootstrap --> id_util_error
        id_bootstrap --> id_util_sensitive
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        subgraph "Business Models"
            m1["advertise.go"]:::model
            m2["base.go"]:::model
            m3["user_captcha_record.go"]:::model
        end
        subgraph "Service Layer"
            s1["advertiseService.go"]:::service
            s2["userCaptchaRecord.go"]:::service
        end
        s1 -->|"uses"| m1
        s2 -->|"uses"| m3
        s1 -->|"ORM"| id_util_orm
        s1 -->|"error_handling"| id_util_error
        id_util_sensitive -->|"anti-spam"| s1
    end

    %% Telegram Integration Layer
    subgraph "Telegram Integration"
        t1["command.go"]:::telegram
        t2["handle.go"]:::telegram
        t3["root.go"]:::telegram
        t4["sync.go"]:::telegram
        t1 -->|"triggers"| s1
        t2 -->|"triggers"| s1
        t3 -->|"triggers"| s1
        t4 -->|"triggers"| s1
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        subgraph "Sensitive Dictionary"
            d1["enc_dc1.txt"]:::dict
            d2["enc_dc2.txt"]:::dict
        end
        subgraph "Deployment/Containerization"
            dep1["Dockerfile"]:::deployment
            dep2["docker-compose.yml"]:::deployment
            dep3[".goreleaser.yml"]:::deployment
        end
        d1 --> id_util_sensitive
        d2 --> id_util_sensitive
        dep1 -->|"deploys"| id_main
        dep2 -->|"deploys"| id_main
        dep3 -->|"deploys"| id_main
    end

    %% Click Events
    click id_main "https://github.com/assimon/captcha-bot/blob/master/main.go"
    click id_bootstrap "https://github.com/assimon/captcha-bot/blob/master/bootstrap/bootstrap.go"
    click id_config "https://github.com/assimon/captcha-bot/blob/master/config/example.config.toml"
    click id_util_config "https://github.com/assimon/captcha-bot/blob/master/util/config/config.go"
    click id_util_log "https://github.com/assimon/captcha-bot/blob/master/util/log/log.go"
    click id_util_captcha "https://github.com/assimon/captcha-bot/blob/master/util/captcha/captcha.go"
    click id_util_orm "https://github.com/assimon/captcha-bot/blob/master/util/orm/gorm.go"
    click id_util_error "https://github.com/assimon/captcha-bot/blob/master/util/error/error.go"
    click id_util_sensitive "https://github.com/assimon/captcha-bot/blob/master/util/sensitiveword/sensitiveword.go"
    click m1 "https://github.com/assimon/captcha-bot/blob/master/model/advertise.go"
    click m2 "https://github.com/assimon/captcha-bot/blob/master/model/base.go"
    click m3 "https://github.com/assimon/captcha-bot/blob/master/model/user_captcha_record.go"
    click s1 "https://github.com/assimon/captcha-bot/blob/master/service/advertiseService.go"
    click s2 "https://github.com/assimon/captcha-bot/blob/master/service/userCaptchaRecord.go"
    click t1 "https://github.com/assimon/captcha-bot/blob/master/telegram/command.go"
    click t2 "https://github.com/assimon/captcha-bot/blob/master/telegram/handle.go"
    click t3 "https://github.com/assimon/captcha-bot/blob/master/telegram/root.go"
    click t4 "https://github.com/assimon/captcha-bot/blob/master/telegram/sync.go"
    click d1 "https://github.com/assimon/captcha-bot/blob/master/dict/enc_dc1.txt"
    click d2 "https://github.com/assimon/captcha-bot/blob/master/dict/enc_dc2.txt"
    click dep1 "https://github.com/assimon/captcha-bot/tree/master/Dockerfile"
    click dep2 "https://github.com/assimon/captcha-bot/blob/master/docker-compose.yml"
    click dep3 "https://github.com/assimon/captcha-bot/blob/master/.goreleaser.yml"

    %% Styles
    classDef entry fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef boot fill:#ffe6cc,stroke:#cc9900,stroke-width:2px;
    classDef config fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef util fill:#cce5ff,stroke:#0066cc,stroke-width:2px;
    classDef model fill:#ffebcc,stroke:#cc6600,stroke-width:2px;
    classDef service fill:#e6ccff,stroke:#9933ff,stroke-width:2px;
    classDef telegram fill:#d9ead3,stroke:#66ff66,stroke-width:2px;
    classDef dict fill:#f4cccc,stroke:#ff6666,stroke-width:2px;
    classDef deployment fill:#d9d2e9,stroke:#9966cc,stroke-width:2px;
```
