How yokkichan/stone_volodya_backend works
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)