# yokkichan/stone_volodya_backend architecture

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

- Interactive diagram: https://gitdiagram.com/yokkichan/stone_volodya_backend
- Repository: https://github.com/yokkichan/stone_volodya_backend

## Overview

##### Project Type and Purpose
- This is the backend of a full‑stack Telegram/WebApp game (“Stone Volodya”) implemented in Node.js/TypeScript with Express.
- Responsibilities: user management, game logic, referrals, TON‑blockchain airdrops, real‑time updates via WebSocket, and Telegram Bot integration.

##### Main Components
- Telegram Bot (Telegraf)
‑ Handles `/start`, referral links, WebApp launch, authentication.
- Express API Server
‑ Routes layer (`/api/auth`, `/api/game`, `/api/user`, `/api/referral`, `/api/airdrop`, `/api/leaderboard`)
‑ Controllers layer (business logic for game, airdrop, referral, leaderboard)
‑ Middleware (authMiddleware for JWT validation)
- WebSocket (Socket.IO)
‑ Pushes real‑time events: leaderboard updates, balance changes
- Database (MongoDB via Mongoose)
‑ User collection (stores stones, energy, boosts, skins, referralCode, invitedFriends, telegramId)
- In‑Memory User Cache
‑ Periodically syncs with MongoDB, serves quick lookups
- TON Blockchain (via TON SDK)
‑ Processes `claimAirdrop` transactions
- Telegram WebApp (client)
‑ Calls Express endpoints, displays UI inside Telegram

##### Relationships and Data Flows
- Telegram Bot ↔ Express API
‑ Bot sends HTTP requests to authController, referralController
- Telegram WebApp ↔ Express API
‑ User actions (gameplay, wallet connect) call API routes
- Express API → MongoDB
‑ Controllers perform CRUD on User model
- Express API ↔ WebSocket
‑ On state changes (stones updated, leaderboard changed), API emits Socket.IO events to connected clients
- Express API → TON SDK
‑ airdropController invokes blockchain calls
- In‑Memory Cache ↔ MongoDB
‑ Periodic sync; controllers read cache for performance, write through to DB

##### Architectural Patterns and Design Principles
- Layered Architecture:
‑ Presentation: Telegram Bot + WebApp client
‑ API/Routing: Express routes
‑ Business Logic: Controllers
‑ Data Access: Mongoose models + cache
‑ External Integration: TON SDK, Socket.IO
- Separation of Concerns: routes → controllers → models
- Statelessness: JWT‑based auth; stateful user cache isolated
- Event‑Driven Updates: WebSocket for near‑real‑time feedback

##### Elements
- Notes on update intervals (cache sync every 60s) and real‑time channels (Socket.IO)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Telegram["Telegram"]:::external
    WebApp["Telegram WebApp Client"]:::external
    TONSDK["TON Blockchain (via TON SDK)"]:::external

    %% Services
    Bot["Telegram Bot (Telegraf)"]:::service
    ExpressAPI["Express API Server"]:::service
    WS["Socket.IO (WebSocket)"]:::service

    %% API Layer Components
    subgraph "Express API Layer"
        AuthMW["authMiddleware (JWT)"]:::service
        subgraph "Routes"
            AuthRoute["/api/auth"]:::service
            GameRoute["/api/game"]:::service
            UserRoute["/api/user"]:::service
            ReferralRoute["/api/referral"]:::service
            AirdropRoute["/api/airdrop"]:::service
            LeaderboardRoute["/api/leaderboard"]:::service
            EarnRoute["/api/earn"]:::service
        end
        subgraph "Controllers"
            AuthCtrl["Auth Controller"]:::service
            GameCtrl["Game Controller"]:::service
            UserCtrl["User Controller"]:::service
            ReferralCtrl["Referral Controller"]:::service
            AirdropCtrl["Airdrop Controller"]:::service
            LeaderboardCtrl["Leaderboard Controller"]:::service
            EarnCtrl["Earn Controller"]:::service
        end
        UserModel["User Model"]:::database
        Cache["In-Memory User Cache<br/>(sync every 60s)"]:::cache
        JWT["JWT Utils"]:::service
        ReferralCode["ReferralCode Util"]:::service
        TelegramAuth["Telegram Auth Helper"]:::service
        Logger["Logging Service"]:::service
    end

    %% Database
    Mongo["MongoDB"]:::database

    %% Data Flows
    Telegram -->|"/start, referral, WebApp launch"| Bot
    Bot -->|HTTP| ExpressAPI
    WebApp -->|HTTP| ExpressAPI

    ExpressAPI --> AuthMW
    AuthMW -->|validates JWT| AuthRoute

    AuthRoute --> AuthCtrl
    GameRoute --> GameCtrl
    UserRoute --> UserCtrl
    ReferralRoute --> ReferralCtrl
    AirdropRoute --> AirdropCtrl
    LeaderboardRoute --> LeaderboardCtrl
    EarnRoute --> EarnCtrl

    AuthCtrl -->|uses JWT| JWT
    ReferralCtrl -->|uses referralCode| ReferralCode
    AirdropCtrl -->|calls SDK| TONSDK

    AuthCtrl --> Cache
    GameCtrl --> Cache
    UserCtrl --> Cache
    ReferralCtrl --> Cache
    AirdropCtrl --> Cache
    LeaderboardCtrl --> Cache
    EarnCtrl --> Cache

    Cache <-->|CRUD| UserModel
    UserModel -->|persist| Mongo

    ExpressAPI -->|emit events| WS
    WS -->|WebSocket| WebApp

    %% Click Events
    click Bot "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/bot.ts"
    click ExpressAPI "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/server.ts"
    click AuthRoute "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/routes/auth.ts"
    click GameRoute "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/routes/game.ts"
    click UserRoute "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/routes/user.ts"
    click ReferralRoute "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/routes/referral.ts"
    click AirdropRoute "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/routes/airdrop.ts"
    click LeaderboardRoute "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/routes/leaderboard.ts"
    click EarnRoute "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/routes/earn.ts"
    click AuthCtrl "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/controllers/authController.ts"
    click GameCtrl "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/controllers/gameController.ts"
    click UserCtrl "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/controllers/userController.ts"
    click ReferralCtrl "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/controllers/referralController.ts"
    click AirdropCtrl "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/controllers/airdropController.ts"
    click LeaderboardCtrl "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/controllers/leaderboardController.ts"
    click EarnCtrl "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/controllers/earnController.ts"
    click AuthMW "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/middleware/authMiddleware.ts"
    click UserModel "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/models/User.ts"
    click Cache "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/utils/userUtils.ts"
    click JWT "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/utils/jwt.ts"
    click ReferralCode "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/utils/referralCode.ts"
    click TelegramAuth "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/utils/telegramAuth.ts"
    click Logger "https://github.com/yokkichan/stone_volodya_backend/blob/master/src/logger.ts"

    %% Styles
    classDef service fill:#E0F7FA,stroke:#0288D1,stroke-width:1px;
    classDef external fill:#FFE0B2,stroke:#EF6C00,stroke-width:1px;
    classDef database fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px;
    classDef cache fill:#FFECB3,stroke:#F9A825,stroke-width:1px;
```
