gridpilot.gg/docs/COMPANION_POC.md

GridPilot Companion App - POC Guide

Overview

The Electron companion app demonstrates the complete hosted session automation workflow with a visual interface, validating the Clean Architecture implementation through a functional proof-of-concept.

Quick Start

Prerequisites

npm install

Running the POC

npm run companion:start

This command:

1. Compiles TypeScript main process → dist/main/
2. Builds React renderer with Vite → dist/renderer/
3. Launches the Electron application

What You'll See

Left Panel: Session Configuration Form

Pre-configured form with fields representing all 18 automation steps:

• Session Name - Race session identifier
• Server Name - Server configuration name
• Passwords - Session and admin access credentials
• Max Drivers - Capacity (1-60)
• Track - Track selection (e.g., "watkins-glen")
• Cars - Vehicle selection (e.g., "porsche-911-gt3-r")
• Weather Type - Static or dynamic weather
• Time of Day - Morning, afternoon, evening, or night
• Session Lengths - Practice, qualifying, warmup, race durations
• Race Options - Start type, restarts, damage model
• Track State - Surface condition

Action: Click "Start Automation" to begin the workflow

Right Panel: Live Progress Monitor

Real-time visualization showing:

• Session ID - Generated UUID
• Current Status - Running/Completed/Failed/Stopped
• Step-by-Step Progress - Visual indicators for all 18 steps:
  • ✓ Green checkmark = Completed
  • Blue number = Current step (in progress)
  • Gray number = Pending
• Safety Notice - Yellow warning at step 18 stop point
• Progress Counter - "X / 18 steps" tracker

Expected Behavior

1. Initial State

• Form enabled with pre-filled POC defaults
• Progress panel shows "Configure and start..." message

2. Automation Started

• Form becomes disabled
• Button changes to "Automation Running..."
• Progress panel shows "Running" status
• Steps begin progressing: 1 → 2 → 3 → ... → 18

3. Step Progression (Simulated)

Each step takes ~500ms to complete:

• Step 1: Navigate to Hosted Racing
• Step 2: Click Create a Race
• Step 3: Fill Race Information
• Step 4: Configure Server Details
• Step 5: Set Admins
• Step 6: Add Admin (modal step)
• Step 7: Set Time Limits
• Step 8: Set Cars
• Step 9: Add Car (modal step)
• Step 10: Set Car Classes
• Step 11: Set Track
• Step 12: Add Track (modal step)
• Step 13: Configure Track Options
• Step 14: Set Time of Day
• Step 15: Configure Weather
• Step 16: Set Race Options
• Step 17: Configure Team Driving
• Step 18: Set Track Conditions → STOPS HERE

4. Step 18 Reached

• Status changes to "Stopped at Step 18"
• Yellow safety notice appears:

  ⚠️ Safety Stop
  Automation stopped at step 18 (Track Conditions) as configured.
  This prevents accidental session creation during POC demonstration.
  

• Form remains disabled
• All 18 steps visible with completion status

Technical Architecture

Clean Architecture Validation

Presentation Layer (newly created):

src/apps/companion/
├── main/
│   ├── index.ts              # Electron app initialization
│   ├── di-container.ts       # Dependency injection
│   ├── ipc-handlers.ts       # IPC request/response handlers
│   └── preload.ts            # Secure IPC bridge
└── renderer/
    ├── App.tsx               # Main UI component
    ├── main.tsx              # React entry point
    ├── index.html            # HTML entry
    └── components/
        ├── SessionCreationForm.tsx
        └── SessionProgressMonitor.tsx

Reused Layers (100% unchanged):

• Domain: AutomationSession, SessionState, StepId
• Application: StartAutomationSessionUseCase
• Infrastructure: MockBrowserAutomationAdapter, MockAutomationEngineAdapter, InMemorySessionRepository

IPC Communication Flow

Renderer Process              Main Process
     |                             |
     |-- start-automation -------->|
     |                             |-- Create session
     |                             |-- Start automation engine
     |                             |-- Begin step execution loop
     |                             |
     |<-- session-progress --------|  (emitted every 100ms)
     |<-- session-progress --------|
     |<-- session-progress --------|
     |                             |

Dependency Chain

UI Component (React)
    ↓
IPC Handler (Electron main)
    ↓
DI Container
    ↓
StartAutomationSessionUseCase
    ↓
MockAutomationEngineAdapter
    ↓
MockBrowserAutomationAdapter
InMemorySessionRepository

POC Success Criteria

✅ Clean Architecture Preserved

• Zero business logic in UI components
• Complete separation of concerns
• All 158 existing tests still passing
• Domain/application/infrastructure layers unchanged

✅ 18-Step Workflow Visualized

• All steps from ROADMAP.md represented
• Real-time progress updates every 100ms
• State transitions validated by domain layer
• Step execution tracked via domain entities

✅ Mock Adapters Functional

• Browser automation simulated with realistic delays
• Session state persisted in-memory
• Dependency injection wiring complete
• Automation engine orchestrates workflow

✅ Electron Best Practices

• Context isolation enabled
• Preload script for secure IPC
• Main/renderer process separation
• No node integration in renderer

✅ Safety Stop Demonstrated

• Automation stops at step 18 as designed
• STOPPED_AT_STEP_18 state properly displayed
• Clear user communication about safety measure
• No accidental session creation possible

Architecture Compliance

Boundaries Respected

Presentation Layer (UI only):

• React components render data
• Electron IPC handles communication
• No domain knowledge or business logic

Application Layer (orchestration):

• Use cases coordinate workflow
• Port interfaces define contracts
• No UI or infrastructure concerns

Domain Layer (business rules):

• Entities enforce invariants
• Value objects validate states
• Services implement domain logic
• No dependencies on outer layers

Infrastructure Layer (adapters):

• Mock implementations for POC
• Repository handles persistence
• Automation adapters simulate browser
• Ready to swap with real implementations

SOLID Principles Demonstrated

• Single Responsibility: Each component has one clear purpose
• Open/Closed: New adapters can be added without changing domain
• Liskov Substitution: Mock adapters fully implement port interfaces
• Interface Segregation: Clean port definitions, no fat interfaces
• Dependency Inversion: All dependencies point inward via abstractions

Next Steps (Beyond POC)

This POC validates the technical approach. For production:

1. Replace Mock Adapters:

   • Swap MockBrowserAutomationAdapter with PuppeteerAdapter or PlaywrightAdapter
   • Replace InMemorySessionRepository with PostgreSQLSessionRepository

2. Implement Real Automation:

   • Add actual browser control (Puppeteer/Playwright)
   • Implement iRacing website interaction
   • Handle real modals, forms, and navigation

3. Add Pause/Resume:

   • IPC handlers currently stubbed
   • Implement session state management
   • Add UI controls for pause/resume

4. Polish UI/UX:

   • Professional styling and branding
   • Error recovery flows
   • Better loading states

5. Production Features:

   • Auto-updater mechanism
   • Crash reporting
   • Logging and diagnostics
   • User preferences storage

Troubleshooting

Build Fails

# Clean and rebuild
rm -rf dist node_modules
npm install
npm run companion:build

Electron Doesn't Start

# Verify build output exists
ls dist/main/index.js        # Main process
ls dist/renderer/index.html  # Renderer

# Run directly
electron dist/main/index.js

Progress Not Updating

• Open DevTools in Electron (View → Toggle Developer Tools)
• Check browser console for errors
• Verify IPC handlers registered
• Check main process terminal output

TypeScript Errors

# Check configuration
cat tsconfig.electron.json

# Verify include paths match your structure
npm run typecheck

File Reference

File	Purpose	Lines
main/index.ts	Electron app initialization	39
main/di-container.ts	Dependency injection setup	47
main/ipc-handlers.ts	Request/response handlers	79
main/preload.ts	Secure IPC bridge	21
renderer/App.tsx	Main UI component	80
renderer/components/SessionCreationForm.tsx	Config form	173
renderer/components/SessionProgressMonitor.tsx	Progress visualization	213
MockAutomationEngineAdapter.ts	Automation orchestrator	85

Conclusion

This POC successfully demonstrates:

• Clean Architecture principles in practice
• Separation of concerns across all layers
• Real-time automation workflow visualization
• Safety controls preventing accidental actions
• Foundation for production implementation

All domain logic remains testable, maintainable, and independent of UI or infrastructure concerns. The 158 passing tests validate the core business rules remain intact.