# dhinesh-dhinesh/hamster-calci-client architecture

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

- Interactive diagram: https://gitdiagram.com/dhinesh-dhinesh/hamster-calci-client
- Repository: https://github.com/dhinesh-dhinesh/hamster-calci-client

## Overview

Hamster Calci is a Telegram mini-app for tracking Hamster Kombat card levels and comparing their profit per hour, price, and return on investment. Users enter or update card levels, then review ranked cards and statistics; card values are estimated with exponential growth calculations. The main flow spans routed screens, card data state, calculation helpers, and Firestore persistence, with Firebase Analytics providing event and screen tracking. The README also describes Telegram integration. Some provider wiring and the statistics implementation were not excerpted, so their internal links are not inferred.

Main entry points: [`src/components/cardDrawerContext.tsx`](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/components/cardDrawerContext.tsx) (Level Drawer), [`src/App.tsx`](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/App.tsx) (Route Shell), [`src/pages/topCards.tsx`](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/pages/topCards.tsx) (Top Cards), [`src/components/cardDataContext.tsx`](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/components/cardDataContext.tsx) (Card Data Context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_screens["App Screens"]
  node_app["Route Shell<br/>[App.tsx]"]
  node_entry["Enter Levels<br/>[enterData.tsx]"]
  node_rankings["Top Cards<br/>[topCards.tsx]"]
  node_stats["Statistics<br/>[stats.tsx]"]
end

subgraph group_cards["Card Analysis"]
  node_cardview["Card View<br/>[card.tsx]"]
  node_catalog["Card Catalog<br/>[cardData.ts]"]
  node_combine["Card Valuation<br/>[combineCards.ts]"]
  node_format["Number Formatting<br/>[numberFormat.ts]"]
  node_clean["Category Cleanup<br/>[cleanString.ts]"]
end

subgraph group_state["User And Card State"]
  node_userstate["User Context"]
  node_cardstate["Card Data Context"]
  node_drawer["Level Drawer"]
end

subgraph group_services["Firebase Services"]
  node_firestore["Card Persistence"]
  node_firebase["Firebase Setup<br/>[firebase.ts]"]
  node_cloudstore[("Cloud Firestore")]
  node_analytics["Firebase Analytics"]
end

node_player(("Telegram Player"))

node_player -->|"uses"| node_app
node_app -->|"routes to"| node_entry
node_app -->|"routes to"| node_rankings
node_app -->|"routes to"| node_stats
node_app -->|"reads user"| node_userstate
node_app -->|"logs screens"| node_analytics
node_entry -->|"uses catalog"| node_catalog
node_entry -->|"combines cards"| node_combine
node_entry -->|"reads card state"| node_cardstate
node_entry -->|"opens drawer"| node_drawer
node_rankings -->|"reads card state"| node_cardstate
node_rankings -->|"uses catalog"| node_catalog
node_rankings -->|"combines and ranks"| node_combine
node_rankings -->|"opens drawer"| node_drawer
node_rankings -->|"renders cards"| node_cardview
node_stats -->|"reads card state"| node_cardstate
node_stats -->|"uses catalog"| node_catalog
node_stats -->|"combines cards"| node_combine
node_stats -->|"formats values"| node_format
node_combine -->|"uses card values"| node_catalog
node_cardstate -->|"reads user"| node_userstate
node_cardstate -->|"fetches card data"| node_firestore
node_drawer -->|"updates local data"| node_cardstate
node_drawer -->|"reads user"| node_userstate
node_drawer -->|"updates card"| node_firestore
node_drawer -->|"cleans category"| node_clean
node_drawer -->|"formats values"| node_format
node_firestore -->|"uses database config"| node_firebase
node_firebase -->|"initializes"| node_cloudstore
node_firebase -->|"initializes"| node_analytics
node_player -.->|"Telegram identity integration"| node_firebase

click node_app "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/App.tsx"
click node_entry "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/pages/enterData.tsx"
click node_rankings "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/pages/topCards.tsx"
click node_stats "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/pages/stats.tsx"
click node_cardview "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/components/card.tsx"
click node_catalog "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/data/cardData.ts"
click node_combine "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/util/combineCards.ts"
click node_format "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/util/numberFormat.ts"
click node_clean "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/util/cleanString.ts"
click node_userstate "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/components/userDataContext.tsx"
click node_cardstate "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/components/cardDataContext.tsx"
click node_drawer "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/components/cardDrawerContext.tsx"
click node_firestore "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/util/FirestoreService.ts"
click node_firebase "https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/firebase.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_app,node_entry,node_rankings,node_stats toneBlue
class node_cardview,node_catalog,node_combine,node_format,node_clean toneAmber
class node_userstate,node_cardstate,node_drawer toneMint
class node_firestore,node_firebase,node_cloudstore,node_analytics toneRose
class node_player toneIndigo
```

## Components

### App Screens

- [Route Shell](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/App.tsx): `src/App.tsx`
- [Enter Levels](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/pages/enterData.tsx): `src/pages/enterData.tsx`
- [Top Cards](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/pages/topCards.tsx): `src/pages/topCards.tsx`
- [Statistics](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/pages/stats.tsx): `src/pages/stats.tsx`

### Card Analysis

- [Card View](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/components/card.tsx): `src/components/card.tsx`
- [Card Catalog](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/data/cardData.ts): `src/data/cardData.ts`
- [Card Valuation](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/util/combineCards.ts): `src/util/combineCards.ts`
- [Number Formatting](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/util/numberFormat.ts): `src/util/numberFormat.ts`
- [Category Cleanup](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/util/cleanString.ts): `src/util/cleanString.ts`

### User And Card State

- [User Context](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/components/userDataContext.tsx): `src/components/userDataContext.tsx`
- [Card Data Context](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/components/cardDataContext.tsx): `src/components/cardDataContext.tsx`
- [Level Drawer](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/components/cardDrawerContext.tsx): `src/components/cardDrawerContext.tsx`

### Firebase Services

- [Card Persistence](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/util/FirestoreService.ts): `src/util/FirestoreService.ts`
- [Firebase Setup](https://github.com/dhinesh-dhinesh/hamster-calci-client/blob/main/src/firebase.ts): `src/firebase.ts`
- **Cloud Firestore**
- **Firebase Analytics**

### Other components

- **Telegram Player**

## Connections

- Telegram Player → Route Shell: uses (evidence: `README.md`)
- Route Shell → Enter Levels: routes to (evidence: `src/App.tsx`)
- Route Shell → Top Cards: routes to (evidence: `src/App.tsx`)
- Route Shell → Statistics: routes to (evidence: `src/App.tsx`)
- Route Shell → User Context: reads user (evidence: `src/App.tsx`)
- Route Shell → Firebase Analytics: logs screens (evidence: `src/App.tsx`)
- Enter Levels → Card Catalog: uses catalog (evidence: `src/pages/enterData.tsx`)
- Enter Levels → Card Valuation: combines cards (evidence: `src/pages/enterData.tsx`)
- Enter Levels → Card Data Context: reads card state (evidence: `src/pages/enterData.tsx`)
- Enter Levels → Level Drawer: opens drawer (evidence: `src/pages/enterData.tsx`)
- Top Cards → Card Data Context: reads card state (evidence: `src/pages/topCards.tsx`)
- Top Cards → Card Catalog: uses catalog (evidence: `src/pages/topCards.tsx`)
- Top Cards → Card Valuation: combines and ranks (evidence: `src/pages/topCards.tsx`)
- Top Cards → Level Drawer: opens drawer (evidence: `src/pages/topCards.tsx`)
- Top Cards → Card View: renders cards (evidence: `src/pages/topCards.tsx`)
- Statistics → Card Data Context: reads card state (evidence: `src/pages/stats.tsx`)
- Statistics → Card Catalog: uses catalog (evidence: `src/pages/stats.tsx`)
- Statistics → Card Valuation: combines cards (evidence: `src/pages/stats.tsx`)
- Statistics → Number Formatting: formats values (evidence: `src/pages/stats.tsx`)
- Card Valuation → Card Catalog: uses card values (evidence: `src/util/combineCards.ts`)
- Card Data Context → User Context: reads user (evidence: `src/components/cardDataContext.tsx`)
- Card Data Context → Card Persistence: fetches card data (evidence: `src/components/cardDataContext.tsx`)
- Level Drawer → Card Data Context: updates local data (evidence: `src/components/cardDrawerContext.tsx`)
- Level Drawer → User Context: reads user (evidence: `src/components/cardDrawerContext.tsx`)
- Level Drawer → Card Persistence: updates card (evidence: `src/components/cardDrawerContext.tsx`)
- Level Drawer → Category Cleanup: cleans category (evidence: `src/components/cardDrawerContext.tsx`)
- Level Drawer → Number Formatting: formats values (evidence: `src/components/cardDrawerContext.tsx`)
- Card Persistence → Firebase Setup: uses database config (evidence: `src/util/FirestoreService.ts`)
- Firebase Setup → Cloud Firestore: initializes (evidence: `src/firebase.ts`)
- Firebase Setup → Firebase Analytics: initializes (evidence: `src/firebase.ts`)
- Telegram Player → Firebase Setup: Telegram identity integration (evidence: `README.md`)
