# telegrambotindonesia/gas-lib-v3 architecture

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

- Interactive diagram: https://gitdiagram.com/telegrambotindonesia/gas-lib-v3
- Repository: https://github.com/telegrambotindonesia/gas-lib-v3

## Overview

##### Project type and purpose
- This is an open-source Google Apps Script (GAS) library (“GAS Lib v3”) for building Telegram bots.
- Its purpose is to provide a modular, promise-based wrapper around the Telegram Bot API, exposing an easy DSL (`bot.cmd`, `bot.hears`, `ctx.reply`, etc.) that runs inside a GAS WebApp.

##### File structure
- Top-level:
- core/ – the library modules broken into single-responsibility files (version, helper, markup, event pipeline, context, composer, client, telegram API wrapper, HTTP fetch, user database, main entry).
- core/appsscript.json – GAS manifest (WebApp entry points, scopes).
- examples/ – sample user scripts demonstrating how to import the library and define bot behaviors.
- docs/ – markdown docs for deeper reference.
- deploy.md, package.json – build/deployment instructions via clasp and npm tooling.

##### README for additional insights
- Explains how to initialize the bot (`lumpia.init(token)`), wire up `doPost(e)` as the webhook handler, then register handlers via `.start`, `.cmd`, `.hears`.
- Mentions that the library handles parsing update payloads, matching patterns, and sending messages back via Telegram API.

##### Components
a. Main components
1. Telegram Bot API (external service)
2. GAS WebApp server (the hosted script)
3. lumpia core modules (inside core/)
- HTTP Entry (doPost)
- Event dispatcher & pipeline (event.js, composer.js)
- Context manager (context.js)
- Command/hears matcher
- Telegram client & fetch wrapper (telegram.js, fetch.js, client.js)
- Utilities (helper.js, markup.js, version.js)
- User state storage (userdb.js)
4. User’s bot script (examples/*.js) that imports lumpia, calls `init()` and registers handlers
5. Optional external storage (PropertiesService, Google Sheets via GAS)
b. Relationships and data flow
1. Telegram sends an HTTPS POST (update JSON) → GAS WebApp `doPost(e)` entry
2. `doPost` calls `lumpia.main` → core.event triggers pipeline
3. Pipeline builds a `Context` object → composer invokes matching handlers (`.start`, `.cmd`, `.hears`) defined by user script
4. Handlers call `ctx.reply` or `ctx.replyIt` → core.client & fetch wrap UrlFetchApp → send HTTPS requests to Telegram API
5. For stateful bots, `userdb.js` reads/writes from GAS storage (PropertiesService or Spreadsheet)
c. Architectural patterns/design principles
- Modular single‐responsibility files (each core file handles one concern)
- Middleware/event‐pipeline pattern for update processing
- Dependency inversion: user script only depends on the lumpia API, not on underlying fetch or storage details
- Extension points: users add handlers; library core remains untouched
d. Key technologies/frameworks
- Google Apps Script WebApp environment
- UrlFetchApp for HTTP requests
- Clasp CLI for deployment
- Telegram Bot HTTP API

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Services"
        Telegram["Telegram API"]:::external
        Storage["GAS Storage\n(PropertiesService/Sheets)"]:::external
    end

    subgraph "GAS WebApp Environment"
        subgraph "Entry Point"
            doPost["doPost (WebApp Entry)"]:::core
            Main["main.js"]:::core
            Manifest["appsscript.json"]:::core
        end

        subgraph "lumpia Core Modules"
            version["version.js"]:::core
            helper["helper.js"]:::core
            markup["markup.js"]:::core
            event["event.js"]:::core
            composer["composer.js"]:::core
            context["context.js"]:::core
            client["client.js"]:::core
            telegram["telegram.js"]:::core
            fetch["fetch.js"]:::core
            userdb["userdb.js"]:::core
        end
    end

    subgraph "User Bot Scripts"
        bot["bot.js"]:::user
        keyboard["keyboard_inline.js"]:::user
        payload["payload.js"]:::user
        ping["ping.js"]:::user
        user_version["version.js"]:::user
    end

    Telegram --> doPost
    doPost --> event
    event --> context
    context --> composer
    composer --> bot
    composer --> keyboard
    composer --> payload
    composer --> ping
    composer --> user_version
    bot --> client
    keyboard --> client
    payload --> client
    ping --> client
    user_version --> client
    client --> telegram
    telegram --> fetch
    context --> userdb
    userdb <--> Storage

    version -.-> event
    helper -.-> composer
    markup -.-> client

    classDef external fill:#f9d,stroke:#333
    classDef core fill:#9fd,stroke:#333
    classDef user fill:#ddf,stroke:#333

    click doPost "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/90 main.js"
    click Manifest "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/appsscript.json"
    click event "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/20 event.js"
    click composer "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/40 composer.js"
    click context "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/30 context.js"
    click client "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/50 client.js"
    click fetch "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/70 fetch.js"
    click telegram "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/60 telegram.js"
    click version "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/00 version.js"
    click helper "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/10 helper.js"
    click markup "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/15 markup.js"
    click userdb "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/core/80 userdb.js"
    click bot "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/examples/bot.js"
    click keyboard "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/examples/keyboard_inline.js"
    click payload "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/examples/payload.js"
    click ping "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/examples/ping.js"
    click user_version "https://github.com/telegrambotindonesia/gas-lib-v3/blob/main/examples/version.js"
```
