139 lines
4.4 KiB
Markdown
139 lines
4.4 KiB
Markdown
# GridPilot
|
|
|
|
[](https://github.com/yourusername/gridpilot)
|
|
[](https://www.typescriptlang.org/)
|
|
[](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
|
|
|
|
## 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
|
|
Run this sequence before pushing to ensure correctness:
|
|
```bash
|
|
npm run lint && npm run typecheck && npm run test:unit && npm run test:integration
|
|
```
|
|
|
|
### 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. |