# alanshamov/piggee-telegram-mini-app architecture

> Architecture diagram of the GitHub repository alanshamov/piggee-telegram-mini-app, 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/alanshamov/piggee-telegram-mini-app
- Repository: https://github.com/alanshamov/piggee-telegram-mini-app

## Overview

Piggee is a savings-goal tracker available as a standalone web app or a Telegram Mini App. The main user flow is to open the app, create a grid manually or from a template, mark deposited amounts, and view totals and progress. The Telegram bot provides an alternate entry point through a /start message and Web App button. The README documents the app’s storage and customization capabilities; the HTML implementation was not sampled, so those internal relationships are based on documentation rather than inspected source.

Main entry points: [`kopilka.html`](https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html) (Savings app), [`bot.py`](https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/bot.py) (Start handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram_entry["Telegram entry"]
  node_webhook_receiver["Webhook receiver<br/>[bot.py]"]
  node_start_handler["Start handler<br/>[bot.py]"]
end

subgraph group_savings_app["Savings app"]
  node_web_app["Savings app<br/>[kopilka.html]"]
  node_grid_setup["Grid setup<br/>[kopilka.html]"]
  node_templates["Savings templates<br/>[kopilka.html]"]
  node_cell_tracking["Cell tracking<br/>[kopilka.html]"]
  node_progress["Totals and progress<br/>[kopilka.html]"]
  node_appearance["Appearance settings<br/>[kopilka.html]"]
end

subgraph group_persistence["Persistence and preferences"]
  node_local_storage[("Browser localStorage")]
  node_cloud_storage[("Telegram CloudStorage")]
end

node_user(("User"))
node_telegram["Telegram"]

node_telegram -->|"posts updates"| node_webhook_receiver
node_webhook_receiver -->|"dispatches updates"| node_start_handler
node_user -->|"sends /start"| node_telegram
node_start_handler -->|"sends launch button"| node_user
node_user -->|"opens app"| node_web_app
node_start_handler -->|"links to app"| node_web_app
node_user -->|"sets grid"| node_grid_setup
node_user -->|"chooses template"| node_templates
node_grid_setup -->|"provides cells"| node_cell_tracking
node_templates -->|"provides grid"| node_cell_tracking
node_user -->|"marks deposits"| node_cell_tracking
node_cell_tracking -->|"updates totals"| node_progress
node_user -->|"configures display"| node_appearance
node_web_app -->|"stores data"| node_local_storage
node_web_app -->|"syncs in Telegram"| node_cloud_storage

click node_webhook_receiver "https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/bot.py"
click node_start_handler "https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/bot.py"
click node_web_app "https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html"
click node_grid_setup "https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html"
click node_templates "https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html"
click node_cell_tracking "https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html"
click node_progress "https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html"
click node_appearance "https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html"

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_webhook_receiver,node_start_handler,node_user toneBlue
class node_web_app,node_grid_setup,node_templates,node_cell_tracking,node_progress,node_appearance toneAmber
class node_local_storage,node_cloud_storage toneMint
class node_telegram toneIndigo
```

## Components

### Telegram entry

- [Webhook receiver](https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/bot.py): `bot.py`
- [Start handler](https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/bot.py): `bot.py`

### Savings app

- [Savings app](https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html): `kopilka.html`
- [Grid setup](https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html): `kopilka.html`
- [Savings templates](https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html): `kopilka.html`
- [Cell tracking](https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html): `kopilka.html`
- [Totals and progress](https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html): `kopilka.html`
- [Appearance settings](https://github.com/alanshamov/piggee-telegram-mini-app/blob/main/kopilka.html): `kopilka.html`

### Persistence and preferences

- **Browser localStorage**
- **Telegram CloudStorage**

### Other components

- **User**
- **Telegram**

## Connections

- Telegram → Webhook receiver: posts updates (evidence: `README.md`)
- Webhook receiver → Start handler: dispatches updates (evidence: `bot.py`)
- User → Telegram: sends /start (evidence: `README.md`)
- Start handler → User: sends launch button (evidence: `bot.py`)
- User → Savings app: opens app (evidence: `README.md`)
- Start handler → Savings app: links to app (evidence: `bot.py`)
- User → Grid setup: sets grid (evidence: `README.md`)
- User → Savings templates: chooses template (evidence: `README.md`)
- Grid setup → Cell tracking: provides cells (evidence: `README.md`)
- Savings templates → Cell tracking: provides grid (evidence: `README.md`)
- User → Cell tracking: marks deposits (evidence: `README.md`)
- Cell tracking → Totals and progress: updates totals (evidence: `README.md`)
- User → Appearance settings: configures display (evidence: `README.md`)
- Savings app → Browser localStorage: stores data (evidence: `README.md`)
- Savings app → Telegram CloudStorage: syncs in Telegram (evidence: `README.md`)
