# 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](./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*