# nmtechsolutionstuc/botnm architecture

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

- Interactive diagram: https://gitdiagram.com/nmtechsolutionstuc/botnm
- Repository: https://github.com/nmtechsolutionstuc/botnm

## Overview

#### Purpose and Runtime
`makebufferbot` is a Node.js Telegram long-polling bot that turns received media and user direction into Buffer drafts requiring manual approval. It also supports Telegram-group publishing and a separate YouTube draft flow. The process starts in `src/index.js`, which launches the bot plus HTTP endpoints for health checks and temporary media delivery.

#### Conversation State and Routing
Conversation progress is persisted per chat/user in `src/state/conversationStore.js` (`data/state.json` at runtime). The main router and photo-post workflow live in `src/bot/handlers.js`: collect one or more photos, choose a Sheet-defined mode, collect text/audio, select immediate or scheduled timing, optionally send to a group, then create Buffer drafts. Shared state transitions and UI/message utilities are centralized in `src/bot/shared.js`.

#### Mode Configuration Boundary
Google Sheets is the dynamic business configuration source: modes determine prompts, fixed copy, permitted Telegram users, and Buffer channel IDs. `src/services/sheets.js` reads and caches these rows; it allows adding brands/modes without code changes. Configuration/environment validation and service credentials are handled through `src/config.js`.

#### AI Generation and Fallback
AI operations are abstracted so Gemini is preferred but Cloudflare is a resilient fallback. `src/services/ai.js` orchestrates text generation, audio transcription, and trivia generation across providers. `src/services/gemini.js` handles Gemini image enhancement and content tasks; `src/services/cloudflare.js` handles Workers AI image generation/editing and fallback text/audio tasks. This boundary keeps bot flows provider-agnostic while exposing which fallback was used.

#### Image Command Subflow
`src/bot/imageCommands.js` implements `/generar`, `/editar`, and `/mejorar`. It creates or transforms media through Cloudflare, rate-limits requests with `src/services/rateLimit.js`, and requires user confirmation before adding the resulting image into the normal post-drafting conversation. Gemini image-enhancement failures similarly fall back to Cloudflare before retaining the original.

#### Publishing and Public-Media Boundary
`src/services/buffer.js` creates pending/scheduled Buffer posts through Buffer’s GraphQL API, using channel IDs selected from the mode configuration. Buffer needs publicly downloadable media rather than raw uploaded bytes; `src/services/mediaHost.js` temporarily exposes generated/downloaded media via the HTTP endpoint rooted at `src/index.js` (`/media/:id`). `PUBLIC_BASE_URL` is therefore required for media-containing Buffer drafts.

#### Alternative Delivery Flows
Telegram group posting is intentionally separate from Buffer delivery. `src/bot/groupCommands.js` parses direct group text/photo, polls, and quizzes; `src/services/telegramGroup.js` sends confirmed content to the configured Telegram group. `src/bot/youtubeFlow.js` is a separate state flow for incoming videos, producing distinct AI title/description fields and publishing through a separate YouTube Buffer token/channel configuration.

#### Infrastructure and External Services
The service depends on Telegram Bot API, Google Sheets API via a service account, Google Gemini, Cloudflare Workers AI, and Buffer GraphQL. It is designed for a persistent Node host such as Render; `/health` in `src/index.js` supports external uptime monitoring to prevent free-tier sleep from interrupting Telegram polling. Local persistent state is under `data/`, so deployments need durable storage if conversation recovery across restarts matters.

Main entry points: [`src/bot/handlers.js`](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/handlers.js) (Post workflow router), [`src/index.js`](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/index.js) (App entry & HTTP media), [`src/bot/imageCommands.js`](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/imageCommands.js) (Image commands), [`src/services/ai.js`](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/ai.js) (AI orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_index["App entry &amp; HTTP media<br/>Node runtime<br/>[index.js]"]
  node_state[("Conversation store<br/>state persistence")]
  node_state_file[("State file<br/>runtime data")]
end

subgraph group_bot["Telegram flows"]
  node_handlers["Post workflow router<br/>bot handler<br/>[handlers.js]"]
  node_shared["Shared conversation UI<br/>bot utilities<br/>[shared.js]"]
  node_image_commands["Image commands<br/>bot subflow<br/>[imageCommands.js]"]
  node_group_commands["Group commands<br/>bot subflow<br/>[groupCommands.js]"]
  node_youtube_flow["YouTube draft flow<br/>bot subflow<br/>[youtubeFlow.js]"]
end

subgraph group_services["Service layer"]
  node_config["Configuration<br/>credentials config<br/>[config.js]"]
  node_sheets["Mode configuration<br/>Sheets service<br/>[sheets.js]"]
  node_ai{{"AI orchestration<br/>provider facade<br/>[ai.js]"}}
  node_gemini["Gemini provider<br/>AI provider<br/>[gemini.js]"]
  node_cloudflare["Cloudflare provider<br/>AI provider<br/>[cloudflare.js]"]
  node_rate_limit["Image rate limiter<br/>request guard<br/>[rateLimit.js]"]
  node_buffer["Buffer drafts<br/>publishing service<br/>[buffer.js]"]
  node_media_host["Temporary media host<br/>public media service<br/>[mediaHost.js]"]
  node_telegram_group["Telegram group publisher<br/>delivery service<br/>[telegramGroup.js]"]
end

subgraph group_external["External platforms"]
  node_telegram(("Telegram Bot API<br/>messaging platform"))
  node_google_sheets(("Google Sheets API<br/>configuration platform"))
  node_ai_platforms(("Gemini &amp; Workers AI<br/>AI platforms"))
  node_buffer_api(("Buffer GraphQL API<br/>publishing platform"))
end

node_index -->|"routes updates"| node_handlers
node_index -->|"routes commands"| node_image_commands
node_index -->|"routes commands"| node_group_commands
node_index -->|"routes videos"| node_youtube_flow
node_index -->|"serves /media/:id"| node_media_host
node_index -->|"long polling"| node_telegram
node_handlers -->|"reads and writes progress"| node_state
node_handlers -->|"uses transitions and UI"| node_shared
node_handlers -->|"loads selected mode"| node_sheets
node_handlers -->|"generates text or transcribes"| node_ai
node_handlers -->|"creates Buffer draft"| node_buffer
node_image_commands -->|"limits requests"| node_rate_limit
node_image_commands -->|"enhances images"| node_gemini
node_image_commands -->|"generates, edits, fallback"| node_cloudflare
node_image_commands -->|"confirmed image enters draft flow"| node_handlers
node_group_commands -->|"publishes confirmed group content"| node_telegram_group
node_youtube_flow -->|"creates video metadata"| node_ai
node_youtube_flow -->|"creates YouTube draft"| node_buffer
node_state -->|"persists"| node_state_file
node_sheets -->|"reads mode rows"| node_google_sheets
node_ai -->|"preferred provider"| node_gemini
node_ai -.->|"fallback provider"| node_cloudflare
node_gemini -->|"calls"| node_ai_platforms
node_cloudflare -->|"calls"| node_ai_platforms
node_buffer -->|"requires public media URLs"| node_media_host
node_buffer -->|"creates posts"| node_buffer_api
node_config -->|"supplies credentials"| node_sheets
node_config -->|"supplies credentials"| node_ai
node_config -->|"supplies tokens"| node_buffer

click node_index "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/index.js"
click node_state "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/state/conversationStore.js"
click node_handlers "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/handlers.js"
click node_shared "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/shared.js"
click node_image_commands "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/imageCommands.js"
click node_group_commands "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/groupCommands.js"
click node_youtube_flow "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/youtubeFlow.js"
click node_config "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/config.js"
click node_sheets "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/sheets.js"
click node_ai "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/ai.js"
click node_gemini "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/gemini.js"
click node_cloudflare "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/cloudflare.js"
click node_rate_limit "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/rateLimit.js"
click node_buffer "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/buffer.js"
click node_media_host "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/mediaHost.js"
click node_telegram_group "https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/telegramGroup.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_state,node_state_file toneBlue
class node_handlers,node_shared,node_image_commands,node_group_commands,node_youtube_flow toneAmber
class node_config,node_sheets,node_ai,node_gemini,node_cloudflare,node_rate_limit,node_buffer,node_media_host,node_telegram_group toneMint
class node_telegram,node_google_sheets,node_ai_platforms,node_buffer_api toneRose
```

## Components

### Runtime

Node process and persistent conversation state.

- [App entry & HTTP media](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/index.js): Node runtime · Starts Telegram polling and exposes health and temporary media endpoints. · `src/index.js`
- [Conversation store](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/state/conversationStore.js): state persistence · Persists progress per chat and user. · `src/state/conversationStore.js`
- **State file**: runtime data

### Telegram flows

Conversation routing and alternative delivery flows.

- [Post workflow router](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/handlers.js): bot handler · Collects media, mode, content, timing, and delivery choices. · `src/bot/handlers.js`
- [Shared conversation UI](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/shared.js): bot utilities · `src/bot/shared.js`
- [Image commands](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/imageCommands.js): bot subflow · Handles generation, editing, enhancement, and confirmation. · `src/bot/imageCommands.js`
- [Group commands](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/groupCommands.js): bot subflow · Parses direct group posts, polls, and quizzes. · `src/bot/groupCommands.js`
- [YouTube draft flow](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/bot/youtubeFlow.js): bot subflow · Builds video-specific titles and descriptions. · `src/bot/youtubeFlow.js`

### Service layer

Provider-agnostic integrations and configuration.

- [Configuration](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/config.js): credentials config · Validates environment and service credentials. · `src/config.js`
- [Mode configuration](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/sheets.js): Sheets service · Caches modes, prompts, permissions, and Buffer channel IDs. · `src/services/sheets.js`
- [AI orchestration](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/ai.js): provider facade · Selects Gemini or Cloudflare for generation and transcription. · `src/services/ai.js`
- [Gemini provider](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/gemini.js): AI provider · Performs content tasks and image enhancement. · `src/services/gemini.js`
- [Cloudflare provider](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/cloudflare.js): AI provider · Provides image generation/editing and fallback text or audio tasks. · `src/services/cloudflare.js`
- [Image rate limiter](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/rateLimit.js): request guard · `src/services/rateLimit.js`
- [Buffer drafts](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/buffer.js): publishing service · Creates pending or scheduled posts through GraphQL. · `src/services/buffer.js`
- [Temporary media host](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/mediaHost.js): public media service · Makes media downloadable for Buffer. · `src/services/mediaHost.js`
- [Telegram group publisher](https://github.com/nmtechsolutionstuc/botnm/blob/master/src/services/telegramGroup.js): delivery service · Sends confirmed content to the configured group. · `src/services/telegramGroup.js`

### External platforms

- **Telegram Bot API**: messaging platform
- **Google Sheets API**: configuration platform
- **Gemini & Workers AI**: AI platforms
- **Buffer GraphQL API**: publishing platform

## Connections

- App entry & HTTP media → Post workflow router: routes updates
- App entry & HTTP media → Image commands: routes commands
- App entry & HTTP media → Group commands: routes commands
- App entry & HTTP media → YouTube draft flow: routes videos
- App entry & HTTP media → Temporary media host: serves /media/:id
- App entry & HTTP media → Telegram Bot API: long polling
- Post workflow router → Conversation store: reads and writes progress
- Post workflow router → Shared conversation UI: uses transitions and UI
- Post workflow router → Mode configuration: loads selected mode
- Post workflow router → AI orchestration: generates text or transcribes
- Post workflow router → Buffer drafts: creates Buffer draft
- Image commands → Image rate limiter: limits requests
- Image commands → Gemini provider: enhances images
- Image commands → Cloudflare provider: generates, edits, fallback
- Image commands → Post workflow router: confirmed image enters draft flow
- Group commands → Telegram group publisher: publishes confirmed group content
- YouTube draft flow → AI orchestration: creates video metadata
- YouTube draft flow → Buffer drafts: creates YouTube draft
- Conversation store → State file: persists
- Mode configuration → Google Sheets API: reads mode rows
- AI orchestration → Gemini provider: preferred provider
- AI orchestration → Cloudflare provider: fallback provider
- Gemini provider → Gemini & Workers AI: calls
- Cloudflare provider → Gemini & Workers AI: calls
- Buffer drafts → Temporary media host: requires public media URLs
- Buffer drafts → Buffer GraphQL API: creates posts
- Configuration → Mode configuration: supplies credentials
- Configuration → AI orchestration: supplies credentials
- Configuration → Buffer drafts: supplies tokens