# jvsleal-dev/puma-bot architecture

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

- Interactive diagram: https://gitdiagram.com/jvsleal-dev/puma-bot
- Repository: https://github.com/jvsleal-dev/puma-bot

## Overview

Puma Bot is a Telegram-and-PIX subscription SaaS: operators configure bots, VIP groups, payment gateways and sales flows; buyers interact with a bot, pay by PIX, and receive VIP access. The main domain stages are bot-led plan selection and charge creation, payment confirmation and access fulfillment, then subscription expiry and renewal. The dashboard, finance, customer and remarketing areas provide operational oversight. Service and persistence layers sit behind the routes. The README describes the product at a high level; several route and integration implementations are listed in the tree but were not sampled, so their connections are not inferred.

Main entry points: [`src/lib/server/prisma.ts`](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/server/prisma.ts) (Prisma Store), [`src/lib/services/pix-service.ts`](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/services/pix-service.ts) (PIX Fulfillment), [`src/lib/services/telegram-service.ts`](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/services/telegram-service.ts) (Bot Funnel), [`src/lib/domain/repositories.ts`](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/domain/repositories.ts) (Domain Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator Console"]
  node_site["Landing and Auth<br/>[+page.svelte]"]
  node_dashboard["Dashboard Metrics<br/>[+page.server.ts]"]
  node_finance["Financial Ledger<br/>[+page.server.ts]"]
  node_admin["Platform Admin<br/>[+page.server.ts]"]
  node_clients["Customer Management"]
  node_bots["Bot Management"]
  node_groups["VIP Groups<br/>[+page.server.ts]"]
  node_flows["Sales Flows"]
  node_gateways["Gateway Settings"]
  node_remarketing["Remarketing<br/>[+page.server.ts]"]
end

subgraph group_api["Routes and Webhooks"]
  node_telegramhook["Telegram Webhook<br/>[+server.ts]"]
  node_pixhook["PIX Webhook<br/>[+server.ts]"]
  node_authapi["Auth Endpoints"]
end

subgraph group_domain["Subscription Services"]
  node_pixservice["PIX Fulfillment<br/>[pix-service.ts]"]
  node_telegramservice["Bot Funnel"]
  node_subscriptions["Subscription Lifecycle"]
end

subgraph group_infra["Persistence and Integrations"]
  node_repositories["Domain Repositories<br/>[repositories.ts]"]
  node_database[("Prisma Store<br/>[prisma.ts]")]
  node_pixgateway["PIX Providers<br/>[pix-gateway.ts]"]
  node_telegram["Telegram API<br/>[telegram.ts]"]
end

node_operator(("Operator"))

node_operator -->|"visits"| node_site
node_operator -->|"views metrics"| node_dashboard
node_dashboard -->|"queries sales and bots"| node_database
node_finance -->|"queries ledger"| node_database
node_admin -->|"queries and updates"| node_database
node_groups -->|"queries groups"| node_database
node_remarketing -->|"queries leads"| node_database
node_telegramhook -.->|"dispatches updates"| node_telegramservice
node_pixhook -->|"sends access messages"| node_telegram
node_telegramservice -->|"creates charges"| node_pixservice
node_telegramservice -->|"uses contracts"| node_repositories
node_pixservice -->|"uses contracts"| node_repositories
node_pixservice -->|"creates PIX charge"| node_pixgateway
node_pixservice -->|"delivers VIP access"| node_telegram
node_subscriptions -->|"evicts and renews"| node_telegramservice
node_subscriptions -->|"uses contracts"| node_repositories

click node_site "https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/%2Bpage.svelte"
click node_dashboard "https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/dashboard/%2Bpage.server.ts"
click node_finance "https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/financeiro/%2Bpage.server.ts"
click node_admin "https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/admin/%2Bpage.server.ts"
click node_clients "https://github.com/jvsleal-dev/puma-bot/tree/main/src/routes/clientes"
click node_bots "https://github.com/jvsleal-dev/puma-bot/tree/main/src/routes/robos"
click node_groups "https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/grupos/%2Bpage.server.ts"
click node_flows "https://github.com/jvsleal-dev/puma-bot/tree/main/src/routes/fluxos"
click node_gateways "https://github.com/jvsleal-dev/puma-bot/tree/main/src/routes/gateways"
click node_remarketing "https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/remarketing/%2Bpage.server.ts"
click node_telegramhook "https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/api/webhook/telegram/%5BbotId%5D/%2Bserver.ts"
click node_pixhook "https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/api/webhook/pix/%2Bserver.ts"
click node_authapi "https://github.com/jvsleal-dev/puma-bot/tree/main/src/routes/api/auth"
click node_pixservice "https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/services/pix-service.ts"
click node_telegramservice "https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/services/telegram-service.ts"
click node_subscriptions "https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/services/subscription-service.ts"
click node_repositories "https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/domain/repositories.ts"
click node_database "https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/server/prisma.ts"
click node_pixgateway "https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/server/pix-gateway.ts"
click node_telegram "https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/server/telegram.ts"

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_site,node_dashboard,node_finance,node_admin,node_clients,node_bots,node_groups,node_flows,node_gateways,node_remarketing toneBlue
class node_telegramhook,node_pixhook,node_authapi toneAmber
class node_pixservice,node_telegramservice,node_subscriptions toneMint
class node_repositories,node_database,node_pixgateway,node_telegram toneRose
class node_operator toneIndigo
```

## Components

### Operator Console

- [Landing and Auth](https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/%2Bpage.svelte): `src/routes/+page.svelte`
- [Dashboard Metrics](https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/dashboard/%2Bpage.server.ts): `src/routes/dashboard/+page.server.ts`
- [Financial Ledger](https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/financeiro/%2Bpage.server.ts): `src/routes/financeiro/+page.server.ts`
- [Platform Admin](https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/admin/%2Bpage.server.ts): `src/routes/admin/+page.server.ts`
- [Customer Management](https://github.com/jvsleal-dev/puma-bot/tree/main/src/routes/clientes): `src/routes/clientes`
- [Bot Management](https://github.com/jvsleal-dev/puma-bot/tree/main/src/routes/robos): `src/routes/robos`
- [VIP Groups](https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/grupos/%2Bpage.server.ts): `src/routes/grupos/+page.server.ts`
- [Sales Flows](https://github.com/jvsleal-dev/puma-bot/tree/main/src/routes/fluxos): `src/routes/fluxos`
- [Gateway Settings](https://github.com/jvsleal-dev/puma-bot/tree/main/src/routes/gateways): `src/routes/gateways`
- [Remarketing](https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/remarketing/%2Bpage.server.ts): `src/routes/remarketing/+page.server.ts`

### Routes and Webhooks

- [Telegram Webhook](https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/api/webhook/telegram/%5BbotId%5D/%2Bserver.ts): `src/routes/api/webhook/telegram/[botId]/+server.ts`
- [PIX Webhook](https://github.com/jvsleal-dev/puma-bot/blob/main/src/routes/api/webhook/pix/%2Bserver.ts): `src/routes/api/webhook/pix/+server.ts`
- [Auth Endpoints](https://github.com/jvsleal-dev/puma-bot/tree/main/src/routes/api/auth): `src/routes/api/auth`

### Subscription Services

- [PIX Fulfillment](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/services/pix-service.ts): `src/lib/services/pix-service.ts`
- [Bot Funnel](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/services/telegram-service.ts): `src/lib/services/telegram-service.ts`
- [Subscription Lifecycle](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/services/subscription-service.ts): `src/lib/services/subscription-service.ts`

### Persistence and Integrations

- [Domain Repositories](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/domain/repositories.ts): `src/lib/domain/repositories.ts`
- [Prisma Store](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/server/prisma.ts): `src/lib/server/prisma.ts`
- [PIX Providers](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/server/pix-gateway.ts): `src/lib/server/pix-gateway.ts`
- [Telegram API](https://github.com/jvsleal-dev/puma-bot/blob/main/src/lib/server/telegram.ts): `src/lib/server/telegram.ts`

### Other components

- **Operator**

## Connections

- Operator → Landing and Auth: visits (evidence: `README.md`)
- Operator → Dashboard Metrics: views metrics (evidence: `README.md`)
- Dashboard Metrics → Prisma Store: queries sales and bots (evidence: `src/routes/dashboard/+page.server.ts`)
- Financial Ledger → Prisma Store: queries ledger (evidence: `src/routes/financeiro/+page.server.ts`)
- Platform Admin → Prisma Store: queries and updates (evidence: `src/routes/admin/+page.server.ts`)
- VIP Groups → Prisma Store: queries groups (evidence: `src/routes/grupos/+page.server.ts`)
- Remarketing → Prisma Store: queries leads (evidence: `src/routes/remarketing/+page.server.ts`)
- Telegram Webhook → Bot Funnel: dispatches updates
- PIX Webhook → Telegram API: sends access messages (evidence: `src/routes/api/webhook/pix/+server.ts`)
- Bot Funnel → PIX Fulfillment: creates charges (evidence: `src/lib/services/telegram-service.ts`)
- Bot Funnel → Domain Repositories: uses contracts (evidence: `src/lib/services/telegram-service.ts`)
- PIX Fulfillment → Domain Repositories: uses contracts (evidence: `src/lib/services/pix-service.ts`)
- PIX Fulfillment → PIX Providers: creates PIX charge (evidence: `src/lib/services/pix-service.ts`)
- PIX Fulfillment → Telegram API: delivers VIP access (evidence: `src/lib/services/pix-service.ts`)
- Subscription Lifecycle → Bot Funnel: evicts and renews (evidence: `src/lib/services/subscription-service.ts`)
- Subscription Lifecycle → Domain Repositories: uses contracts (evidence: `src/lib/services/subscription-service.ts`)