# aglarus/grandstarsuz architecture

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

- Interactive diagram: https://gitdiagram.com/aglarus/grandstarsuz
- Repository: https://github.com/aglarus/grandstarsuz

## Overview

GrandStars is a Telegram-centered digital-goods commerce platform with web/Mini App administration, partner storefronts, payment monitoring, TON wallets, automated fulfillment, and AI-assisted support. The principal documented journey is customer purchase through Telegram or web, payment confirmation, digital delivery, and order notification; available excerpts show several service-to-database and wallet calls but not the main bot/web orchestration. Dashed links mark documented capabilities whose runtime wiring was not shown.

Main entry points: [`db.py`](https://github.com/aglarus/grandstarsuz/blob/main/db.py) (Persistence), [`notifications.py`](https://github.com/aglarus/grandstarsuz/blob/main/notifications.py) (Notifications), [`web.py`](https://github.com/aglarus/grandstarsuz/blob/main/web.py) (Web And Mini App), [`wallet_sync.py`](https://github.com/aglarus/grandstarsuz/blob/main/wallet_sync.py) (Wallet Sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["Customer Channels"]
  node_bot_shop["Bot Shop<br/>[main.py]"]
  node_web_panel["Web And Mini App<br/>[web.py]"]
end

subgraph group_commerce["Commerce Operations"]
  node_partner_store["Partner Bots<br/>[partner_bot.py]"]
  node_order_fulfillment["Order Fulfillment<br/>[main.py]"]
  node_gift_delivery["Gift Delivery<br/>[gift_sender.py]"]
end

subgraph group_payments["Payments And Wallets"]
  node_card_monitor["Card Monitoring<br/>[monitoring.py]"]
  node_ton_buyer["TON Purchases<br/>[ton_buyer.py]"]
  node_wallet_commands["Wallet Commands<br/>[wallet_handlers.py]"]
  node_wallet_sync["Wallet Sync<br/>[wallet_sync.py]"]
end

subgraph group_support["Support And Safety"]
  node_support_tickets["Support Tickets<br/>[support.py]"]
  node_ai_support["AI Support And Reports<br/>[support_ai.py]"]
  node_ai_bot["AI Assistant<br/>[ai_bot.py]"]
  node_forum_backup["Forum Backup<br/>[forum_backup.py]"]
  node_reports["Reports<br/>[reports.py]"]
end

subgraph group_platform["Platform Services"]
  node_notifications["Notifications<br/>[notifications.py]"]
  node_database[("Persistence<br/>[db.py]")]
end

node_customer(("Customer"))
node_operator(("Administrator"))
node_telegram{{"Telegram"}}
node_ton{{"TON And Fragment"}}
node_cardbots{{"Card Alert Bots"}}
node_ai_provider{{"AI Provider"}}

node_customer -.->|"shops"| node_bot_shop
node_customer -.->|"uses Mini App"| node_web_panel
node_bot_shop -.->|"serves via"| node_telegram
node_web_panel -.->|"uses persistence"| node_database
node_bot_shop -.->|"submits orders"| node_order_fulfillment
node_order_fulfillment -.->|"fulfills gifts"| node_gift_delivery
node_order_fulfillment -.->|"reports status"| node_notifications
node_partner_store -->|"reads partner records"| node_database
node_partner_store -->|"links to setup"| node_web_panel
node_cardbots -.->|"send payment alerts"| node_card_monitor
node_card_monitor -->|"records transactions"| node_database
node_card_monitor -->|"alerts on failure"| node_operator
node_ton_buyer -->|"queries purchases"| node_ton
node_wallet_commands -->|"validates wallets"| node_ton_buyer
node_wallet_commands -->|"notifies transfers"| node_notifications
node_wallet_sync -->|"syncs balances"| node_database
node_wallet_sync -->|"notifies deposits"| node_notifications
node_wallet_sync -->|"sends withdrawals"| node_ton_buyer
node_support_tickets -->|"reads ticket data"| node_database
node_support_tickets -->|"sends updates"| node_notifications
node_ai_support -->|"checks reports"| node_database
node_ai_support -.->|"requests AI analysis"| node_ai_provider
node_ai_bot -->|"reads AI settings"| node_database
node_forum_backup -->|"uses persistence"| node_database
node_reports -->|"reads report records"| node_database
node_operator -.->|"administers"| node_web_panel
node_notifications -.->|"delivers alerts"| node_telegram

click node_bot_shop "https://github.com/aglarus/grandstarsuz/blob/main/main.py"
click node_web_panel "https://github.com/aglarus/grandstarsuz/blob/main/web.py"
click node_partner_store "https://github.com/aglarus/grandstarsuz/blob/main/partner_bot.py"
click node_order_fulfillment "https://github.com/aglarus/grandstarsuz/blob/main/main.py"
click node_gift_delivery "https://github.com/aglarus/grandstarsuz/blob/main/gift_sender.py"
click node_card_monitor "https://github.com/aglarus/grandstarsuz/blob/main/monitoring.py"
click node_ton_buyer "https://github.com/aglarus/grandstarsuz/blob/main/ton_buyer.py"
click node_wallet_commands "https://github.com/aglarus/grandstarsuz/blob/main/wallet_handlers.py"
click node_wallet_sync "https://github.com/aglarus/grandstarsuz/blob/main/wallet_sync.py"
click node_support_tickets "https://github.com/aglarus/grandstarsuz/blob/main/support.py"
click node_ai_support "https://github.com/aglarus/grandstarsuz/blob/main/support_ai.py"
click node_ai_bot "https://github.com/aglarus/grandstarsuz/blob/main/ai_bot.py"
click node_forum_backup "https://github.com/aglarus/grandstarsuz/blob/main/forum_backup.py"
click node_reports "https://github.com/aglarus/grandstarsuz/blob/main/reports.py"
click node_notifications "https://github.com/aglarus/grandstarsuz/blob/main/notifications.py"
click node_database "https://github.com/aglarus/grandstarsuz/blob/main/db.py"

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_bot_shop,node_web_panel toneBlue
class node_partner_store,node_order_fulfillment,node_gift_delivery toneAmber
class node_card_monitor,node_ton_buyer,node_wallet_commands,node_wallet_sync toneMint
class node_support_tickets,node_ai_support,node_ai_bot,node_forum_backup,node_reports toneRose
class node_notifications,node_database,node_customer,node_operator,node_telegram,node_ton,node_cardbots,node_ai_provider toneIndigo
```

## Components

### Customer Channels

- [Bot Shop](https://github.com/aglarus/grandstarsuz/blob/main/main.py): `main.py`
- [Web And Mini App](https://github.com/aglarus/grandstarsuz/blob/main/web.py): `web.py`

### Commerce Operations

- [Partner Bots](https://github.com/aglarus/grandstarsuz/blob/main/partner_bot.py): `partner_bot.py`
- [Order Fulfillment](https://github.com/aglarus/grandstarsuz/blob/main/main.py): `main.py`
- [Gift Delivery](https://github.com/aglarus/grandstarsuz/blob/main/gift_sender.py): `gift_sender.py`

### Payments And Wallets

- [Card Monitoring](https://github.com/aglarus/grandstarsuz/blob/main/monitoring.py): `monitoring.py`
- [TON Purchases](https://github.com/aglarus/grandstarsuz/blob/main/ton_buyer.py): `ton_buyer.py`
- [Wallet Commands](https://github.com/aglarus/grandstarsuz/blob/main/wallet_handlers.py): `wallet_handlers.py`
- [Wallet Sync](https://github.com/aglarus/grandstarsuz/blob/main/wallet_sync.py): `wallet_sync.py`

### Support And Safety

- [Support Tickets](https://github.com/aglarus/grandstarsuz/blob/main/support.py): `support.py`
- [AI Support And Reports](https://github.com/aglarus/grandstarsuz/blob/main/support_ai.py): `support_ai.py`
- [AI Assistant](https://github.com/aglarus/grandstarsuz/blob/main/ai_bot.py): `ai_bot.py`
- [Forum Backup](https://github.com/aglarus/grandstarsuz/blob/main/forum_backup.py): `forum_backup.py`
- [Reports](https://github.com/aglarus/grandstarsuz/blob/main/reports.py): `reports.py`

### Platform Services

- [Notifications](https://github.com/aglarus/grandstarsuz/blob/main/notifications.py): `notifications.py`
- [Persistence](https://github.com/aglarus/grandstarsuz/blob/main/db.py): `db.py`

### Other components

- **Customer**
- **Administrator**
- **Telegram**
- **TON And Fragment**
- **Card Alert Bots**
- **AI Provider**

## Connections

- Customer → Bot Shop: shops (evidence: `README.md`)
- Customer → Web And Mini App: uses Mini App (evidence: `README.md`)
- Bot Shop → Telegram: serves via (evidence: `README.md`)
- Web And Mini App → Persistence: uses persistence (evidence: `README.md`)
- Bot Shop → Order Fulfillment: submits orders (evidence: `README.md`)
- Order Fulfillment → Gift Delivery: fulfills gifts (evidence: `README.md`)
- Order Fulfillment → Notifications: reports status (evidence: `README.md`)
- Partner Bots → Persistence: reads partner records (evidence: `partner_bot.py`)
- Partner Bots → Web And Mini App: links to setup (evidence: `partner_bot.py`)
- Card Alert Bots → Card Monitoring: send payment alerts (evidence: `README.md`)
- Card Monitoring → Persistence: records transactions (evidence: `monitoring.py`)
- Card Monitoring → Administrator: alerts on failure (evidence: `monitoring.py`)
- TON Purchases → TON And Fragment: queries purchases (evidence: `ton_buyer.py`)
- Wallet Commands → TON Purchases: validates wallets (evidence: `wallet_handlers.py`)
- Wallet Commands → Notifications: notifies transfers (evidence: `wallet_handlers.py`)
- Wallet Sync → Persistence: syncs balances (evidence: `wallet_sync.py`)
- Wallet Sync → Notifications: notifies deposits (evidence: `wallet_sync.py`)
- Wallet Sync → TON Purchases: sends withdrawals (evidence: `wallet_sync.py`)
- Support Tickets → Persistence: reads ticket data (evidence: `support.py`)
- Support Tickets → Notifications: sends updates (evidence: `support.py`)
- AI Support And Reports → Persistence: checks reports (evidence: `support_ai.py`)
- AI Support And Reports → AI Provider: requests AI analysis (evidence: `README.md`)
- AI Assistant → Persistence: reads AI settings (evidence: `ai_bot.py`)
- Forum Backup → Persistence: uses persistence (evidence: `forum_backup.py`)
- Reports → Persistence: reads report records (evidence: `reports.py`)
- Administrator → Web And Mini App: administers (evidence: `README.md`)
- Notifications → Telegram: delivers alerts (evidence: `README.md`)
