# manu6373/tgshorturl architecture

> Architecture diagram of the GitHub repository manu6373/tgshorturl, 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/manu6373/tgshorturl
- Repository: https://github.com/manu6373/tgshorturl

## Overview

TGShortUrl is a Telegram Mini App URL shortener with rewarded ads and referral commissions. The visible backend workflow validates a Telegram session and link, checks configured ad completion and abuse limits, then records clicks and eligible earnings. Admin APIs manage settings, users and withdrawals; other endpoints provide referral details, notifications and Telegram broadcasts. The HTML files likely provide the app surfaces, but their behavior is not evidenced here, so their connections are omitted.

Main entry points: [`api/reward.js`](https://github.com/manu6373/tgshorturl/blob/main/api/reward.js) (Reward handler), [`admin.html`](https://github.com/manu6373/tgshorturl/blob/main/admin.html) (Admin interface), [`api/broadcast.js`](https://github.com/manu6373/tgshorturl/blob/main/api/broadcast.js) (Broadcast API), [`index.html`](https://github.com/manu6373/tgshorturl/blob/main/index.html) (Mini App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["App surfaces"]
  node_app["Mini App<br/>[index.html]"]
  node_admin_ui["Admin interface<br/>[admin.html]"]
end

subgraph group_rewards["Reward workflow"]
  node_reward_api["Reward handler<br/>[reward.js]"]
  node_telegram_auth["Telegram validation<br/>[reward.js]"]
  node_ad_checks["Ad and abuse checks<br/>[reward.js]"]
  node_reward_ledger["Clicks and earnings<br/>[reward.js]"]
end

subgraph group_referrals["Referral features"]
  node_referral_process["Referral notification"]
  node_referral_names["Referral names<br/>[referral_names.js]"]
end

subgraph group_admin["Administration"]
  node_admin_api["Admin API<br/>[admin.js]"]
  node_broadcast_api["Broadcast API<br/>[broadcast.js]"]
end

node_user(("Mini App user"))
node_supabase[("Supabase")]
node_monetag["Reward ad providers"]
node_telegram_bot["Telegram Bot API"]

node_user -->|"uses"| node_app
node_user -->|"uses"| node_admin_ui
node_app -.->|"requests"| node_reward_api
node_reward_api -->|"validates"| node_telegram_auth
node_reward_api -->|"checks"| node_ad_checks
node_reward_api -->|"records"| node_reward_ledger
node_reward_api -->|"reads/writes"| node_supabase
node_ad_checks -->|"loads settings"| node_supabase
node_admin_ui -.->|"requests"| node_admin_api
node_admin_api -->|"authenticates and manages"| node_supabase
node_admin_ui -.->|"requests"| node_broadcast_api
node_broadcast_api -->|"loads recipients"| node_supabase
node_broadcast_api -->|"sends batches"| node_telegram_bot
node_referral_process -->|"notifies"| node_telegram_bot
node_referral_names -->|"loads referral profiles"| node_supabase
node_monetag -.->|"configured providers"| node_ad_checks

click node_app "https://github.com/manu6373/tgshorturl/blob/main/index.html"
click node_admin_ui "https://github.com/manu6373/tgshorturl/blob/main/admin.html"
click node_reward_api "https://github.com/manu6373/tgshorturl/blob/main/api/reward.js"
click node_telegram_auth "https://github.com/manu6373/tgshorturl/blob/main/api/reward.js"
click node_ad_checks "https://github.com/manu6373/tgshorturl/blob/main/api/reward.js"
click node_reward_ledger "https://github.com/manu6373/tgshorturl/blob/main/api/reward.js"
click node_admin_api "https://github.com/manu6373/tgshorturl/blob/main/api/admin.js"
click node_broadcast_api "https://github.com/manu6373/tgshorturl/blob/main/api/broadcast.js"
click node_referral_process "https://github.com/manu6373/tgshorturl/blob/main/api/process_referral.js"
click node_referral_names "https://github.com/manu6373/tgshorturl/blob/main/api/referral_names.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_app,node_admin_ui,node_user toneBlue
class node_reward_api,node_telegram_auth,node_ad_checks,node_reward_ledger,node_supabase toneAmber
class node_referral_process,node_referral_names,node_telegram_bot toneMint
class node_admin_api,node_broadcast_api toneRose
class node_monetag toneIndigo
```

## Components

### App surfaces

- [Mini App](https://github.com/manu6373/tgshorturl/blob/main/index.html): `index.html`
- [Admin interface](https://github.com/manu6373/tgshorturl/blob/main/admin.html): `admin.html`

### Reward workflow

- [Reward handler](https://github.com/manu6373/tgshorturl/blob/main/api/reward.js): `api/reward.js`
- [Telegram validation](https://github.com/manu6373/tgshorturl/blob/main/api/reward.js): `api/reward.js`
- [Ad and abuse checks](https://github.com/manu6373/tgshorturl/blob/main/api/reward.js): `api/reward.js`
- [Clicks and earnings](https://github.com/manu6373/tgshorturl/blob/main/api/reward.js): `api/reward.js`

### Referral features

- [Referral notification](https://github.com/manu6373/tgshorturl/blob/main/api/process_referral.js): `api/process_referral.js`
- [Referral names](https://github.com/manu6373/tgshorturl/blob/main/api/referral_names.js): `api/referral_names.js`

### Administration

- [Admin API](https://github.com/manu6373/tgshorturl/blob/main/api/admin.js): `api/admin.js`
- [Broadcast API](https://github.com/manu6373/tgshorturl/blob/main/api/broadcast.js): `api/broadcast.js`

### Other components

- **Mini App user**
- **Supabase**
- **Reward ad providers**
- **Telegram Bot API**

## Connections

- Mini App user → Mini App: uses
- Mini App user → Admin interface: uses
- Mini App → Reward handler: requests
- Reward handler → Telegram validation: validates (evidence: `api/reward.js`)
- Reward handler → Ad and abuse checks: checks (evidence: `api/reward.js`)
- Reward handler → Clicks and earnings: records (evidence: `api/reward.js`)
- Reward handler → Supabase: reads/writes (evidence: `api/reward.js`)
- Ad and abuse checks → Supabase: loads settings (evidence: `api/reward.js`)
- Admin interface → Admin API: requests
- Admin API → Supabase: authenticates and manages (evidence: `api/admin.js`)
- Admin interface → Broadcast API: requests
- Broadcast API → Supabase: loads recipients (evidence: `api/broadcast.js`)
- Broadcast API → Telegram Bot API: sends batches (evidence: `api/broadcast.js`)
- Referral notification → Telegram Bot API: notifies (evidence: `api/process_referral.js`)
- Referral names → Supabase: loads referral profiles (evidence: `api/referral_names.js`)
- Reward ad providers → Ad and abuse checks: configured providers