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

```bash
npm install
```

### Running the POC

```bash
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`](../src/packages/domain/entities/AutomationSession.ts:1), [`SessionState`](../src/packages/domain/value-objects/SessionState.ts:1), [`StepId`](../src/packages/domain/value-objects/StepId.ts:1)
- **Application**: [`StartAutomationSessionUseCase`](../src/packages/application/use-cases/StartAutomationSessionUseCase.ts:1)
- **Infrastructure**: [`MockBrowserAutomationAdapter`](../src/infrastructure/adapters/automation/MockBrowserAutomationAdapter.ts:1), [`MockAutomationEngineAdapter`](../src/infrastructure/adapters/automation/MockAutomationEngineAdapter.ts:1), [`InMemorySessionRepository`](../src/infrastructure/repositories/InMemorySessionRepository.ts:1)

### 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`](./ROADMAP.md:1) 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`](../src/infrastructure/adapters/automation/MockBrowserAutomationAdapter.ts:1) with `PuppeteerAdapter` or `PlaywrightAdapter`
   - Replace [`InMemorySessionRepository`](../src/infrastructure/repositories/InMemorySessionRepository.ts:1) 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

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

### Electron Doesn't Start

```bash
# 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

```bash
# Check configuration
cat tsconfig.electron.json

# Verify include paths match your structure
npm run typecheck
```

## File Reference

| File | Purpose | Lines |
|------|---------|-------|
| [`main/index.ts`](../src/apps/companion/main/index.ts:1) | Electron app initialization | 39 |
| [`main/di-container.ts`](../src/apps/companion/main/di-container.ts:1) | Dependency injection setup | 47 |
| [`main/ipc-handlers.ts`](../src/apps/companion/main/ipc-handlers.ts:1) | Request/response handlers | 79 |
| [`main/preload.ts`](../src/apps/companion/main/preload.ts:1) | Secure IPC bridge | 21 |
| [`renderer/App.tsx`](../src/apps/companion/renderer/App.tsx:1) | Main UI component | 80 |
| [`renderer/components/SessionCreationForm.tsx`](../src/apps/companion/renderer/components/SessionCreationForm.tsx:1) | Config form | 173 |
| [`renderer/components/SessionProgressMonitor.tsx`](../src/apps/companion/renderer/components/SessionProgressMonitor.tsx:1) | Progress visualization | 213 |
| [`MockAutomationEngineAdapter.ts`](../src/infrastructure/adapters/automation/MockAutomationEngineAdapter.ts:1) | 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.