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

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

Run this sequence before pushing to ensure correctness:

npm run lint && npm run typecheck && npm run test:unit && npm run test:integration

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.