# marcelobvieira/pais-cansados-bot architecture

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

- Interactive diagram: https://gitdiagram.com/marcelobvieira/pais-cansados-bot
- Repository: https://github.com/marcelobvieira/pais-cansados-bot

## Overview

##### Tipo e propósito do projeto (o que seu diagrama precisa “contar”)
Este projeto é um **Telegram Bot serverless e stateless** (Node.js + Telegraf) hospedado na **Vercel** e acionado por **Webhook**. A função principal é **coletar dados via um fluxo conversacional (Wizard)** e **registrar filmes/séries em um Google Sheets** (abas “Filmes” e “Séries”), usando **Service Account (JWT)** para autenticação.

O diagrama ideal deve evidenciar:
- **Evento de entrada**: mensagem do usuário no Telegram → Telegram Webhook → Vercel.
- **Orquestração**: Telegraf + Scenes/Wizard guiando perguntas.
- **Persistência**: não há banco; o “registro” final é a **planilha no Google Sheets**.
- **Segurança**: `WEBHOOK_SECRET` (validar origem/URL) + `ALLOWED_USERS` (controle de acesso).

#### 2) Mapeamento do file tree para componentes arquiteturais (use isso para “ancorar” o diagrama)
Pelos arquivos/diretórios:

##### Entrada/Deploy
- `api/webhook.js`
**Container/Entry-point serverless**: endpoint HTTP na Vercel que recebe POST do Telegram e dispara o Telegraf para processar o update.
- `vercel.json`
**Config de deploy/roteamento** (como a Vercel expõe `/api/webhook`).
- `.env.example`
**Config/Secrets** (tokens, IDs, service account, allowed users, segredo do webhook).

##### Domínio do Bot
- `lib/bot.js`
**Composição do bot**: inicialização do Telegraf, middlewares (ex.: allowed users), registro de scenes/handlers.
- `lib/scenes/filmesSeriesScene.js`
**Wizard/Fluxo conversacional**: coleta campos (Nome, Origem, Nota, etc.) e ramifica para “Filmes” vs “Séries” (ex.: Temporada para séries).

##### Integração com Google Sheets
- `lib/sheets.js`
**Gateway/Adapter** para Google Sheets: autenticação JWT (service account) + operações de append/update nas abas.

##### Dependências/Build
- `package.json` / `package-lock.json`
**Runtime Node + libs**: Telegraf, node-google-spreadsheet, google-auth-library.

No diagrama, isso vira: **1 endpoint serverless** + **módulos internos** (bot/scenes/sheets) + **serviços externos** (Telegram, Google APIs).

##### Como desenhar o “melhor e mais preciso” diagrama (em camadas, estilo C4)

Mostra atores e sistemas externos:
- **Ator**: Usuário (Telegram App)
- **Sistema externo**: Telegram Platform (Webhook delivery)
- **Seu sistema**: “Pais Cansados Bot (Vercel Serverless)”
- **Sistema externo**: Google Sheets (via Google Sheets API)
- **Identidade/Auth**: Google Service Account (JWT) / Google Auth

**Setas principais (data flow):**
##### Google Sheets API → Google Sheets (persistência final)

Aqui o “seu sistema” se detalha:
- **Vercel Serverless Function** (container compute): `api/webhook.js`
- **Bot Runtime (Telegraf)** (dentro da função): `lib/bot.js`
- **Conversation/Wizard**: `lib/scenes/filmesSeriesScene.js`
- **Sheets Adapter**: `lib/sheets.js`
- **Config/Secrets**: env vars injetadas pela Vercel

**Pontos cruciais para desenhar com fidelidade:**
- O bot é **on-demand**: não existe processo rodando 24/7; a execução nasce do webhook.
- “State” do wizard: como não há Redis/DB no repo, represente como **estado efêmero em memória do runtime** (pode ser best-effort em serverless). Mesmo que o README chame de stateless, a conversa guiada normalmente depende de um estado transiente entre mensagens—vale explicitar como “Session/Wizard State (ephemeral)”.

Ideal para capturar “separar o projeto no máximo de componentes” (como você pediu):
- **Webhook Handler** (`api/webhook.js`)
- valida `WEBHOOK_SECRET`
- parse do update
- encaminha para Telegraf
- **Global Middleware** (`lib/bot.js`)
- **Allowed Users Filter**: valida `ALLOWED_USERS`
- **Scenes Router**
- decide “Filme vs Série”
- **Wizard Steps** (`lib/scenes/filmesSeriesScene.js`)
- perguntas/captura (Nome, Origem, Nota, Lançamento, Onde vimos, etc.)
- para séries inclui Temporada
- ao final chama o gateway do Sheets
- **Sheets Gateway** (`lib/sheets.js`)
- auth (JWT via google-auth-library)
- open doc by `GOOGLE_SHEETS_DOCUMENT_ID`
- select tab: “Filmes” ou “Séries”
- append row (com “Mês” etc.)
- inclui o “parser robusto” da private key (mencione como subcomponente: “Private Key Normalizer/Parser”)

##### Relações e interações que o diagrama deve mostrar (setas e protocolos)
Use setas direcionais com rótulos de protocolo/formato:

- **Telegram → Vercel**: `HTTPS POST /api/webhook (Telegram Update JSON)`
- **Vercel → Telegram**: `HTTPS (sendMessage/editMessage)` via Bot API (Telegraf abstrai)
- **Vercel → Google APIs**:
- `JWT Auth` (Service Account)
- `Google Sheets API` (append row)
- **Config**: Vercel injects env vars → função lê env vars (`TELEGRAM_BOT_TOKEN`, `WEBHOOK_SECRET`, etc.)

Inclua também fluxos de “negação” (importante para precisão):
- Request sem `webhook_secret` correto → **reject/ignore**
- User não está em `ALLOWED_USERS` → **reject/ignore**
- Erro Google Auth / Sheets API → **log + resposta amigável ao usuário** (se existir; se não existir no código, ao menos marque como “erro possível”)

##### Padrões/princípios arquiteturais a destacar (o “porquê” do desenho)
- **Serverless Webhook**: compute elástico, acorda sob demanda.
- **Adapter/Gateway**: `lib/sheets.js` encapsula Google Sheets.
- **Conversation Orchestration (Wizard/State machine)**: `lib/scenes/*`.
- **Security-by-default**:
- endpoint protegido por segredo no URL (`WEBHOOK_SECRET`)
- autorização por allowlist (`ALLOWED_USERS`)
- **No DB**: o “sistema de registro” é o Google Sheets (storage externo).

##### Tecnologias a rotular no diagrama (não deixe implícito)
- Node.js (ES Modules)
- Telegraf (Scenes/Wizard)
- Vercel Serverless Functions
- Telegram Bot API + Webhooks
- Google Sheets API via `node-google-spreadsheet`
- Google Auth Library (JWT Service Account)
- Env vars / Secrets management (Vercel)

##### Convenções visuais (para ficar “inequívoco”)
Para o diagrama ficar imediatamente legível:

##### Rotulagem das setas
Sempre inclua: **protocolo + payload** (ex.: “HTTPS POST (Update JSON)” / “Sheets appendRow”).

##### À esquerda: Usuário + Telegram
2. Centro: **Vercel** com a caixa `/api/webhook.js` (entrada) e dentro dela os componentes (`lib/bot.js`, `lib/scenes/...`, `lib/sheets.js`).
3. À direita: **Google APIs** e abaixo/ao lado **Google Sheets (doc com abas Filmes/Séries)**.

##### Checklist final de precisão (o que mais costuma faltar)
- Explicitou que **o webhook é registrado via `setWebhook`** apontando para a URL da Vercel com `webhook_secret`?
- Mostrou **dois controles de segurança** (secret + allowlist)?
- Representou que **não existe banco próprio**; a escrita final é no **Google Sheets** (duas abas)?
- Indicou o **ponto de entrada único** (`api/webhook.js`) e o runtime serverless?
- Detalhou o **Wizard** como máquina de estados/fluxo guiado e o **Sheets adapter** como camada de integração?

Se você desenhar nesses 2–3 níveis (Context + Container + Component), com esses rótulos e fluxos, você terá um diagrama altamente fiel ao repo e “separado no máximo de componentes” sem perder a narrativa principal do sistema.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% LEVEL A — C4 CONTEXT
  %% =========================
  subgraph L0["Level A — Context (C4)"]
    direction TB

    U["User\n(Telegram App)"]:::person
    TG["Telegram Platform\n(Webhook Delivery + Bot API)"]:::external

    subgraph SYS["Pais Cansados Bot\n(Vercel Serverless, Node.js + Telegraf)"]
      direction TB
      SYSBOX["System Boundary"]:::system
    end

    GAPI["Google APIs\n(Google Auth + Sheets API)"]:::external
    GSH[("Google Sheets Document\nTabs: Filmes | Séries")]:::storage

    U -->|"messages"| TG
    TG -->|"HTTPS POST /api/webhook\n(Telegram Update JSON)"| SYSBOX
    SYSBOX -->|"HTTPS (sendMessage/editMessage)\nvia Bot API (Telegraf)"| TG
    SYSBOX -->|"JWT Auth + Sheets API\n(appendRow/write)"| GAPI
    GAPI -->|"persist rows"| GSH
  end

  %% =========================
  %% LEVEL B — CONTAINERS
  %% =========================
  subgraph L1["Level B — Containers (within Vercel Project)"]
    direction TB

    VERCEL["Vercel Project\n(Serverless Runtime)"]:::compute

    subgraph C1["Serverless Function Invocation (on-demand)"]
      direction TB

      WH["Webhook Handler\n/api/webhook"]:::compute
      BOT["Bot Runtime\nTelegraf App Composition"]:::compute

      SCENES["Conversation Orchestration\nScenes/Wizard Router"]:::compute
      WIZ["Filmes vs Séries Wizard\n(questions + branching)"]:::compute

      STATE["Session/Wizard State\n(ephemeral in-memory)"]:::state

      SHEETS["Sheets Gateway/Adapter\n(node-google-spreadsheet)"]:::integration
      JWT["Service Account JWT Auth\n(google-auth-library)"]:::integration
      KEYP["Private Key Normalizer/Parser"]:::integration

      ENV["Env Vars / Secrets\n(Vercel injected)"]:::config
    end

    VERCEL -->|"invokes"| WH
    ENV -->|"read config"| WH
    ENV -->|"read token/config"| BOT
    WH -->|"hands update to"| BOT
    BOT -->|"routes to"| SCENES
    SCENES -->|"runs steps"| WIZ
    WIZ <-->|"store transient state"| STATE
    WIZ -->|"append row (Filmes|Séries)"| SHEETS
    SHEETS -->|"normalize private key"| KEYP
    SHEETS -->|"JWT auth"| JWT
  end

  %% =========================
  %% LEVEL C — COMPONENTS (inside function)
  %% =========================
  subgraph L2["Level C — Components (inside /api/webhook execution)"]
    direction TB

    subgraph CWEB["Webhook Handler Components"]
      direction TB
      VSEC["Validate WEBHOOK_SECRET\n(query param)"]:::security
      PARSE["Parse Update JSON"]:::compute
      REJ1["Reject/Ignore\n(Invalid secret)"]:::deny
    end

    subgraph CBOT["Telegraf Bot Components"]
      direction TB
      MW["Global Middleware"]:::compute
      ALLOW["Allowed Users Filter\n(ALLOWED_USERS allowlist)"]:::security
      REJ2["Reject/Ignore\n(Unauthorized user)"]:::deny
      ROUTER["Scenes Router\n(start/next/back)"]:::compute
    end

    subgraph CWIZ["Wizard Steps (Filmes/Séries)"]
      direction TB
      Q1["Collect Fields\nNome, Origem, Nota, Lançamento,\nOnde vimos, etc."]:::compute
      BR["Branch\nFilme vs Série\n(Série adds Temporada)"]:::compute
      FINAL["Finalize Payload\n(includes Mês, tab selection)"]:::compute
    end

    subgraph CSHEETS["Sheets Integration Components"]
      direction TB
      DOC["Open Spreadsheet\n(GOOGLE_SHEETS_DOCUMENT_ID)"]:::integration
      TAB["Select Worksheet\n('Filmes' or 'Séries')"]:::integration
      APP["Append Row / Write"]:::integration
      ERR["Error Handling\n(GAuth/Sheets failures)\nlog + user-friendly reply (if implemented)"]:::error
    end

    WH -->|"checks secret"| VSEC
    VSEC -->|"invalid"| REJ1
    VSEC -->|"valid"| PARSE
    PARSE -->|"dispatch update"| BOT

    BOT -->|"runs"| MW
    MW -->|"enforces"| ALLOW
    ALLOW -->|"not allowed"| REJ2
    ALLOW -->|"allowed"| ROUTER
    ROUTER -->|"enter/continue"| Q1
    Q1 -->|"decide type"| BR
    BR -->|"collect remaining"| Q1
    Q1 -->|"done"| FINAL
    FINAL -->|"call sheets gateway"| SHEETS

    SHEETS -->|"open doc"| DOC
    DOC -->|"choose tab"| TAB
    TAB -->|"append"| APP
    JWT -->|"auth for"| DOC
    APP -->|"on error"| ERR
  end

  %% =========================
  %% External connections to containers/components
  %% =========================
  TG -->|"HTTPS POST /api/webhook\n(Update JSON)"| WH
  BOT -->|"HTTPS Bot API\n(sendMessage/editMessage)"| TG
  JWT -->|"JWT (Service Account)"| GAPI
  APP -->|"Sheets API requests"| GAPI
  GAPI -->|"writes rows"| GSH

  %% =========================
  %% CLICK EVENTS (paths only)
  %% =========================
  click WH "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/api/webhook.js"
  click VERCEL "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/vercel.json"
  click ENV "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/.env.example"
  click BOT "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/bot.js"
  click WIZ "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/scenes/filmesSeriesScene.js"
  click SHEETS "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/sheets.js"
  click SCENES "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/scenes/filmesSeriesScene.js"
  click JWT "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/sheets.js"
  click KEYP "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/sheets.js"
  click PARSE "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/api/webhook.js"
  click VSEC "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/api/webhook.js"
  click ALLOW "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/bot.js"
  click ROUTER "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/bot.js"
  click DOC "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/sheets.js"
  click TAB "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/sheets.js"
  click APP "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/sheets.js"
  click ERR "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/sheets.js"
  click SYSBOX "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/bot.js"
  click MW "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/bot.js"
  click Q1 "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/scenes/filmesSeriesScene.js"
  click BR "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/scenes/filmesSeriesScene.js"
  click FINAL "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/scenes/filmesSeriesScene.js"
  click REJ1 "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/api/webhook.js"
  click REJ2 "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/bot.js"
  click STATE "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/bot.js"
  click SYS "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/lib/bot.js"
  click L1 "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/package.json"
  click L2 "https://github.com/marcelobvieira/pais-cansados-bot/blob/main/package-lock.json"

  %% =========================
  %% STYLES
  %% =========================
  classDef person fill:#ffffff,stroke:#1f2937,stroke-width:2px,color:#111827
  classDef external fill:#d1fae5,stroke:#047857,stroke-width:2px,color:#064e3b
  classDef system fill:#e0f2fe,stroke:#0369a1,stroke-width:2px,color:#0c4a6e
  classDef compute fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#1e3a8a
  classDef integration fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d
  classDef storage fill:#bbf7d0,stroke:#166534,stroke-width:2px,color:#052e16
  classDef config fill:#fef3c7,stroke:#b45309,stroke-width:2px,color:#78350f
  classDef security fill:#fde68a,stroke:#a16207,stroke-width:2px,color:#713f12
  classDef state fill:#e5e7eb,stroke:#6b7280,stroke-width:2px,color:#111827
  classDef deny fill:#fee2e2,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d
  classDef error fill:#ffe4e6,stroke:#9f1239,stroke-width:2px,color:#881337

  class U person
  class TG,GAPI external
  class GSH storage
  class SYSBOX system
  class VERCEL,WH,BOT,SCENES,WIZ,PARSE,MW,ROUTER,Q1,BR,FINAL compute
  class SHEETS,JWT,KEYP,DOC,TAB,APP integration
  class ENV config
  class VSEC,ALLOW security
  class STATE state
  class REJ1,REJ2 deny
  class ERR error
```
