GridPilot

Modern league management for iRacing

GridPilot streamlines the organization and administration of iRacing racing leagues, eliminating manual spreadsheet management and providing real-time race data integration. Built with Clean Architecture principles and comprehensive BDD testing.

Prerequisites

• Node.js >=20.0.0 (includes npm)
• Docker and Docker Compose
• Git for version control

Windows Compatibility

This project is fully compatible with Windows 11, macOS, and Linux. All development scripts have been updated to work across all platforms:

• ✅ Cross-platform npm scripts
• ✅ Windows-compatible Docker commands
• ✅ Universal test commands
• ✅ Cross-platform cleanup scripts

For detailed information, see Windows Compatibility Guide.

Installation

# Clone the repository
git clone https://github.com/yourusername/gridpilot.git
cd gridpilot

# Install dependencies
npm install

Environment configuration files (.env) will be needed for each application. Refer to .env.example files in each app directory for required variables.

Development Workflow

GridPilot uses a monorepo structure with concurrent development across multiple applications:

# Run all applications in development mode
npm run dev

# Build all applications
npm run build

# Run all tests
npm test

Individual applications support hot reload and watch mode during development:

• web-api: Backend REST API server
• web-client: Frontend React application
• companion: Desktop companion application

Testing Commands

GridPilot follows strict BDD (Behavior-Driven Development) with comprehensive test coverage.

Local Verification Pipeline

GridPilot uses lint-staged to automatically validate only changed files on commit:

• eslint --fix runs on changed JS/TS/TSX files
• vitest related --run runs tests related to changed files
• prettier --write formats JSON, MD, and YAML files

This ensures fast commits without running the full test suite.

Pre-Push Hook

A pre-push hook runs the full verification pipeline before pushing to remote:

• npm run lint - Check for linting errors
• npm run typecheck - Verify TypeScript types
• npm run test:unit - Run unit tests
• npm run test:integration - Run integration tests

You can skip this with git push --no-verify if needed.

Individual Commands

# Run all tests
npm test

# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

# E2E tests (requires Docker)
npm run test:e2e

# Watch mode for TDD workflow
npm run test:watch

# Generate coverage report
npm run test:coverage

All E2E tests run in isolated Docker containers to ensure consistent, reproducible results.

Monorepo Structure

gridpilot/
├── src/
│   ├── core/          # Shared packages
│   │   ├── domain/        # Core business logic (entities, value objects)
│   │   ├── application/   # Use cases and orchestration
│   │   ├── shared/        # Common utilities and types
│   │   └── contracts/     # Interface definitions
│   ├── apps/              # Deployable applications
│   │   ├── web-api/       # Backend REST API
│   │   ├── web-client/    # Frontend React app
│   │   └── companion/     # Desktop companion
│   └── infrastructure/    # External adapters (DB, APIs)
├── tests/
│   ├── unit/             # Fast, isolated tests
│   ├── integration/      # Service integration tests
│   └── e2e/              # End-to-end scenarios
├── docker/               # Container configurations
├── docs/                 # Project documentation
└── scripts/              # Build and automation scripts

For detailed architectural information, see /docs/ARCHITECTURE.md.

Contributing

GridPilot adheres to strict development standards:

• Clean Architecture: Domain logic remains independent of frameworks and external concerns
• BDD Testing: All features must have Given/When/Then scenarios
• TypeScript Strict Mode: No implicit any, full type safety
• TDD Workflow: RED → GREEN → Refactor cycle enforced

Pull Request Process

1. Ensure all tests pass (npm test)
2. Verify no linting errors (npm run lint)
3. Update relevant documentation
4. Follow conventional commit format
5. Submit PR with clear description

Documentation

Comprehensive documentation is available in the /docs directory:

• CONCEPT.md - Product vision and problem statement
• ARCHITECTURE.md - Technical design and Clean Architecture implementation
• TECH.md - Technology stack and tooling decisions
• TESTS.md - Testing strategy and BDD approach
• ROADMAP.md - Development phases and milestones

License

MIT License - see LICENSE file for details.