Mythistone Project Overview

MythiStone is an interactive World of Warcraft Mythic+ dashboard that provides tier lists, leaderboards, dungeon route finding and per-spec statistics for the current season. The site combines data from the Blizzard API, Raider.IO, Keystone.guru, and community sources to help players plan and optimize Mythic+ runs. The frontend is a static website (built with Jinja2 templates) that presents dashboards, tier lists, class guides, and a team route finder in a responsive Material Dashboard theme.

Purpose and Scope

This repository contains the source for Mythistone, including data processing scripts and page templates. The primary purpose is to aggregate Mythic+ performance data (dungeon performance, spec talent popularity, gear recommendations, etc.) and present it visually in charts and tables. Key features include Mythic+ overall statistics, tier lists, per-spec gear and talent information, and a “Route Finder” tool for finding keystone routes based on team composition. The scope is limited to static content so the site can be hosted on GitHub Pages. All heavy data processing is done offline before publishing.

Architecture Overview

• Static Site Generation: Pages are generated from Jinja2 templates using Python scripts. The build system pulls data from APIs and a MySQL database and applies it to templates to produce static output for hosting on GitHub Pages.

• Frontend:

  • The site layout is based on the Material Dashboard UI theme.
  • Charts and graphs are rendered client-side using Chart.js.
  • Client-side search and filtering enable interactive features without a backend server.
  • Interactive WoW data is driven by Wowhead tooltips.
  • Consent for cookies and tracking is managed with the open-source Klaro consent manager.
  • On PC, ads are optionally hosted using Google AdSense (when cookies have been consented to). Otherwise static images are used. There are no ads on mobile.

• Data sources:

  • Raider.IO API for highest keys and some static data.
  • Keystone.guru API for routes.
  • Raidbots for static data and the talent frame.
  • Blizzard’s Battle.net API for leaderboard, character and other game data.

• Backend:

  • MySQL Database
  • Static site hosting using GitHub Pages.
  • Data Collection docker container
  • Jinja2 page templates are rebuilt every other day by a set of Python scripts which also power different forms of data collection. See backend_scripts for details.

Local Setup:

To run the site locally, you need Python installed (tested with 3.13.3) any 3.x version should work.

Install required Python packages. See the individual workflows for an up-to-date list, then install them with:

pip install <PackageName>

To view the site directly in your browser, use Python's built-in web server. From the repository root run:

python -m http.server

Getting the collector to run

Prerequisites

• A MySQL database with the tables defined in backend_scripts/database.sql. This will at some point be included in the Docker container, but for historical reasons it is not currently. You must also set up periodic jobs to aggregate values. That setup is out of scope here.
• Four API clients (one per region) from Blizzard: https://community.developer.battle.net/access/clients. Follow Blizzard's getting-started guide if needed: https://community.developer.battle.net/documentation/guides/getting-started.
• A Raider.IO API client: https://raider.io/settings/apps.
• A Discord webhook for monitoring the Docker container. See Discord's webhook docs for how to set one up.
• Docker (or another container runtime that can run Docker containers) installed on your system.

Running the collector

1. Copy docker-compose.yml from the repository.

2. Copy .envexample and rename it to .env.

3. Fill in the .env values.

4. Run:

   docker compose up
   

This will populate your database with data collected from the Blizzard API.

Building Pages

Multiple pages are built by different Python scripts. See the build workflow to view all available pages: here.

Because building spec pages can take a while, the spec script can be started with flags to build a single spec for testing:

--debug True --spec=<Spec Id>

Automated social-media posts

In addition to the frontend, MythiStone includes automated social-media posts. The system builds a static image at 18:00 UTC (see .github/workflows/automatedSocialMediaPosts.yml). It feeds data for image generation to an LLM via OpenRouter to generate a text/tagline, then posts the result to Twitter, Discord, and Bluesky.