# insanusmokrassar/ktgbotapi architecture

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

- Interactive diagram: https://gitdiagram.com/insanusmokrassar/ktgbotapi
- Repository: https://github.com/insanusmokrassar/ktgbotapi

## Overview

##### Project type and purpose
- Type: Multi-module, Kotlin Multiplatform library (JVM, JS, native)
- Purpose: Provide a strongly-typed, coroutine-based Kotlin interface to Telegram’s Bot API, plus higher-level behavior builders, utilities, and KSP code generation.

##### Top-level component decomposition
- tgbotapi.core
- tgbotapi.api
- tgbotapi.behaviour_builder
- tgbotapi.behaviour_builder.fsm
- tgbotapi.utils
- tgbotapi.webapps
- tgbotapi.ksp
- Consumer application (example bots)
- External service: Telegram Bot API server
- CI/CD: GitHub Actions / Maven Central / Dokka publishing

##### Relationships and data flow
a. Core layer (tgbotapi.core)
– Implements HTTP layers via Ktor (RequestExecutor → TelegramBotPipelinesHandler → multipart, download, etc.)
– Defines `types/`, `requests/`, `updateshandlers/`, `utils/` in commonMain + platformMain sources.
b. API module (tgbotapi.api)
– Contains IDL-style API definitions (package tgbotapi.api.api) that core & builders implement.
c. Behaviour builders (tgbotapi.behaviour_builder & fsm)
– Layer on core to provide coroutine-based “onCommand”, “waitPhoto” DSL.
– FSM module builds on the base behaviour module.
d. Utilities (tgbotapi.utils)
– Extensions & helpers to simplify filters, flows, JSON formatting, parsing.
– Consumed by behaviour_builder and client code.
e. WebApps module (tgbotapi.webapps)
– Kotlin/JS bindings to Telegram WebApp features (callbacks, UI widgets).
f. KSP plugin (tgbotapi.ksp)
– Compile-time code generation for class casts filler, symbol processor.
g. Consumer bots & examples
– Show sample `main()` with `telegramBot(TOKEN)` → uses behaviour_builder.
h. CI/CD & documentation
– GitHub Actions workflows (.github/workflows/*.yml) for testing, publishing to Maven Central, generating docs via Dokka or MkDocs.

##### Architectural patterns and principles
- Layered architecture:
– Core (foundation)
– API definitions
– DSL / Behaviour (application logic)
– Client code (examples)
- Multiplatform: each module has `commonMain`, `jvmMain`, `jsMain`, native source sets.
- DSL & builder pattern in behaviour modules for event handlers.
- KSP for compile-time metaprogramming.
- CI pipeline for automated testing & publishing.

##### Recommended elements
- Module names & source‐sets (commonMain, platformMain).
- Ktor HTTP pipeline inside core.
- CI/CD workflows node linking to Gradle build & Maven Central.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Foundation Modules"
        Core["tgbotapi.core\n(commonMain, jvmMain, jsMain)"]:::foundation
        API["tgbotapi.api\n(commonMain, jvmMain)"]:::foundation
    end

    subgraph "Feature Modules"
        BB["tgbotapi.behaviour_builder\n(commonMain)"]:::feature
        FSM["tgbotapi.behaviour_builder.fsm\n(commonMain)"]:::feature
        Utils["tgbotapi.utils\n(commonMain, jvmMain)"]:::feature
        WebApps["tgbotapi.webapps\n(commonMain, jsMain)"]:::feature
        KSP["tgbotapi.ksp\n(src/main/kotlin)"]:::feature
    end

    Consumer["Consumer Examples\n(sample bots)"]:::consumer
    Telegram["Telegram Bot API Server"]:::external
    CI["CI/CD & Docs\n(GitHub Actions, Travis, Dokka)"]:::external

    API -->|"defines API"| Core
    BB -->|"uses API definitions"| API
    FSM -->|"builds on DSL"| BB
    BB -->|"calls core HTTP"| Core
    Utils -->|"helpers for DSL"| BB
    Utils -->|"helpers for examples"| Consumer
    Consumer -->|"uses DSL"| BB
    Consumer -->|"uses helpers"| Utils
    Core -->|"HTTPS calls"| Telegram
    WebApps -->|"JS SDK calls"| Telegram
    KSP -->|"generates code in"| Core
    KSP -->|"generates code in"| API
    KSP -->|"generates code in"| BB
    KSP -->|"generates code in"| FSM
    KSP -->|"generates code in"| Utils
    KSP -->|"generates code in"| WebApps
    CI -->|"publishes modules & docs"| Core
    CI -->|"publishes modules & docs"| API
    CI -->|"publishes modules & docs"| BB
    CI -->|"publishes modules & docs"| FSM
    CI -->|"publishes modules & docs"| Utils
    CI -->|"publishes modules & docs"| WebApps
    CI -->|"publishes modules & docs"| KSP

    click Core "https://github.com/insanusmokrassar/ktgbotapi/tree/master/tgbotapi.core/"
    click API "https://github.com/insanusmokrassar/ktgbotapi/tree/master/tgbotapi.api/"
    click BB "https://github.com/insanusmokrassar/ktgbotapi/tree/master/tgbotapi.behaviour_builder/"
    click FSM "https://github.com/insanusmokrassar/ktgbotapi/tree/master/tgbotapi.behaviour_builder.fsm/"
    click Utils "https://github.com/insanusmokrassar/ktgbotapi/tree/master/tgbotapi.utils/"
    click WebApps "https://github.com/insanusmokrassar/ktgbotapi/tree/master/tgbotapi.webapps/"
    click KSP "https://github.com/insanusmokrassar/ktgbotapi/tree/master/tgbotapi.ksp/"
    click Consumer "https://github.com/insanusmokrassar/ktgbotapi/tree/master/tgbotapi/"
    click CI "https://github.com/insanusmokrassar/ktgbotapi/tree/master/.github/workflows/"

    classDef foundation fill:#AED6F1,stroke:#21618C,color:#000
    classDef feature fill:#A3E4D7,stroke:#117A65,color:#000
    classDef external fill:#E5E7E9,stroke:#85929E,color:#000,stroke-dasharray:5 5
    classDef consumer fill:#F9E79F,stroke:#B7950B,color:#000
```
