wip

docs/concept/RACING.md

@@ -0,0 +1,250 @@
+# GridPilot Race Management  
+*A unified system for running modern iRacing leagues with team formats, automated series structures, and clean penalty handling.*
+
+---
+
+# 1. Overview
+
+GridPilot Race Management defines **how racing works on the platform**,  
+independent of league size or community style.
+
+It consists of three pillars:
+
+1. **Team Leagues** — real constructors-style multi-driver competitions  
+2. **Automated Leagues** — structured series (e.g., F1-style) that GridPilot can mirror  
+3. **Penalty & Protest System** — clean dispute resolution without Discord chaos  
+
+GridPilot's goal is to make league racing **consistent, fair, and meaningful**,  
+without forcing admins into complexity or drivers into mandatory social interaction.
+
+---
+
+# 2. Team Leagues (Constructors Format)
+
+Most iRacing leagues treat teams as cosmetic.  
+GridPilot treats them as **primary competition units**, like real motorsport.
+
+## 2.1 Team Structure
+
+A team has:
+- Team profile (logo, colors, description)  
+- Captain / co-captains  
+- Roster of drivers  
+- Recruitment status  
+- Participation history  
+- Team stats + points  
+
+Teams exist platform-wide — not only inside one league.
+
+## 2.2 Team Participation in a League
+
+Teams can:
+- register for seasons  
+- assign drivers to race slots  
+- have different drivers each week  
+- score parallel points from every contributing driver  
+
+## 2.3 Constructors-Style Points
+
+GridPilot supports multiple team scoring methods:
+
+- **All Drivers Count** (every finisher scores team points)  
+- **Top X Drivers Count** (top 2, top 3, etc.)  
+- **Weighted Points** (e.g., top driver counts 60%, next counts 40%)  
+- **Custom Rules per League**
+
+Admins choose their model.  
+GridPilot handles the math, standings, history, and transparency.
+
+## 2.4 Team Rivalries & Identity
+
+Built-in:
+- team standings  
+- driver contribution breakdown  
+- cross-season performance  
+- team “form” (last 5 races)  
+- recruitment visibility  
+
+Team racing becomes **a core part of the platform**, not an afterthought.
+
+---
+
+# 3. Automated Leagues (F1-Style Mirror Systems)
+
+Some admins want complete freedom.  
+Some drivers want structured, official-feeling series.
+
+GridPilot supports *both* by providing the option for **auto-generated leagues**.
+
+These are **not forced**; they are templates admins or communities can adopt.
+
+## 3.1 What Are Automated Leagues?
+
+An automated league is a **predefined series template** provided by GridPilot that mirrors real motorsport.
+
+Examples:
+- F1 World Championship (same tracks, same order)  
+- F2 / F3 / F4 analogs  
+- GT3 European Sprint Cup  
+- IMSA-style multiclass  
+- DTM-style format  
+
+Users don’t need to invent formats — they pick from proven structures.
+
+## 3.2 What an Automated League Includes
+
+A template defines:
+- car class  
+- track calendar (pre-set schedule)  
+- race format (practice, quali, race)  
+- scoring system (e.g., FIA F1 points)  
+- bonus points (fastest lap, sprint race, etc.)  
+- team size (e.g., 2 drivers like Constructors)  
+- DNF rules  
+- drop rules (if any)  
+- penalty rules (warnings → time penalties → DSQ)  
+
+Admins can tweak details OR run it 1:1 as provided.
+
+## 3.3 Session Generation
+
+GridPilot can automatically:
+- create the full season  
+- populate all race settings  
+- optionally generate sessions via browser automation  
+- clearly list required content for admins  
+
+This is still *admin-controlled* automation —  
+GridPilot enhances, not replaces, human oversight.
+
+## 3.4 Why Automated Leagues Matter
+
+For drivers:
+- familiar formats  
+- real-world relevance  
+- stability  
+
+For admins:
+- less planning  
+- less overhead  
+- instantly “professional” structure  
+
+For GridPilot:
+- predictable competition ecosystem  
+- consistent feature usage  
+- scalable community engagement  
+
+---
+
+# 4. Penalty & Protest System
+
+A clean, structured way to handle disputes — core to GridPilot fairness.
+
+## 4.1 Driver-Protest Flow
+
+Drivers can submit:
+- race  
+- involved drivers  
+- replay timestamp(s)  
+- explanation text  
+- optional clip/video links  
+
+GridPilot stores everything in a clean UI.
+
+## 4.2 Admin Review Tools
+
+Admin sees:
+- list of protests  
+- timestamps  
+- notes  
+- links  
+- driver details  
+- race context  
+
+Actions:
+- no action  
+- warning  
+- time penalty (+5s / +10s / +30s)  
+- points deduction  
+- DSQ race  
+
+Everything updates automatically.
+
+## 4.3 Automatic Classification Updates
+
+Time penalties:
+- re-sort results  
+- adjust finishing positions  
+- recalc points  
+- update team standings  
+
+Penalties:
+- logged in history  
+- visible on driver/team pages  
+- part of season record  
+
+## 4.4 Consistency & Transparency
+
+GridPilot helps:
+- keep decisions structured  
+- avoid DM drama  
+- maintain fairness  
+- preserve season integrity  
+
+Admins stay in full control — GridPilot handles presentation & recalculation.
+
+---
+
+# 5. What We Must Consider (Key Constraints)
+
+## 5.1 Content Ownership
+
+Automated leagues need:
+- admins (or bot accounts) who own the tracks  
+- 1 owned car per allowed class  
+- iRacing credits to host sessions  
+
+GridPilot cannot bypass iRacing content rules.
+
+## 5.2 Avoiding Splits (Very Important)
+
+Splits destroy community identity.  
+GridPilot must:
+- keep leagues small (20–30 drivers)  
+- allow multiple parallel micro-series (F1-A, F1-B, etc.)  
+- unify standings across micro-series through stats (optional)  
+
+We scale *horizontally*, not vertically.
+
+## 5.3 Admin Optionality
+
+Automation is optional.  
+Manual control must always be possible.
+
+## 5.4 Don’t Replace Community
+
+GridPilot provides structure — not social control.  
+Discord remains important; we complement it.
+
+## 5.5 Avoid excessive complexity
+
+Penalty rules, team formats, automated templates —  
+all must stay simple, configurable, and not overwhelming.
+
+---
+
+# 6. GridPilot Race Management Summary
+
+GridPilot provides:
+- professional team racing  
+- structured constructors scoring  
+- predefined (or custom) league formats  
+- optional auto-generated F1-style calendars  
+- clean protests and quick penalties  
+- automatic standings  
+- minimal admin workload  
+- consistent racing identity  
+- scalable competition model  
+
+We don’t replace iRacing —  
+we give league racing the **structure, fairness, and identity** it has always lacked.