# GridPilot

[![Build Status](https://img.shields.io/badge/build-pending-lightgrey)](https://github.com/yourusername/gridpilot)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**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](docs/WINDOWS_COMPATIBILITY.md).

## Installation

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

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

```bash
# 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`](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`](docs/) directory:

- **[CONCEPT.md](docs/CONCEPT.md)** - Product vision and problem statement
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Technical design and Clean Architecture implementation
- **[TECH.md](docs/TECH.md)** - Technology stack and tooling decisions
- **[TESTS.md](docs/TESTS.md)** - Testing strategy and BDD approach
- **[ROADMAP.md](docs/ROADMAP.md)** - Development phases and milestones

## License

MIT License - see [LICENSE](LICENSE) file for details.