AliasApp/GEMINI.md

Project: TelegaApp (Alias Game WebApp)

Overview

This project is a Spring Boot backend application designed to serve as the host for a Telegram WebApp game, specifically "Alias". The application integrates with the Telegram Bot API to manage the bot interface and will serve the game logic and web resources.

Technology Stack

• Language: Java 17
• Framework: Spring Boot 3.2.5
• Build Tool: Maven
• Telegram Library: telegrambots-spring-boot-starter (6.9.7.1)
• Frontend (Planned): React, TypeScript, Vite (to be integrated into src/main/resources/static)

Architecture & Structure

The project follows a standard Maven and Spring Boot directory structure:

• src/main/java/com/example/telegaapp: Source code root.
  • TelegaAppApplication.java: Entry point.
  • bot/TelegramBot.java: Handles Telegram updates (Long Polling) and WebApp launching.
  • controller/: REST and potentially WebSocket controllers.
• src/main/resources: Configuration and static assets.
  • application.properties: Configuration for server port and Telegram credentials.
  • static/: Location for the built frontend application.

Building and Running

Prerequisites

• JDK 17+
• Maven

Commands

• Run Application:

  mvn spring-boot:run
  

• Build JAR:

  mvn clean package
  

• Run Tests:

  mvn test
  

Configuration

Configuration is managed in src/main/resources/application.properties. Key properties:

• server.port: Defaults to 8080.
• telegram.bot.username: The username of the bot.
• telegram.bot.token: The authentication token from BotFather.
• telegram.webapp.url: The HTTPS URL where the WebApp is hosted (required for the WebApp button).

Architecture & Design Principles

Extensibility & Scalability

• Interface-Driven Design: Core components (like Word providers, Game rules) must be defined by interfaces. This allows swapping implementations (e.g., switching from JSON files to a Database) without modifying the business logic.
• Loose Coupling:
  • The WebSocket Controller should act only as a router/adapter. It converts incoming messages to Service calls and Service events to outgoing messages. It should contain zero game logic.
  • The Game Service should not know about WebSocket implementation details.
• State Management: While currently In-Memory, the design must support migrating the GameState to an external store (Redis) in the future. Avoid relying on object identity (==) for game entities; use IDs.

Coding Standards & Best Practices

• Comments & Documentation:
  • Mandatory Javadoc: All public interfaces, classes, and complex methods must have Javadoc explaining what they do and how to use them.
  • "Why" over "What": Inline comments are required for complex algorithmic logic (e.g., score calculation, state transitions). Focus on explaining the intent and the reasoning behind the code, not just translating syntax into English.
• DTOs (Data Transfer Objects): Strict separation between Domain models (internal logic) and DTOs (API contracts). Never return a mutable entity directly to the client.
• Error Handling: Use global exception handlers (@ControllerAdvice / @MessageExceptionHandler). Failures should be graceful and informative to the user.
• Testing: Logic should be testable in isolation. Unit tests for the Game Engine are critical.

Current Status

• Basic Spring Boot application setup.
• Telegram Bot polling implemented (TelegramBot.java).
• /start command sends a button to open the Web App.
• Pending: WebSocket setup, Game logic service, Frontend implementation.