# rowdyslav/glitchme architecture

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

- Interactive diagram: https://gitdiagram.com/rowdyslav/glitchme
- Repository: https://github.com/rowdyslav/glitchme

## Overview

##### Project type and purpose
- This is a full-stack, modular game platform combining:
- A REST-API backend (FastAPI)
- A reactive Flet frontend (web/desktop)
- A Telegram client via Aiogram
- Players connect via the Flet UI or Telegram bot; both talk to the same FastAPI service which stores game state in a database.

##### File structure
- Top-level directories:
- api/ – contains FastAPI app (main.py, routers/, schemas/, db.py, misc/)
- app/ – Flet frontend (main.py, controls/, misc/)
- bot/ – Telegram bot (main.py, commands/, misc/)
- Configuration & environment: config.json, config.py, env.py
- Requirements.txt lists Python 3.13, FastAPI, Flet, Aiogram
- DB layer abstracted in api/db.py

##### README for additional insights
- Modular architecture: backend houses “mechanics,” clients only render & send user actions
- QR-based registration, real-time Flet updates
- Configurable rounds/questions in config.json

a. Main components
- FastAPI Backend
- Database (e.g., SQLite/Postgres via SQLAlchemy in api/db.py)
- Flet Frontend (app/)
- Telegram Bot (bot/)
- External Telegram API
- Configuration store (config.json)
b. Relationships & interactions
- Flet Frontend ↔ HTTP(S) ↔ FastAPI
- Telegram Bot ↔ Aiogram Polling/Webhook ↔ FastAPI
- FastAPI ↔ DB (CRUD of games/players/rounds)
- FastAPI ↔ config.json (load questions at startup)
- FastAPI generates QR codes → Flet bot displays them → Clients scan → frontend/bot call PATCH /game/connect/{id}
c. Architectural patterns & principles
- Layered: Presentation (app/, bot/) → API layer → Persistence layer
- Modular: routers/schemas/handlers → easily extend with new endpoints or game mechanics
- Reactive UI: Flet uses event handlers & long-poll updates (or WebSockets/SSE) to reflect state changes
d. Key technologies/frameworks
- FastAPI (api/main.py)
- Flet UI (app/main.py, app/controls/)
- Aiogram (bot/main.py, bot/commands/)
- SQLAlchemy or equivalent in api/db.py
- config.json for dynamic rounds/questions

##### Detailed capture of essential elements
- Break Backend into components:
- Routers (api/routers/game.py, player.py)
- Schema definitions (models, params, errors)
- misc utilities (QR code, by_bot, by_api handlers)
- DB module
- Frontend modules mapping:
- Controls (game.py, lobby.py, index.py)
- misc helpers (by_api calls)
- Bot modules:
- Command handlers (advanced, base)
- misc (keyboards, messages, by_api)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Flet Frontend"
        direction TB
        FE_Main["app/main.py"]:::frontend
        FE_Index["controls/index.py"]:::frontend
        FE_Game["controls/game.py"]:::frontend
        FE_Lobby["controls/lobby.py"]:::frontend
        FE_ByAPI["misc/by_api.py"]:::frontend
    end

    %% Backend Layer
    subgraph "FastAPI Backend"
        direction TB
        BE_Main["api/main.py"]:::backend

        subgraph "Routers"
            direction TB
            BE_RouterGame["game.py"]:::backend
            BE_RouterPlayer["player.py"]:::backend
        end

        subgraph "Schemas"
            direction TB
            BE_Models["models.py"]:::backend
            BE_Params["params.py"]:::backend
            BE_Errors["errors.py"]:::backend
        end

        subgraph "Utilities"
            direction TB
            BE_QR["qr.py"]:::backend
            BE_ByBot["by_bot.py"]:::backend
            BE_Handlers["handlers.py"]:::backend
        end

        BE_DBModule["api/db.py"]:::database
        BE_ConfigJson["config.json"]:::backend
        BE_ConfigPy["config.py"]:::backend
        BE_EnvPy["env.py"]:::backend
    end

    %% Bot Layer
    subgraph "Telegram Bot"
        direction TB
        BOT_Main["bot/main.py"]:::bot
        BOT_Base["commands/base.py"]:::bot
        BOT_Advanced["commands/advanced.py"]:::bot
        BOT_ByAPI["misc/by_api.py"]:::bot
        BOT_Keyboards["misc/keyboards.py"]:::bot
        BOT_Messages["misc/messages.py"]:::bot
    end

    %% External Services
    TEL_API["Telegram API"]:::external

    %% Database
    DB["Database"]:::database

    %% Connections
    FE_Main -->|"HTTP(S) requests"| BE_Main
    BOT_Main -->|"HTTP(S) requests"| BE_Main
    BE_Main -->|"CRUD operations"| DB
    BE_Main -->|"load config"| BE_ConfigJson
    BE_Main -->|"load config"| BE_ConfigPy
    BE_Main -->|"load env"| BE_EnvPy
    BOT_Main -->|"polling/webhook"| TEL_API

    %% Click events
    click FE_Main "https://github.com/rowdyslav/glitchme/blob/main/app/main.py"
    click FE_Index "https://github.com/rowdyslav/glitchme/blob/main/app/controls/index.py"
    click FE_Game "https://github.com/rowdyslav/glitchme/blob/main/app/controls/game.py"
    click FE_Lobby "https://github.com/rowdyslav/glitchme/blob/main/app/controls/lobby.py"
    click FE_ByAPI "https://github.com/rowdyslav/glitchme/blob/main/app/misc/by_api.py"
    click BE_Main "https://github.com/rowdyslav/glitchme/blob/main/api/main.py"
    click BE_RouterGame "https://github.com/rowdyslav/glitchme/blob/main/api/routers/game.py"
    click BE_RouterPlayer "https://github.com/rowdyslav/glitchme/blob/main/api/routers/player.py"
    click BE_Models "https://github.com/rowdyslav/glitchme/blob/main/api/schemas/models.py"
    click BE_Params "https://github.com/rowdyslav/glitchme/blob/main/api/schemas/params.py"
    click BE_Errors "https://github.com/rowdyslav/glitchme/blob/main/api/schemas/errors.py"
    click BE_QR "https://github.com/rowdyslav/glitchme/blob/main/api/misc/qr.py"
    click BE_ByBot "https://github.com/rowdyslav/glitchme/blob/main/api/misc/by_bot.py"
    click BE_Handlers "https://github.com/rowdyslav/glitchme/blob/main/api/misc/handlers.py"
    click BE_DBModule "https://github.com/rowdyslav/glitchme/blob/main/api/db.py"
    click BOT_Main "https://github.com/rowdyslav/glitchme/blob/main/bot/main.py"
    click BOT_Base "https://github.com/rowdyslav/glitchme/blob/main/bot/commands/base.py"
    click BOT_Advanced "https://github.com/rowdyslav/glitchme/blob/main/bot/commands/advanced.py"
    click BOT_ByAPI "https://github.com/rowdyslav/glitchme/blob/main/bot/misc/by_api.py"
    click BOT_Keyboards "https://github.com/rowdyslav/glitchme/blob/main/bot/misc/keyboards.py"
    click BOT_Messages "https://github.com/rowdyslav/glitchme/blob/main/bot/misc/messages.py"

    %% Styles
    classDef frontend fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef bot fill:#90EE90,stroke:#333,stroke-width:1px
    classDef database fill:#F5DEB3,stroke:#333,stroke-width:1px,shape:cylinder
    classDef external fill:#FFEFD5,stroke:#333,stroke-width:1px,shape:cloud
```
