Hearts of Iron IV Multiplayer Community Tier List

A community-driven performance tier list and evaluation platform for Hearts of Iron IV multiplayer competitive players.

Built with React 19, TypeScript, and Vite, engineered for 100% static hosting on GitHub Pages, backed securely by Supabase (Auth, PostgreSQL Database, and Row Level Security).

---

Table of Contents

1. Core Features & Community Methodology
2. Architecture Overview
3. Anti-Self-Rating Security Enforcement
4. Supabase Setup & Database Schema
5. Row Level Security (RLS) Policies
6. Environment Variables
7. GitHub Repository & Pages Setup
8. Automated Deployment (GitHub Actions)
9. Local Development

---

1. Core Features & Community Methodology

The 6 Official Performance Categories

Players are evaluated across strictly six tactical and strategic competencies on a 1.0 to 10.0 scale:

• Micro: Micro-management speed, front-line split-second reactions, encirclement execution, and manual unit control.
• Macro: Industrial planning, production line efficiency, supply depot network logistics, and tech pacing.
• TeamWork: Coalition communication, coordination on combined air/land pushes, and frontline resource sharing.
• IQ: Game mechanic comprehension, combat width understanding, division doctrine synergy, and counter-build mastery.
• Initiative: Aggression timing, exploiting unexpected frontline breaches, and dictating battle momentum.
• Flexibility: Adaptability to unconventional opponent doctrines, salvage operations when encircled, and emergency pivots.

Official Tier Brackets

• Tier S (≥ 9.0): Elite vanguard commanders
• Tier A (≥ 8.0): Formidable strategic assets
• Tier B (≥ 7.0): Solid, dependable frontline combatants
• Tier C (≥ 6.0): Intermediate capability
• Tier D (≥ 5.0): Developing recruits
• Tier F (< 5.0): Sub-threshold performance
• Provisional Tier: 3 to 4 evaluations (designated with *)
• Insufficient Data: < 3 evaluations (tier masked until minimum statistical threshold is met)

---

2. Architecture Overview

+-------------------------------------------------------------------------+
|                  GitHub Pages (Static Hosting)                          |
|                                                                         |
|  +-------------------------------------------------------------------+  |
|  |             React 19 + TypeScript + Vite SPA                      |  |
|  |                                                                   |  |
|  |  * Interactive Tier List & Filters (Search, Tier, Role, Min Votes)|  |
|  |  * Evaluator Rating Interface with Dynamic Radar Chart           |  |
|  |  * Community Analytics & Category Champions                       |  |
|  |  * Command Administration Panel & Access Code Management         |  |
|  |  * Official Russian Methodology Modal                             |  |
|  |  * Zero Server-side /api routes (100% static client)              |  |
|  +-------------------------------------------------------------------+  |
|                                     |                                   |
|                      Supabase JS Client SDK                             |
|                 (Public anon key, no admin secrets)                     |
+-------------------------------------+-----------------------------------+
                                      |
                                      v HTTPS
+-------------------------------------------------------------------------+
|                       Supabase Cloud Backend                            |
|                                                                         |
|  * Supabase Auth: Session management & role-based authentication        |
|  * PostgreSQL Database: Tables for players, profiles, ratings, settings |
|  * Row Level Security (RLS): Enforced on all tables                     |
|  * PostgreSQL Triggers: Strictly prevents evaluators from rating self   |
+-------------------------------------------------------------------------+

---

3. Anti-Self-Rating Security Enforcement

The rule that an evaluator cannot rate themselves is enforced on two independent layers:

1. PostgreSQL Database Trigger (check_anti_self_rating): An explicit BEFORE INSERT OR UPDATE trigger on public.ratings. If the authenticated user's profile ID or nickname matches the target player's ID or nickname, PostgreSQL throws an exception (Methodology Violation: Evaluators are strictly prohibited from evaluating themselves.) and aborts the transaction immediately.
2. Row Level Security Policy (ratings): The WITH CHECK clause contains a subquery verifying that no profile linked to auth.uid() matches the player ID or nickname of the rating row being submitted.
3. Frontend Guard: The React UI automatically disables and hides self-rating options for authenticated evaluators.

---

4. Supabase Setup & Database Schema

Step 1: Create a Supabase Project

1. Visit supabase.com and create a free account.
2. Create a new project (e.g. hoi4-mp-tierlist).
3. Note your Project URL and Anon Public Key from Project Settings > API.

Step 2: Run the Database Schema

1. In your Supabase Dashboard, open the SQL Editor.
2. Copy the entire contents of supabase/schema.sql from this repository.
3. Click Run.

The script creates:

• public.players: Community players directory
• public.profiles: Evaluator and administrator profiles linked to auth.users
• public.evaluator_invites: Secure access-code management
• public.ratings: Rating entries with UNIQUE (evaluator_id, player_id) and scores constrained to 1.0–10.0
• public.activity_log: Audit trail for rating submissions
• public.app_settings: Configurable community name, tier thresholds, and evaluation quotas
• All triggers, security functions, and RLS policies

---

5. Row Level Security (RLS) Policies

All tables have RLS enabled (ALTER TABLE ... ENABLE ROW LEVEL SECURITY):

Table	Operation	Allowed Roles	Rule / Constraint
players	SELECT	Public	View all active players
players	INSERT / UPDATE / DELETE	Admin	public.is_admin() = true
profiles	SELECT	Public	View evaluator profiles
profiles	UPDATE	Self / Admin	auth.uid() = id OR public.is_admin()
profiles	DELETE	Admin	Only admins can delete profiles
evaluator_invites	ALL	Admin	Only admins can generate or view access codes
ratings	SELECT	Public	View ratings for statistical computation
ratings	INSERT / UPDATE	Evaluator	auth.uid() = evaluator_id AND non-self rating check
ratings	DELETE	Self / Admin	Evaluators can clear their vote; Admins can reset
activity_log	SELECT	Public	View community activity
activity_log	INSERT	Evaluator / Admin	Log rating changes
app_settings	SELECT	Public	Read thresholds & settings
app_settings	UPDATE	Admin	Only admins can update thresholds

---

6. Environment Variables

Create a .env file in the project root for local development (copy from .env.example):

# Supabase Project Credentials (from Supabase Dashboard -> Project Settings -> API)
VITE_SUPABASE_URL=https://your-project-ref.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Optional: Base path for GitHub Pages subfolder deployment (defaults to './')
VITE_BASE_PATH=./

Security Note: Never put Supabase service_role keys or administrator passwords in your frontend environment variables. Only the public anon key is needed; Supabase RLS enforces data security.

---

7. GitHub Repository & Pages Setup

1. Initialize Git & Push to GitHub:

   git init
   git add .
   git commit -m "feat: HOI4 MP Tier List static deployment ready"
   git branch -M main
   git remote add origin https://github.com/USERNAME/REPOSITORY.git
   git push -u origin main

2. Configure GitHub Secrets:

   • Go to your repository on GitHub.
   • Click Settings > Secrets and variables > Actions.
   • Click New repository secret:
     • VITE_SUPABASE_URL: Your project URL (e.g. https://xyz.supabase.co)
     • VITE_SUPABASE_ANON_KEY: Your project's anon public key

3. Enable GitHub Pages via GitHub Actions:

   • In your repository, click Settings > Pages.
   • Under Build and deployment > Source, select GitHub Actions.

---

8. Automated Deployment (GitHub Actions)

The repository includes .github/workflows/deploy.yml:

• Automatic Trigger: Any push to the main or master branch triggers the build.
• Manual Trigger: Can also be dispatched manually from the Actions tab.
• Vite Subpath Handling: Configures base: './' to guarantee that all assets, scripts, and CSS load correctly regardless of whether the site is hosted at https://USERNAME.github.io/REPOSITORY/ or a custom root domain.

---

9. Local Development

# 1. Install dependencies
npm install

# 2. Run the Vite development server
npm run dev

# 3. Build for production (outputs static bundle into dist/)
npm run build

# 4. Preview the static production build locally
npm run preview

Static Fallback Preview Mode

If VITE_SUPABASE_URL is not yet configured, the app will run in Static Preview Mode with pre-seeded sample data, allowing complete visual and interactive evaluation before connecting your live Supabase cloud database.