How marcelobvieira/pais-cansados-bot works
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.