gridpilot.gg/docs/ROADMAP.md

# 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`](core/infrastructure/adapters/IAutomationLifecycleEmitter.ts:1) and [`OverlaySyncService`](core/application/services/OverlaySyncService.ts:1).
- Checkout safety via [`CheckoutPriceExtractor`](core/infrastructure/adapters/automation/CheckoutPriceExtractor.ts:1), [`ConfirmCheckoutUseCase`](core/application/use-cases/ConfirmCheckoutUseCase.ts:1), [`ElectronCheckoutConfirmationAdapter`](core/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`](core/domain/services/StepTransitionValidator.ts:1).
  - [ ] Ensure `tests/e2e/steps/*` cover all 18 hosted wizard steps end to end.
  - [ ] Harden [`WizardStepOrchestrator`](core/infrastructure/adapters/automation/core/PlaywrightAutomationAdapter.ts:1) behavior for retries and timeouts.
- [ ] Strengthen page validation:
  - [ ] Extend [`PageStateValidator`](core/domain/services/PageStateValidator.ts:1) to cover edge cases found in real-hosted tests.
  - [ ] Ensure selector sets in `core/infrastructure/adapters/automation/dom/*` match current iRacing UI.
- [ ] Tighten auth/session flows:
  - [ ] Verify [`CheckAuthenticationUseCase`](core/application/use-cases/CheckAuthenticationUseCase.ts:1), [`InitiateLoginUseCase`](core/application/use-cases/InitiateLoginUseCase.ts:1), and [`VerifyAuthenticatedPageUseCase`](core/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`](core/infrastructure/adapters/IAutomationLifecycleEmitter.ts:1) and consumed by [`OverlaySyncService`](core/application/services/OverlaySyncService.ts:1).
  - [ ] Ensure all critical state transitions of [`AutomationSession`](core/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`](core/infrastructure/adapters/automation/CheckoutPriceExtractor.ts:1) against current iRacing UI.
  - [ ] Ensure [`CheckoutState`](core/domain/value-objects/CheckoutState.ts:1) covers all relevant button states.
- [ ] Harden confirmation logic:
  - [ ] Confirm [`ConfirmCheckoutUseCase`](core/application/use-cases/ConfirmCheckoutUseCase.ts:1) is the *only* entry point for automation that proceeds past a non-zero price.
  - [ ] Ensure [`ElectronCheckoutConfirmationAdapter`](core/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`](core/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`](core/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`](core/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)