# 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:**
    ```bash
    mvn spring-boot:run
    ```
*   **Build JAR:**
    ```bash
    mvn clean package
    ```
*   **Run Tests:**
    ```bash
    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.