# fabricior/rsvp-telegram-bot architecture

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

- Interactive diagram: https://gitdiagram.com/fabricior/rsvp-telegram-bot
- Repository: https://github.com/fabricior/rsvp-telegram-bot

## Overview

##### Project Type and Purpose
- This is a Telegram bot project focused on facilitating game attendance management (e.g., scheduling a Five-a-side football match). Users interact via Telegram commands (/new, /yes, /no, /maybe, /status, etc.) to schedule games and RSVP.
- It is a serverless application deployed as a Google Cloud Function, implemented in Node.js with TypeScript and using telegraf as the Telegram API wrapper. The data is stored in a MongoDB database managed through Prisma.

##### Main Components
a. Telegram Interface:
- Telegram API as the channel for incoming updates to your bot service.
b. Bot Service (Cloud Function):
- The core of the bot is implemented within the Node.js application under the “src” directory. Key files include:
- index.ts (likely the entry point for the Cloud Function)
- bot.ts (handles Telegram Bot initialization and command routing using telegraf)
- middleware.ts (for processing requests like authentication, logging, or internationalization)
- Other business logic files such as game.ts, rsvp.ts, and guest handling in guest.ts
c. Database Layer:
- MongoDB instance working as a replica set as described in the README.
- ORM layer using Prisma, referencing files in the “prisma” directory (schema.prisma and seed.ts). This is the bridge between the bot and the database.
d. External Tools & Deployment:
- Google Cloud Functions infrastructure, showing that the bot is deployed via a HTTP trigger.
- Optionally, include configuration steps related to environment variables (.env, .env.yaml conversion) and the Dockerfile (mention limited usage in deployment).
e. Testing & Development:
- Testing component (Jest tests inside src/test, specifically rsvp.test.ts) to emphasize continuous integration and validation of business logic.

##### Relationships and Data Flow
- Within the bot service, divide the internal logic into separate components:
- Command Parsing / Middleware (which intercepts and prepares incoming commands)
- Business Logic Handlers (corresponding to individual commands: create game, RSVP responses, guest management)
- Utility modules (such as dates, translations)

##### Architectural Patterns and Technologies
- Mention that the bot follows a modular design where each command/feature is handled in separate files.
- The use of middleware implies separation of concerns (authentication, enrollment, localization).
- Clearly label key technologies: Node.js, TypeScript, telegraf, MongoDB (with replica set), Prisma, and Google Cloud Functions as critical parts of the stack.

##### Instructing the Principal Software Engineer
- Use a hierarchical layout: External Clients (Telegram Users) → Telegram API → Cloud Function (RSVP Bot Service) → Business Logic Modules → Database (MongoDB via Prisma).
- Component with its file counterparts where applicable (e.g., “Bot Logic: src/bot.ts, src/rsvp.ts, src/guest.ts”).
- The flow of incoming messages from the Telegram API to your bot.
- How commands are processed by middleware and routed to specific business logic.
- The connection from business logic to the persistent database.
- That every key relation is captured (e.g., state changes in the database when a new game is created, how RSVP updates are handled, and guest management interactions).
- Don’t hesitate to capture even a small module (like translations) as a separate component if needed to fully explain interactions—this will help future maintainers and engineers understand where changes might be required.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    A["Telegram User"]:::external
    B["Telegram API"]:::external

    A -->|"sends commands"| B

    %% RSVP Bot Service (Google Cloud Function)
    subgraph "RSVP Bot Service (Google Cloud Function)"
        CF["Cloud Function Entry Point (index.ts)"]:::service
        BI["Bot Initialization (bot.ts, botTypes.ts)"]:::service
        MW["Command Parsing & Middleware (middleware.ts)"]:::service
        GL["Game Logic (game.ts)"]:::service
        RL["RSVP Logic (rsvp.ts)"]:::service
        GM["Guest Management (guest.ts)"]:::service
    end

    B -->|"forwards update"| CF
    CF -->|"initializes"| BI
    BI -->|"routes to"| MW
    MW -->|"handles game creation"| GL
    MW -->|"processes RSVP responses"| RL
    MW -->|"manages guest list"| GM

    %% Database Layer
    subgraph "Database Layer"
        DTS["DB Connection (db.ts)"]:::database
        PR["Prisma ORM (prisma/)"]:::database
        DB["MongoDB Replica Set"]:::database
    end

    GL -->|"stores game data"| PR
    RL -->|"updates RSVP status"| PR
    GM -->|"updates guest info"| PR
    DTS -->|"connects"| PR
    PR -->|"persists data"| DB

    %% Deployment & Configuration
    DC["Deployment & Configuration (.env.template, Dockerfile, .gcloudignore)"]:::deployment
    DC -->|"configures"| CF

    %% Testing & Development
    TEST["Jest Testing (rsvp.test.ts)"]:::testing
    TEST -->|"validates"| GL
    TEST -->|"validates"| RL
    TEST -->|"validates"| GM

    %% Click Events
    click B "https://github.com/fabricior/rsvp-telegram-bot/blob/main/src/bot.ts"
    click B "https://github.com/fabricior/rsvp-telegram-bot/blob/main/src/botTypes.ts"
    click CF "https://github.com/fabricior/rsvp-telegram-bot/blob/main/src/index.ts"
    click GL "https://github.com/fabricior/rsvp-telegram-bot/blob/main/src/game.ts"
    click RL "https://github.com/fabricior/rsvp-telegram-bot/blob/main/src/rsvp.ts"
    click GM "https://github.com/fabricior/rsvp-telegram-bot/blob/main/src/guest.ts"
    click MW "https://github.com/fabricior/rsvp-telegram-bot/blob/main/src/middleware.ts"
    click DTS "https://github.com/fabricior/rsvp-telegram-bot/blob/main/src/db.ts"
    click PR "https://github.com/fabricior/rsvp-telegram-bot/tree/main/prisma/"
    click DC "https://github.com/fabricior/rsvp-telegram-bot/blob/main/.env.template"
    click DC "https://github.com/fabricior/rsvp-telegram-bot/tree/main/Dockerfile"
    click DC "https://github.com/fabricior/rsvp-telegram-bot/blob/main/.gcloudignore"
    click TEST "https://github.com/fabricior/rsvp-telegram-bot/blob/main/src/test/rsvp.test.ts"

    %% Styling
    classDef external fill:#aqua,stroke:#000,stroke-width:2px;
    classDef service fill:#cfc,stroke:#000,stroke-width:2px;
    classDef database fill:#f88,stroke:#000,stroke-width:2px,stroke-dasharray: 5 5;
    classDef deployment fill:#fc9,stroke:#000,stroke-width:2px;
    classDef testing fill:#ff9,stroke:#000,stroke-width:2px;
```
