402 lines
17 KiB
Markdown
402 lines
17 KiB
Markdown
# 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* |