# GridPilot Implementation Roadmap ## 1. Big Picture and Scope GridPilot is the **competition layer** for iRacing leagues, as described in: - [`CONCEPT.md`](docs/concept/CONCEPT.md) - [`ADMINS.md`](docs/concept/ADMINS.md) - [`DRIVERS.md`](docs/concept/DRIVERS.md) - [`COMPETITION.md`](docs/concept/COMPETITION.md) - [`RACING.md`](docs/concept/RACING.md) - [`STATS.md`](docs/concept/STATS.md) - [`RATING.md`](docs/concept/RATING.md) - [`SOCIAL.md`](docs/concept/SOCIAL.md) - [`TEAMS.md`](docs/concept/TEAMS.md) Those docs describe the full platform: leagues, seasons, standings, stats, rating, complaints, social, teams, discovery, monetization. This **repository** currently implements a **narrow, ToS-safe slice** of that vision: - A desktop Electron companion running on the admin’s machine. - A hosted-session automation engine that drives the iRacing web UI with Playwright. - Domain and application logic for: - hosted wizard steps - authentication and cookie/session reuse - overlays and lifecycle events - checkout safety and confirmation. For the technical slice implemented here, see: - [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) - [`TECH.md`](docs/TECH.md) - [`TESTS.md`](docs/TESTS.md) Everything else from the concept docs (league/season management, stats, social, complaints, team identity, discovery) is **future or external** to this repo and will live in other services. This roadmap is therefore split into two levels: - **Automation & Companion Roadmap** – implementation-level, this repo. - **Core Platform Roadmap** – high-level, future/external services guided by the concept docs. ## 2. How to Use This Roadmap - Treat Automation & Companion items as work **inside this repo**. - Treat Core Platform items as **future/external services** that will integrate with this automation slice later. - Use checklists for near-term Automation & Companion work only. - Use the concept docs plus [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) as the source of truth for scope boundaries. - Keep success criteria **testable**, using patterns in [`TESTS.md`](docs/TESTS.md). --- ## 3. Automation & Companion Roadmap (This Repo) This track is grounded in the existing code and architecture: - Hosted wizard flow and step orchestration (see `tests/e2e/steps/*` and `tests/e2e/workflows/*`). - Auth and cookie/session management. - Overlay lifecycle via [`IAutomationLifecycleEmitter`](packages/infrastructure/adapters/IAutomationLifecycleEmitter.ts:1) and [`OverlaySyncService`](packages/application/services/OverlaySyncService.ts:1). - Checkout safety via [`CheckoutPriceExtractor`](packages/infrastructure/adapters/automation/CheckoutPriceExtractor.ts:1), [`ConfirmCheckoutUseCase`](packages/application/use-cases/ConfirmCheckoutUseCase.ts:1), [`ElectronCheckoutConfirmationAdapter`](packages/infrastructure/adapters/ipc/ElectronCheckoutConfirmationAdapter.ts:1) and the renderer dialog. - Electron companion UI and IPC wiring. ### Phase A: Solid Hosted-Session Engine & Companion Baseline **Goal:** Make the existing hosted-session automation and Electron companion reliable, observable, and easy to run on an admin’s machine. **Automation (this repo)** - [ ] Stabilize wizard step orchestration: - [ ] Review and align wizard-step domain rules with [`StepTransitionValidator`](packages/domain/services/StepTransitionValidator.ts:1). - [ ] Ensure `tests/e2e/steps/*` cover all 18 hosted wizard steps end to end. - [ ] Harden [`WizardStepOrchestrator`](packages/infrastructure/adapters/automation/core/PlaywrightAutomationAdapter.ts:1) behavior for retries and timeouts. - [ ] Strengthen page validation: - [ ] Extend [`PageStateValidator`](packages/domain/services/PageStateValidator.ts:1) to cover edge cases found in real-hosted tests. - [ ] Ensure selector sets in `packages/infrastructure/adapters/automation/dom/*` match current iRacing UI. - [ ] Tighten auth/session flows: - [ ] Verify [`CheckAuthenticationUseCase`](packages/application/use-cases/CheckAuthenticationUseCase.ts:1), [`InitiateLoginUseCase`](packages/application/use-cases/InitiateLoginUseCase.ts:1), and [`VerifyAuthenticatedPageUseCase`](packages/application/use-cases/VerifyAuthenticatedPageUseCase.ts:1) match the constraints in [`CONCEPT.md`](docs/concept/CONCEPT.md) and [`RACING.md`](docs/concept/RACING.md). - [ ] Confirm cookie handling in `automation/auth/*` matches the lifecycle described in [`ARCHITECTURE.md`](docs/ARCHITECTURE.md). - [ ] Companion baseline: - [ ] Ensure the Electron app boots and connects reliably on supported platforms (see smoke tests in `tests/smoke/*`). - [ ] Keep the renderer minimal but clear: session creation, auth state, progress, checkout confirmation. **Success criteria** - All unit, integration and E2E tests for existing flows are green (see [`TESTS.md`](docs/TESTS.md)). - Full hosted-session workflows (fixture-based and real-hosted where enabled) complete without intermittent failures. - Auth/login flow is ToS-safe, matches the “helper, not cheat” model in [`CONCEPT.md`](docs/concept/CONCEPT.md), and remains visible to the admin. - Companion can run a full hosted-session creation with no manual DOM clicks beyond login. ### Phase B: Overlay & Lifecycle Clarity **Goal:** Make the automation lifecycle and overlay behavior predictable and trustworthy for admins. **Automation (this repo)** - [ ] Lifecycle events: - [ ] Review events emitted by [`IAutomationLifecycleEmitter`](packages/infrastructure/adapters/IAutomationLifecycleEmitter.ts:1) and consumed by [`OverlaySyncService`](packages/application/services/OverlaySyncService.ts:1). - [ ] Ensure all critical state transitions of [`AutomationSession`](packages/domain/entities/AutomationSession.ts:1) are reflected in overlay events. - [ ] Overlay UX: - [ ] Ensure [`SessionProgressMonitor`](apps/companion/renderer/components/SessionProgressMonitor.tsx:1) clearly maps steps 1–18 to admin-understandable labels. - [ ] Align overlay messaging with admin QoL themes in [`ADMINS.md`](docs/concept/ADMINS.md) (less repetitive work, more transparency). - [ ] Error surfacing: - [ ] Standardize how validation and runtime errors are propagated from domain → application → companion UI. - [ ] Ensure failures are actionable (what failed, where, and what the admin can retry). **Success criteria** - Overlay and progress UI always reflect the underlying session state without lag or missing steps. - Admin can see where automation stopped and why, without reading logs. - Lifecycle behavior is fully covered in tests (overlay integration, companion workflow E2E), as referenced from [`TESTS.md`](docs/TESTS.md). ### Phase C: Checkout Safety Path **Goal:** Make every credit/checkout-like action go through an explicit, traceable confirmation path that admins can trust. **Automation (this repo)** - [ ] Enrich checkout detection: - [ ] Validate selector logic and price parsing in [`CheckoutPriceExtractor`](packages/infrastructure/adapters/automation/CheckoutPriceExtractor.ts:1) against current iRacing UI. - [ ] Ensure [`CheckoutState`](packages/domain/value-objects/CheckoutState.ts:1) covers all relevant button states. - [ ] Harden confirmation logic: - [ ] Confirm [`ConfirmCheckoutUseCase`](packages/application/use-cases/ConfirmCheckoutUseCase.ts:1) is the *only* entry point for automation that proceeds past a non-zero price. - [ ] Ensure [`ElectronCheckoutConfirmationAdapter`](packages/infrastructure/adapters/ipc/ElectronCheckoutConfirmationAdapter.ts:1) and [`CheckoutConfirmationDialog`](apps/companion/renderer/components/CheckoutConfirmationDialog.tsx:1) enforce explicit admin confirmation and timeouts. - [ ] Failure paths: - [ ] Verify that any parsing failure or ambiguous state results in a safe stop, not a blind click. - [ ] Add tests to cover “weird but possible” UI states observed via fixtures. **Success criteria** - No automation path can perform a checkout-like action without an on-screen confirmation dialog. - All credit-related flows are covered in tests (unit, integration, and companion E2E) with failure-path assertions. - Behavior matches the safety and trust requirements in [`ADMINS.md`](docs/concept/ADMINS.md) and [`RACING.md`](docs/concept/RACING.md). ### Phase D: Additional Hosted Workflows & Admin QoL **Goal:** Extend automation beyond the initial hosted-session wizard happy path while staying within the same ToS-safe browser automation model. **Automation (this repo)** - [ ] Map additional hosted workflows: - [ ] Identify additional iRacing hosted flows that align with admin QoL needs from [`ADMINS.md`](docs/concept/ADMINS.md) (e.g. practice-only, league-specific hosted sessions). - [ ] Encode them as configurations on top of [`HostedSessionConfig`](packages/domain/entities/HostedSessionConfig.ts:1) where feasible. - [ ] Workflow templates: - [ ] Provide a small set of reusable presets (e.g. “standard league race”, “test session”) that can later be populated by external services. - [ ] Resilience work: - [ ] Improve behavior under partial UI changes (selectors, labels) using the validation patterns from [`PageStateValidator`](packages/domain/services/PageStateValidator.ts:1). **Success criteria** - At least one additional hosted workflow beyond the baseline wizard is supported end to end. - Admins can choose between a small number of well-tested presets that reflect league use-cases from [`COMPETITION.md`](docs/concept/COMPETITION.md). - Automation remains fully ToS-safe (no gameplay-affecting automation, no desktop/sim process interference), as reiterated in [`ARCHITECTURE.md`](docs/ARCHITECTURE.md). ### Phase E: Operationalization & Packaging **Goal:** Make it realistic for real league admins to install, configure and operate the companion and automation engine. **Automation (this repo)** - [ ] Packaging & configuration: - [ ] Ensure Electron packaging, browser mode configuration and logging settings match the expectations in [`TECH.md`](docs/TECH.md). - [ ] Provide a minimal operator-facing configuration story (environment, headless vs headed, fixture vs live). - [ ] Observability: - [ ] Ensure logs and failure artifacts are sufficient for debugging issues without code changes. - [ ] Documentation: - [ ] Keep operator-focused docs short and aligned with admin benefits from [`ADMINS.md`](docs/concept/ADMINS.md). **Success criteria** - A technically inclined admin can install the companion, configure automation mode, and run a full hosted-session workflow using only the documentation in this repo. - Most operational issues can be diagnosed via logs and failure artifacts without code-level changes. - Existing tests remain the primary safety net for refactors (see [`TESTS.md`](docs/TESTS.md)). --- ## 4. Core Platform Roadmap (Future / External Services) This track covers the broader GridPilot competition platform from the concept docs. It is **not** implemented in this repo and will likely live in separate services/apps that integrate with the automation engine described in [`ARCHITECTURE.md`](docs/ARCHITECTURE.md). Each phase is intentionally high-level to avoid going stale; details belong in future architecture docs for those services. ### Phase P1: League Identity and Seasons **Core Platform (future/external)** - Provide a clean league home, as described in: - [`CONCEPT.md`](docs/concept/CONCEPT.md) - [`ADMINS.md`](docs/concept/ADMINS.md) - Implement league identity, schedules and season configuration: - public league pages, schedules, rules, rosters (see sections 3 and 4 in [`CONCEPT.md`](docs/concept/CONCEPT.md)). - admin tools for creating seasons, calendars, formats (mirroring [`RACING.md`](docs/concept/RACING.md)). - Model leagues, seasons and events as first-class entities that can later produce [`HostedSessionConfig`](packages/domain/entities/HostedSessionConfig.ts:1) instances for this repo’s automation engine. **Success criteria** - Leagues can exist, configure seasons and publish schedules independent of automation. - Competition structure (points presets, drop weeks, team vs solo) matches the expectations in [`COMPETITION.md`](docs/concept/COMPETITION.md). - There is a clear integration point for calling the automation engine with derived hosted-session configurations (described in the future platform’s own architecture docs). ### Phase P2: Results, Stats, Rating v1, and Team Competition **Core Platform (future/external)** - Result ingestion & standings: - Implement automated result import and standings as described in [`CONCEPT.md`](docs/concept/CONCEPT.md) and [`STATS.md`](docs/concept/STATS.md). - Combine imported results into per-season standings for drivers and teams. - Team system: - Implement team profiles and constructors-style championships as in [`TEAMS.md`](docs/concept/TEAMS.md) and team sections of [`RACING.md`](docs/concept/RACING.md). - Stats and inputs for rating: - Structure league and season stats so that league results, incidents, team points and attendance are reliably captured as described in [`STATS.md`](docs/concept/STATS.md). - GridPilot Rating v1 (platform-side service): - Deliver a first usable GridPilot Rating capability consistent with [`RATING.md`](docs/concept/RATING.md), computed entirely in core platform services. - Treat this repo’s automation slice as a producer of trusted, structured session configs and results; do not move any rating logic into the automation engine. **Success criteria** - For a league connected to GridPilot, standings and stats update automatically based on iRacing results and provide the inputs required by the rating model in [`RATING.md`](docs/concept/RATING.md). - Teams and drivers have persistent identity and history across seasons, matching the narratives in [`DRIVERS.md`](docs/concept/DRIVERS.md) and [`TEAMS.md`](docs/concept/TEAMS.md). - Automation engine in this repo can be treated as a “session executor” feeding reliable results into the platform’s scoring and rating engines, while rating computation remains in Core Platform services. ### Phase P3: Complaints, Penalties, Transparency, and Rating Fairness **Core Platform (future/external)** - Complaint intake: - Structured complaint flows as defined in [`CONCEPT.md`](docs/concept/CONCEPT.md) and [`RACING.md`](docs/concept/RACING.md) (race, drivers, timestamps, evidence). - Penalty tools: - Admin-facing review and decision tools described in [`ADMINS.md`](docs/concept/ADMINS.md) and [`RACING.md`](docs/concept/RACING.md). - Classification updates: - Automatic recalculation of results and standings after penalties, aligned with the classification and penalty handling in [`STATS.md`](docs/concept/STATS.md). - Rating dependencies: - Ensure that penalty-aware classification, incident handling and transparency from this phase directly feed into GridPilot Rating as incident and season factors, consistent with [`RATING.md`](docs/concept/RATING.md). - Keep rating computation fully within Core Platform services; this repo continues to provide only the structured competition data that rating consumes. **Success criteria** - Complaints and penalties are no longer handled via ad-hoc Discord and spreadsheets. - Standings, stats, histories and rating signals remain consistent and penalty-aware. - The platform exposes a transparent, auditable record of decisions, supporting the fairness and rating trust goals from the concept docs. ### Phase P4: Social, Discovery, and Monetization **Core Platform (future/external)** - Social and discovery: - Implement the lightweight social and discovery features from [`SOCIAL.md`](docs/concept/SOCIAL.md) and league/team profile extensions in [`TEAMS.md`](docs/concept/TEAMS.md). - League and driver discovery: - Make it easy for drivers to find leagues and teams, and for leagues to find drivers, as described in [`DRIVERS.md`](docs/concept/DRIVERS.md) and [`COMPETITION.md`](docs/concept/COMPETITION.md). - Monetization (later phase): - Add monetization and premium features only after the core competition and trust layers are stable, following the MVP philosophy in [`CONCEPT.md`](docs/concept/CONCEPT.md). **Success criteria** - Drivers, teams and leagues can discover each other through GridPilot, with identity and history driving trust. - Social features remain lightweight and purpose-driven, complementing community tools like Discord instead of replacing them. - Any monetization respects the “clarity, fairness, and admin control” principles in the concept docs. --- ## 5. Dependencies and Evolution - Automation & Companion phases (A–E) are largely **independent** of Core Platform phases and can be completed first. - Core Platform phases (P1–P4) depend on: - A stable automation engine and companion (this repo). - Clear APIs/IPC or integration contracts that should be documented in future platform services, referencing [`ARCHITECTURE.md`](docs/ARCHITECTURE.md). - The automation slice should remain **small and robust**, so that multiple future services can treat it as a shared “session engine.” Use this roadmap as a **living, checkable** guide: - Update checklists under Automation & Companion as work lands. - Keep Core Platform phases at the level of concept alignment, not implementation detail. - When new services are built, they should introduce their own roadmaps and link back to: - [`CONCEPT.md`](docs/concept/CONCEPT.md) and related concept docs. - [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the automation slice. - [`TESTS.md`](docs/TESTS.md) for testing strategy and coverage expectations. **Last Updated:** 2025-12-01 **Tracks:** Automation & Companion (this repo) / Core Platform (future/external) **Current Focus:** Phase A (Solid hosted-session engine & companion baseline)