gridpilot.gg/docs/ROADMAP.md

GridPilot Implementation Roadmap

Overview

This roadmap provides a phased implementation plan for GridPilot, an automated league management platform for iRacing. Each phase builds upon the previous one, with clear success criteria and actionable todos.

Purpose:

• Guide iterative development from technical validation to public launch and monetization
• Track progress through checkable todos
• Validate assumptions before investing in full implementation
• Ensure architectural integrity throughout each phase

How to Use:

• Check off todos as they are completed (replace [ ] with [x])
• Review success criteria before moving to the next phase
• Refer to ARCHITECTURE.md for component boundaries and patterns
• Consult TESTS.md for testing approach and BDD scenario structure
• See CONCEPT.md for product vision and user needs

Relationship to MVP:

• Phase 0-1: Pre-MVP validation (technical feasibility, market validation)
• Phase 2: MVP (core league management with automated results)
• Phase 3-4: Enhanced MVP (automation layer, branding)
• Phase 5-6: Public launch and monetization

---

Phase 0: Foundation (Automation Testing - Internal)

Goal: Validate technical feasibility of browser automation and establish testing infrastructure.

Infrastructure Setup

• Initialize monorepo with npm workspaces (/src/apps, /src/packages)
• Set up TypeScript configuration (strict mode, path aliases)
• Configure ESLint and Prettier (no warnings tolerated)
• Create basic domain models (League, Team, Event, Driver, Result)
• Set up test harness (Vitest for unit/integration tests)
• Configure Docker Compose for E2E testing environment
• Document development setup in README.md

Automation Validation

• Install and configure Playwright for browser automation
• Test iRacing website navigation and authentication flow
• Test session creation page detection on members.iracing.com
• Test session ID extraction from URL or page elements
• Validate server-side result polling from iRacing API
• Create proof-of-concept automation script using Playwright
• Document browser automation approach and iRacing automation rules
• Identify automation failure modes and mitigation strategies

Testing Foundation

• Write example BDD scenarios (Given/When/Then format)
• Set up Dockerized E2E test environment
• Create fixture data for test scenarios
• Validate test isolation and repeatability
• Document testing strategy in TESTS.md

Success Criteria:

• Technical feasibility confirmed (browser automation reliable)
• Test infrastructure operational (unit, integration, E2E)
• Development environment documented and reproducible
• No blockers identified for MVP implementation

Note: This phase is internal validation only—no user-facing features.

---

Phase 1: Landing Page & Market Validation

Goal: Validate product-market fit before building the full application.

Marketing Website

• Build static marketing website (Next.js or similar)
• Create compelling copy addressing league organizer pain points
• Design product mockups and fake screenshots
• Add email collection form (waitlist integration)
• Implement privacy policy and terms of service
• Set up analytics (signups, page views, engagement)

Community Engagement

• Post to r/iRacing subreddit with mockups
• Share in iRacing Discord communities
• Reach out to league organizers directly
• Collect feedback on pain points and feature requests
• Conduct user interviews with interested organizers
• Document feedback in product backlog

Analysis

• Analyze email signup metrics
• Review qualitative feedback themes
• Validate assumptions about organizer pain points
• Assess willingness to pay (surveys, conversations)
• Document findings and adjust roadmap if needed

Success Criteria:

• 100+ email signups from target users
• Positive feedback from league organizers
• Validated demand for automated result import
• Confirmed interest in team-based scoring
• Product-market fit assumptions validated

Note: No application built in this phase—validation only. Pivot or proceed based on feedback.

---

Phase 2: MVP (League-Focused)

Goal: Build a functional league management platform with automated result import (no fees, no companion app yet).

Authentication & User Management

• Implement iRacing OAuth authentication flow
• Create user registration and profile system
• Build user role system (organizer, driver, spectator)
• Implement session management and token refresh
• Write BDD scenarios for authentication flows
• Achieve test coverage for auth domain

League Management (Core Domain)

• Implement CreateLeagueUseCase (see ARCHITECTURE.md)
• Create league CRUD operations (update, delete, archive)
• Build season setup (tracks, cars, rules configuration)
• Implement points system configuration (customizable)
• Create race event scheduling system
• Write BDD scenarios for league lifecycle
• Achieve >90% test coverage for League aggregate

Driver & Team Registration

• Build driver registration system (join league/season)
• Implement team registration system (optional parallel scoring)
• Create team roster management (add/remove drivers)
• Build approval workflow for registrations
• Write BDD scenarios for registration flows
• Test team scoring calculation logic

Automated Result Import

• Implement PostgreSQL schema (repositories pattern)
• Create server-side iRacing API integration
• Build automated result polling service
• Implement result parsing and validation
• Create ImportResultUseCase (see ARCHITECTURE.md)
• Handle edge cases (DNS, penalties, disconnects)
• Write BDD scenarios for result import
• Test result import reliability and error handling

Standings & Results

• Generate driver standings (individual points calculation)
• Generate team standings (parallel scoring model)
• Build race result pages (lap times, incidents, finishing position)
• Implement historical standings view (by race)
• Create standings export functionality (CSV)
• Write BDD scenarios for standings calculation
• Test edge cases (ties, dropped races, penalties)

League Identity & Admin

• Build league identity pages (public view)
• Create basic admin dashboard (organizer tools)
• Implement league settings management
• Build schedule and calendar view
• Create notifications system (race reminders)
• Write BDD scenarios for admin workflows

Quality Assurance

• Run full test suite (unit, integration, E2E)
• Achieve >90% test coverage for domain/application layers
• Perform manual testing with real iRacing data
• Fix all critical bugs and edge cases
• Document known limitations

Success Criteria:

• Functional platform for league management
• Automated result import working reliably
• Driver and team standings calculated correctly
• No manual result uploads required
• Test coverage >90% for core domain
• Ready for closed beta testing

Note: No fees, no payouts, no companion app in this phase. Focus on core league management.

Cross-References:

• See ARCHITECTURE.md for component boundaries
• See TESTS.md for BDD scenario examples

---

Phase 3: Companion App (Automation Layer)

Goal: Build an Electron companion app to automate session creation and reduce organizer workload.

Companion App Foundation

• Set up Electron application structure
• Implement Playwright browser automation framework
• Create IPC bridge for backend communication
• Build auto-updater mechanism
• Set up application signing and packaging
• Document installation and setup process

Session Creation Automation

• Build session creation assistance workflow
• Implement iRacing session page detection
• Create session ID extraction mechanism
• Build form auto-fill functionality (track, cars, rules)
• Implement session URL capture and sync
• Handle automation failure cases gracefully
• Write E2E tests for automation flows

OAuth & Credential Handoff

• Implement OAuth handoff from companion to web
• Create secure credential storage (encrypted)
• Build IPC bridge for authentication state
• Handle token refresh in companion app
• Write E2E tests for OAuth handoff flow
• Test cross-process credential security

Organizer Utilities

• Create session creation guidance (step-by-step)
• Build pre-race checklist functionality
• Implement session status monitoring
• Add quick access to league settings
• Create notifications for upcoming races

Testing & Reliability

• Test session creation automation reliability (>95% success rate)
• Validate automation across different iRacing UI versions
• Handle iRacing website changes gracefully
• Create fallback mechanisms for automation failures
• Document troubleshooting guide

Success Criteria:

• Companion app reduces session creation time by 80%+
• Automation success rate >95%
• OAuth handoff secure and seamless
• Auto-updater working reliably
• Comprehensive E2E test coverage

Note: Companion app is optional but highly valuable for organizers. Focus on reliability over features.

---

Phase 4: Branding & Public Pages

Goal: Enable professional league identity and public discoverability.

Asset Management

• Implement S3-compatible asset storage (logos, images)
• Add league logo upload functionality
• Create image optimization pipeline
• Implement asset CDN integration
• Build asset management UI (upload, delete, replace)

Custom Branding

• Create custom CSS/theming system (colors, fonts)
• Build theme preview functionality
• Implement logo placement customization
• Add custom header/footer options
• Create branding guidelines documentation

Public League Directory

• Build public league directory (browse and discover)
• Implement search and filtering (game type, region, skill level)
• Create league detail pages (public view)
• Add league statistics (active seasons, drivers, races)
• Implement privacy settings (public/private leagues)

External Integrations

• Implement optional custom domain support (CNAME)
• Create embeddable widgets (standings iframe, schedule)
• Add Discord/TeamSpeak integration links
• Implement YouTube/Twitch VOD linking (external only, no uploads)
• Build social sharing functionality (Twitter, Reddit)

Public Result Pages

• Create public race result pages (shareable links)
• Build driver profile pages (career statistics)
• Implement team profile pages (roster, history)
• Add historical standings archive
• Create race replay link integration (if available)

Testing & Documentation

• Write BDD scenarios for branding features
• Test public pages with various league configurations
• Validate custom domain setup process
• Create user guide for branding customization
• Test embeddable widgets in external sites

Success Criteria:

• Leagues have professional identity and branding
• Public directory drives league discovery
• Custom domains working reliably
• Embeddable widgets functional
• External integrations (Discord, Twitch) operational

Note: Branding features are optional but enhance league professionalism and discoverability.

---

Phase 5: Public Launch

Goal: Launch GridPilot publicly with production-grade infrastructure and stability.

Security & Compliance

• Perform security audit (OAuth, credentials, API security)
• Implement rate limiting and DDoS protection
• Add CSRF and XSS protection
• Conduct penetration testing
• Review GDPR compliance (user data handling)
• Implement data export functionality (user request)
• Create incident response plan

Performance & Scalability

• Load testing and performance optimization
• Implement database query optimization
• Add caching layers (Redis for sessions, API responses)
• Configure CDN for static assets
• Optimize Docker images for production
• Set up horizontal scaling strategy

Production Infrastructure

• Set up production hosting (AWS/GCP/Azure)
• Configure production database (PostgreSQL with replication)
• Implement database backup strategy (automated, tested)
• Set up monitoring and alerting (logs, errors, uptime)
• Configure error tracking (Sentry or similar)
• Implement log aggregation and analysis
• Create disaster recovery plan

Documentation & Support

• Write comprehensive user documentation
• Create organizer onboarding guide
• Build driver user guide
• Document API endpoints (if public)
• Create FAQ and troubleshooting guide
• Set up support system (email, Discord)

Launch Preparation

• Prepare launch marketing materials
• Coordinate Reddit/Discord announcements
• Create launch video/demo
• Set up social media presence
• Prepare press kit (if applicable)
• Plan launch timeline and milestones

Beta Onboarding

• Onboard first 10 beta leagues (closed beta)
• Collect feedback from beta users
• Fix critical bugs identified in beta
• Validate production stability under real load
• Document lessons learned

Success Criteria:

• Platform publicly available and stable
• Security audit passed with no critical issues
• Production infrastructure operational
• Monitoring and alerting functional
• User documentation complete
• First 10+ leagues successfully onboarded
• Platform stable under real-world load

Note: Public launch is a major milestone. Ensure stability and security before opening access.

---

Phase 6: Monetization & Expansion

Goal: Generate revenue and expand platform capabilities.

Monetization Features

• Implement league creation fee system
• Add optional driver entry fee per season
• Build revenue split mechanism (organizer/GridPilot)
• Create billing and invoicing system
• Implement payment processing (Stripe or similar)
• Add subscription management (for premium features)
• Create payout system for organizers
• Implement refund and dispute handling

Premium Features

• Create premium league features (advanced analytics)
• Build driver/team performance metrics over time
• Implement historical trend analysis
• Add advanced race strategy tools
• Create custom report generation
• Build league comparison and benchmarking

Analytics & Insights

• Add analytics dashboards for leagues
• Implement driver consistency metrics
• Create incident rate analysis
• Build lap time comparison tools
• Add race pace analysis
• Implement predictive performance modeling

Platform Expansion

• Explore expansion to other simulators (ACC, rFactor 2)
• Evaluate additional automation features
• Research multi-game league support
• Investigate community-requested features
• Assess partnership opportunities (teams, sponsors)

Business Intelligence

• Implement revenue tracking and reporting
• Create user engagement metrics
• Build churn analysis and retention tools
• Add A/B testing framework
• Implement feature adoption tracking

Success Criteria:

• Revenue generation active and growing
• Premium features adopted by target segment
• Payment processing reliable and secure
• Organizer payouts working correctly
• Platform expansion feasibility validated
• Positive unit economics demonstrated

Note: Monetization should not compromise core user experience. Ensure value delivery justifies pricing.

---

Dependencies & Sequencing

Critical Path:

1. Phase 0 must be completed before any development begins
2. Phase 1 validation should gate investment in Phase 2
3. Phase 2 MVP is required before Phase 3 (companion app depends on API)
4. Phase 4 can be developed in parallel with Phase 3 (independent features)
5. Phase 5 (public launch) requires Phases 2-4 to be complete and stable
6. Phase 6 (monetization) requires Phase 5 (public user base)

Optional Paths:

• Phase 3 (companion app) can be delayed if organizers tolerate manual session creation
• Phase 4 (branding) can be simplified for MVP launch
• Phase 6 features can be prioritized based on user demand

Iteration Strategy:

• Complete each phase fully before moving to the next
• Validate success criteria before proceeding
• Adjust roadmap based on feedback and learnings
• Maintain architectural integrity throughout

---

Living Document

This roadmap is a living document and will be updated as the project evolves. Key updates will include:

• Completed todos (checked off)
• Lessons learned from each phase
• Adjusted priorities based on user feedback
• New features discovered during development
• Changes to success criteria or scope

Maintenance:

• Review and update quarterly (or after each phase)
• Archive completed phases for reference
• Document deviations from original plan
• Track velocity and estimate remaining work

Cross-References:

• CONCEPT.md - Product vision and user needs
• ARCHITECTURE.md - Technical design and component boundaries
• TESTS.md - Testing strategy and BDD scenarios
• TECH.md - Technology decisions and rationale

---

Last Updated: 2025-11-23 Current Phase: Phase 0 (Foundation) Overall Progress: In Progress (browser automation implemented)