# tbeidlershenk/hotround architecture

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

- Interactive diagram: https://gitdiagram.com/tbeidlershenk/hotround
- Repository: https://github.com/tbeidlershenk/hotround

## Overview

##### Project type and purpose
- HotRound is a full-stack, data-driven application with two primary user-facing interfaces:
- A ReactJS single-page web app served by a Flask backend
- A Discord bot built with Disnake
- It scrapes and aggregates PDGA tournament data, stores it in a local SQLite database, then exposes rating-calculation endpoints to both the website and the bot.

##### File structure
- Top-level:
- Dockerfile.web, Dockerfile.bot, docker-compose.yml, heroku.yml → containerized deployment
- site/ → React frontend (package.json, src/, public/)
- src/ → Flask server (server.py), bot (bot.py), extensions (exts/), models/, utility modules (util/), scraping scripts (scripts/), requirements.txt
- Patterns:
- MVC-style models in src/models/
- Separate “scraper” scripts for data ingestion (src/scripts/)
- Flask app and Discord bot live in the same codebase, likely sharing models and utilities
- SQLite via util/database.py

##### README for additional insights
- Technologies: Python, Flask, React, Selenium, SQLite, Docker, Heroku
- Data flow: scrape → SQLite → rating algorithm → serve via API
- Two deployment targets: web service and bot service

##### Main components & interactions
a. Components
1. Web Client (Browser)
2. ReactJS App (site/src)
3. Flask Web Server (src/server.py + exts/* + models/* + util/*)
4. Discord Bot Service (src/bot.py + exts/*)
5. Scraper Service (src/scripts/*.py using Selenium)
6. SQLite Database (data store)
7. External PDGALive Website (data source)
8. Hosting/Orchestration (Docker, docker-compose, Heroku)
b. Relationships & data flows
- Browser → HTTP → Flask server → queries SQLite → HTTP response → Browser
- Discord user → Discord API → Bot service → internal commands → queries SQLite → responds via Discord API
- Scraper service (scheduled or manual) → Selenium → PDGALive → writes new records into SQLite
- Docker-compose orchestrates three containers: web, bot, (optionally a scheduler for scrapers)
c. Architectural patterns/Design principles
- Separation of concerns: frontend vs. API layer vs. bot logic vs. scraper
- Shared domain model: src/models used by both web and bot services
- Single source of truth: SQLite database
- Containerized micro-services style (web vs. bot)
d. Key technologies
- React (site/src)
- Flask (src/server.py)
- Disnake (src/bot.py)
- Selenium (src/scripts/)
- SQLite (util/database.py)
- Docker & Heroku

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        PDGA["PDGALive Website"]:::external
        DiscordAPI["Discord API"]:::external
    end

    %% Client Zone
    subgraph "Client Zone"
        Browser["Web Browser"]:::frontend
        DiscordUser["Discord User"]:::frontend
    end

    %% Service Zone
    subgraph "Service Zone"
        subgraph "Web Service Container"
            ReactApp["ReactJS App"]:::frontend
            FlaskAPI["Flask API"]:::backend
        end
        subgraph "Bot Service Container"
            BotService["Disnake Bot"]:::backend
        end
        subgraph "Scraper Service Container"
            Scraper["Scraper Scripts"]:::backend
        end
    end

    %% Data Zone
    DB["SQLite Database"]:::data

    %% Hosting & Orchestration
    subgraph "Hosting & Orchestration"
        DockerWeb["Dockerfile.web"]:::orchestration
        DockerBot["Dockerfile.bot"]:::orchestration
        Compose["docker-compose.yml"]:::orchestration
        HerokuCfg["heroku.yml"]:::orchestration
    end

    %% Data Flows
    Browser -->|Loads SPA| ReactApp
    ReactApp -->|HTTP GET /ratings| FlaskAPI
    FlaskAPI -->|SQL Query| DB
    DB -->|Data| FlaskAPI
    FlaskAPI -->|HTTP Response| ReactApp

    DiscordUser -->|User Action| DiscordAPI
    DiscordAPI -->|Event| BotService
    BotService -->|SQL Query| DB
    DB -->|Data| BotService
    BotService -->|Response| DiscordAPI

    Scraper -->|Selenium Crawl| PDGA
    PDGA -->|HTML Data| Scraper
    Scraper -->|Insert Records| DB

    DockerWeb --> ReactApp
    Compose --> ReactApp
    Compose --> FlaskAPI
    DockerBot --> BotService
    Compose --> BotService
    Compose --> Scraper
    HerokuCfg --> ReactApp
    HerokuCfg --> FlaskAPI
    HerokuCfg --> BotService
    HerokuCfg --> Scraper

    %% Click Events
    click ReactApp "https://github.com/tbeidlershenk/hotround/tree/main/site/"
    click FlaskAPI "https://github.com/tbeidlershenk/hotround/blob/main/src/server.py"
    click BotService "https://github.com/tbeidlershenk/hotround/blob/main/src/bot.py"
    click Scraper "https://github.com/tbeidlershenk/hotround/tree/main/src/scripts/"
    click DB "https://github.com/tbeidlershenk/hotround/blob/main/src/util/database.py"
    click DockerWeb "https://github.com/tbeidlershenk/hotround/blob/main/Dockerfile.web"
    click DockerBot "https://github.com/tbeidlershenk/hotround/blob/main/Dockerfile.bot"
    click Compose "https://github.com/tbeidlershenk/hotround/blob/main/docker-compose.yml"
    click HerokuCfg "https://github.com/tbeidlershenk/hotround/blob/main/heroku.yml"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#333,stroke-width:1px;
    classDef backend fill:#c8e6c9,stroke:#333,stroke-width:1px;
    classDef data fill:#e1bee7,stroke:#333,stroke-width:1px;
    classDef external fill:#ffe0b2,stroke:#333,stroke-width:1px;
    classDef orchestration fill:#f0f4c3,stroke:#333,stroke-width:1px;
```
