gridpilot.gg/docs/CONCEPT.md

GridPilot Concept

Problem Statement

iRacing league management today is fragmented and manual:

• Communication Chaos: League organizers juggle Discord channels, Google Sheets, and manual messaging to coordinate everything
• No Visibility: Leagues operate in isolation without a central platform for discovery or branding
• Manual Burden: Admins spend hours manually entering race results, managing registrations, and creating sessions in iRacing
• Team Racing Limitations: No native support for team-based racing with parallel scoring (one driver per car slot, but team accumulates points)
• Session Creation Pain: Creating race sessions in iRacing requires tedious browser navigation and form filling
• Migration Challenges: Existing leagues can't easily migrate historical data or preserve their identity

Based on feedback from Reddit and Discord communities, league organizers are overwhelmed by administrative tasks when they'd rather focus on building community and running great racing events.

Target Users

League Organizers & Admins

What they need:

• Automated race result processing
• Easy session creation without manual browser work
• Tools to manage seasons, sign-ups, and standings
• Professional branding and identity for their league
• Custom domains to strengthen league identity
• Migration support to bring existing league history

Team Captains

What they need:

• Create and manage racing teams
• Register teams for league seasons
• Track team standings alongside driver standings
• Coordinate with team drivers
• View team performance history

Solo Drivers

What they need:

• Browse and discover active leagues
• Easy registration and sign-up flows
• Personal statistics and race history
• Track standings and points
• Connect with the racing community

Core Features

For Solo Drivers

League Discovery

• Browse active leagues across different series and skill levels
• Filter by time zones, competitiveness, and racing format
• Join leagues with simple registration flows

Personal Racing Stats

• Automatic race result tracking from iRacing
• Historical performance data
• Personal standings in each league
• Progress tracking across seasons

For Teams

Team Management

• Create and name racing teams
• Invite and manage team drivers
• Register teams for league seasons

Parallel Racing Format

• One driver per car slot in each race
• Team points accumulate from all drivers' results
• Both team standings and individual driver standings
• Flexibility for different drivers each race

Team Identity

• Team branding and profiles
• Historical team performance tracking
• Team communication tools

For League Organizers

League Identity & Branding

• Professional league pages with custom branding
• Custom domain support (e.g., your-league.racing)
• League logos, colors, and identity
• Public-facing presence for member recruitment

Race Management

• Automated result importing from iRacing
• No manual CSV uploads or data entry
• Session result processing tied to league structure
• Point calculations handled automatically

Season Administration

• Create and manage racing seasons
• Define scoring rules and formats
• Handle sign-ups and registrations
• Configure team vs solo racing formats

Authentication & Security

• Zero-knowledge login: GridPilot never sees or stores your password
• User performs login in visible browser window
• Persistent sessions: login once, stay logged in
• Secure access control for league admin functions

Migration Support

For Existing Leagues

• Import historical season data
• Preserve league identity and history
• Maintain continuity for established communities
• Smooth transition without losing context

User Journeys

Admin Creating a League

1. Sign in with iRacing credentials
2. Create new league with name and branding
3. Choose racing series and car/track combinations
4. Configure season format (team vs solo, point system)
5. Set up custom domain (optional)
6. Open registration for drivers/teams
7. Publish league page for discovery

Team Registering for a Season

1. Team captain browses available leagues
2. Reviews league format and schedule
3. Registers team for upcoming season
4. Invites or confirms team drivers
5. Receives confirmation and season details
6. Team appears in league roster

Driver Viewing Standings

1. Driver logs into GridPilot
2. Navigates to their league dashboard
3. Views current season standings (team and driver)
4. Reviews recent race results
5. Checks upcoming race schedule
6. Accesses historical performance data

Organizer Managing Race Day

1. Admin creates race session through GridPilot
2. Session automatically appears in iRacing
3. Drivers join and race in iRacing
4. Race completes in iRacing
5. GridPilot automatically imports results
6. Points calculated and standings updated
7. Admin reviews and publishes results
8. Drivers see updated standings immediately

Automation Vision

Why Browser Automation?

iRacing doesn't provide public APIs for session creation or comprehensive result data. League admins currently face:

• Repetitive browser navigation to create each race session
• Manual form filling for every session detail
• Time-consuming workflows that scale poorly with league size
• Error-prone manual processes

What Automation Solves

Session Creation Pain

• Eliminate manual browser work
• Create sessions from GridPilot with one click
• Batch session creation for full seasons
• Consistent configuration without human error

Result Processing

• Automatic result imports from iRacing
• No manual CSV downloads or uploads
• Real-time standings updates
• Accurate point calculations

Assistant-Style Approach

GridPilot acts as an admin assistant, not a bot:

• Automation runs on admin's behalf with their authorization
• Clear opt-in for automation features
• Admin maintains full control and visibility
• Automation handles tedious tasks, not gameplay

Important Boundary

We automate admin tasks, not gameplay.

GridPilot automates league management workflows - creating sessions, processing results, managing registrations. We never touch actual racing gameplay, driver behavior, or in-race activities. This is administrative automation to free organizers from manual work.

iRacing Automation Rules

Understanding the distinction between iRacing's interfaces is critical:

Two iRacing Interfaces:

1. iRacing Website (members.iracing.com): This is a standard HTML/DOM web application where hosted session management lives. Being a standard web application, it can be automated with browser automation tools like Playwright. This is 100% legal.

2. iRacing Desktop App (Electron): The racing simulation itself runs in a sandboxed Electron application. Its DOM is inaccessible, and any modification violates iRacing's Terms of Service. This is why tools like iRefined were shut down.

Our Approach:

• ✅ Browser automation of the website - Playwright automates members.iracing.com for session creation, form filling, and data extraction
• ❌ Never modify the desktop client - No DOM injection, no script injection, no client modification

Why This Matters:

• iRacing explicitly allows third-party tools that interact with their website
• Client modification (like iRefined did) violates TOS and risks account bans
• Browser automation is reliable, testable, and fully compliant

Security & Authentication

Zero-Knowledge Login Design

GridPilot requires access to your iRacing account to automate session creation, but we never see, store, or transmit your password. This section explains how we achieve secure authentication while maintaining complete transparency.

The Trust Problem

When an app asks for your credentials, you're trusting that app with your identity. Many apps:

• Store passwords in databases (risk of breach)
• Transmit credentials through their servers (man-in-the-middle risk)
• Have access to your login data internally (insider risk)

GridPilot takes a fundamentally different approach: we never have access to your credentials at all.

How GridPilot Authentication Works

┌─────────────────────────────────────────────────────────────────┐
│                     USER'S COMPUTER                              │
│  ┌───────────────┐         ┌─────────────────────────────────┐  │
│  │   GridPilot   │         │   Playwright Browser Window     │  │
│  │   Companion   │────────▶│   (Visible to User)             │  │
│  │      App      │         │                                 │  │
│  │               │         │   ┌─────────────────────────┐   │  │
│  │  Cannot read  │         │   │  iRacing Login Page     │   │  │
│  │  form inputs  │         │   │  members.iracing.com    │   │  │
│  │               │         │   │                         │   │  │
│  │  Only detects │         │   │  [Email: *********** ]  │   │  │
│  │  URL changes  │         │   │  [Password: ******** ]  │   │  │
│  │               │         │   │  [    Sign In    ]      │   │  │
│  └───────────────┘         │   └─────────────────────────┘   │  │
│                            └─────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                        │
                                        │ HTTPS
                                        ▼
                            ┌─────────────────────┐
                            │   iRacing Servers   │
                            │  (Direct connection │
                            │   from browser)     │
                            └─────────────────────┘

Step-by-Step Flow:

1. User clicks "Connect to iRacing" in GridPilot
2. A real browser window opens showing the iRacing login page
3. User verifies the URL - it's the real members.iracing.com
4. User enters credentials directly - GridPilot cannot read input fields
5. iRacing authenticates the user - credentials go directly to iRacing
6. GridPilot detects success - only by observing the URL change
7. Browser session is saved locally - for future automation runs

What GridPilot CAN and CANNOT Do

Capability	GridPilot Access
Read your password	❌ Never
See what you type	❌ Never
Intercept credentials	❌ Never
Know if login succeeded	✅ By URL change only
Use authenticated session	✅ For automation only
Clear your session	✅ User-initiated logout

Session Persistence

After your first login, GridPilot saves the browser session locally on your computer:

• Location: Your user data folder (not transmitted anywhere)
• Contents: Browser cookies and state (encrypted by OS)
• Benefit: You don't need to login every time you use GridPilot
• Control: You can sign out anytime to clear the saved session

Session Lifecycle:

First Use              Return Visit           Session Expired
    │                       │                       │
    ▼                       ▼                       ▼
┌─────────┐           ┌─────────┐            ┌─────────┐
│ Login   │           │ Check   │            │ Detect  │
│ Required│           │ Session │            │ Expiry  │
└────┬────┘           └────┬────┘            └────┬────┘
     │                     │                      │
     ▼                     ▼                      ▼
┌─────────┐           ┌─────────┐            ┌─────────┐
│ Browser │           │ Valid?  │───Yes────▶ │ Ready   │
│ Login   │           └────┬────┘            │ to Use  │
└────┬────┘                │ No              └─────────┘
     │                     │                      │
     ▼                     ▼                      ▼
┌─────────┐           ┌─────────┐            ┌─────────┐
│ Save    │           │ Re-auth │            │ Pause   │
│ Session │           │ Prompt  │            │ & Prompt│
└────┬────┘           └─────────┘            └─────────┘
     │
     ▼
┌─────────┐
│ Ready   │
│ to Use  │
└─────────┘

User Verification Points

At every step, you can verify GridPilot's behavior:

1. Browser Window: You see the real browser - not an embedded frame
2. URL Bar: Verify you're on members.iracing.com (look for HTTPS lock)
3. Network Traffic: Your credentials go directly to iRacing's servers
4. Input Fields: GridPilot cannot inject JavaScript to read form values
5. Logout Control: You can sign out from GridPilot at any time

Session Expiry During Automation

If your iRacing session expires while automation is running:

1. Automation pauses - no data loss
2. You're prompted to re-authenticate - same secure flow
3. Automation resumes - from where it left off

GridPilot never stores credentials to "auto-retry" - you always maintain control.

Security Guarantees

Guarantee	How We Ensure It
Zero-knowledge	Playwright browser is sandboxed; we cannot inject credential-reading code
No transmission	Your login happens directly with iRacing; GridPilot servers never see traffic
Local storage only	Session data stays on your computer, encrypted by your OS
User control	You can logout, clear sessions, or revoke access anytime
Transparency	Browser window is visible; you see exactly what's happening

Comparison to Other Approaches

Approach	Password Exposure	Risk Level
GridPilot (Zero-Knowledge)	Never exposed	✅ Minimal
OAuth (if iRacing offered it)	Never exposed	✅ Minimal
Password stored in app	App has access	⚠️ Moderate
Password in config file	File has plaintext	❌ High

Technical Implementation

For developers interested in the implementation details, see ARCHITECTURE.md. Key points:

• Playwright BrowserContext: Manages browser state including cookies
• Persistent Context: Saved to app.getPath('userData') in Electron
• Session Validation: Navigates to protected page; detects login redirects
• No Credential Ports: Application layer has no interfaces for password handling

Future Vision

Monetization Approach

GridPilot will introduce optional monetization features after the core platform is stable:

League Operation Fees

• Organizers can charge season entry fees
• Both one-time and per-race payment options
• Revenue split between league and GridPilot platform
• Support for league sustainability and prizes

Platform Position

• GridPilot takes a percentage of collected fees
• No fees for free leagues
• Transparent pricing structure
• Revenue supports platform development and hosting

When Monetization Arrives

Monetization features will be added only after:

• Core functionality is proven stable
• User base is established and growing
• League organizers are successfully using the platform
• Feedback confirms value justifies pricing

The focus now is delivering a great product that solves real problems. Monetization comes later when the platform has earned it.

Potential Expansion

Beyond iRacing, GridPilot's approach could extend to:

• Other sim racing platforms
• Different racing series and formats
• Broader motorsport league management
• Cross-platform racing communities

But first: nail the iRacing league management experience.

---

GridPilot exists to make league racing accessible and professional for organizers of all sizes, eliminating manual work so communities can focus on what matters: great racing and strong communities.

Last Updated: 2025-11-23