# Technology Stack

This document outlines GridPilot's technology choices and their rationale. For architectural patterns and layer organization, see [ARCHITECTURE.md](./ARCHITECTURE.md).

## 1. Language & Runtime

### TypeScript (Strict Mode)
- **Version:** Latest stable (5.x+)
- **Configuration:** `strict: true`, no `any` types permitted
- **Rationale:** Type safety catches errors at compile time, improves IDE support, and serves as living documentation. Strict mode eliminates common type-related bugs and enforces explicit handling of null/undefined.

### Node.js LTS
- **Version:** >=20.0.0
- **Rationale:** Long-term support ensures stability and security patches. Modern features (fetch API, native test runner) reduce dependency overhead. Version 20+ provides performance improvements critical for real-time race monitoring.

## 2. Backend Framework

### Current Status: Under Evaluation
Three candidates align with Clean Architecture principles:

**Option A: Express**
- **Pros:** Mature ecosystem, extensive middleware, proven at scale
- **Cons:** Slower than modern alternatives, callback-heavy patterns
- **Use Case:** Best if stability and middleware availability are priorities

**Option B: Fastify**
- **Pros:** High performance, schema-based validation, modern async/await
- **Cons:** Smaller ecosystem than Express
- **Use Case:** Best for performance-critical endpoints (real-time race data)

**Option C: Hono**
- **Pros:** Ultra-lightweight, edge-ready, excellent TypeScript support
- **Cons:** Newest option, smaller community
- **Use Case:** Best for modern deployment targets (Cloudflare Workers, edge functions)

**Requirements (All Options):**
- HTTP server with middleware support
- OpenAPI/Swagger compatibility
- JSON schema validation
- WebSocket support (for real-time features)

**Decision Timeline:** Deferred to implementation phase based on deployment target selection.

## 3. Frontend Framework

### Current Status: Under Evaluation
Two candidates meet accessibility and performance requirements:

**Option A: React 18+ with Vite**
- **Pros:** Maximum flexibility, fast HMR, lightweight bundle
- **Cons:** Manual SEO optimization, client-side routing complexity
- **Use Case:** Best for dashboard-heavy, interactive UI (primary use case)

**Option B: Next.js 14+**
- **Pros:** Built-in SSR/SSG, file-based routing, image optimization
- **Cons:** Larger bundle, more opinionated
- **Use Case:** Best if public league pages require SEO

**Shared Dependencies:**
- **State Management:**
  - TanStack Query: Server state (caching, optimistic updates, real-time sync)
  - Zustand: Client state (UI preferences, form state)
  - Rationale: Separation of concerns prevents state management spaghetti
- **UI Library:**
  - Tailwind CSS: Utility-first styling, design system consistency
  - shadcn/ui: Accessible components (WCAG 2.1 AA), copy-paste philosophy
  - Radix UI primitives: Unstyled, accessible foundations
  - Rationale: Rapid development without sacrificing accessibility or customization
- **Forms:** React Hook Form + Zod schemas (type-safe validation)
- **Routing:** React Router (Option A) or Next.js file-based routing (Option B)

**Decision Timeline:** Deferred to implementation phase. Leaning toward Option A (React + Vite) given dashboard-centric use case.

## 4. Database

### PostgreSQL 15+
- **Rationale:**
  - Complex relationships (leagues → seasons → races → drivers → teams) require relational integrity
  - JSONB columns handle flexible metadata (iRacing session results, custom league rules)
  - Full-text search for driver/team lookups
  - Battle-tested at scale, excellent TypeScript ORM support
- **Features Used:**
  - Foreign keys with cascading deletes
  - Check constraints (business rule validation)
  - Indexes on frequently queried fields (league_id, race_date)
  - Row-level security (multi-tenant data isolation)

### ORM: Under Evaluation

**Option A: Prisma**
- **Pros:** Type-safe queries, automatic migrations, excellent DX
- **Cons:** Additional build step, limited raw SQL for complex queries
- **Use Case:** Best for rapid development, type safety priority

**Option B: TypeORM**
- **Pros:** Decorators, Active Record pattern, SQL flexibility
- **Cons:** Older API design, less type-safe than Prisma
- **Use Case:** Best if complex SQL queries are frequent

**Decision Timeline:** Deferred to implementation phase. Both integrate cleanly with Clean Architecture (repository pattern at infrastructure layer).

## 5. Authentication

### iRacing OAuth Flow
- **Provider:** iRacing official OAuth 2.0
- **Rationale:** Official integration ensures compliance with iRacing Terms of Service. Users trust official credentials over third-party passwords.
- **Flow:** Authorization Code with PKCE (Proof Key for Code Exchange)

### Session Management
- **JWT:** Stateless tokens for API authentication
- **Storage:** HTTP-only cookies (XSS protection), encrypted at rest
- **Refresh Strategy:** Short-lived access tokens (15 min), long-lived refresh tokens (7 days)

### Implementation
- **Passport.js:** OAuth strategy handling, pluggable architecture
- **bcrypt:** Fallback password hashing (if local accounts added later)
- **Rationale:** Passport's strategy pattern aligns with Clean Architecture (adapter layer). Well-tested, extensive documentation.

## 6. Automation (Companion App)

### Electron
- **Version:** Latest stable (28.x+)
- **Rationale:** Cross-platform desktop framework (Windows, macOS, Linux). Native OS integration (system tray, notifications, auto-start).
- **Security:** Isolated renderer processes, context bridge for IPC

### Nut.js
- **Purpose:** Keyboard/mouse control for browser automation
- **Rationale:** Simulates human interaction with iRacing web UI when official API unavailable. Not gameplay automation—assistant for data entry tasks.
- **Constraints:** Windows-only initially (iRacing primary platform)

### Electron IPC
- **Main ↔ Renderer:** Type-safe message passing via preload scripts
- **Rationale:** Security (no direct Node.js access in renderer), type safety (Zod schemas for IPC contracts)

### Auto-Updates
- **electron-updater:** Handles signed updates, delta downloads
- **Rationale:** Critical for security patches, seamless user experience

**Why This Approach:**
- Assistant-style automation (user-initiated), not gameplay bots
- Complements web app (handles tasks iRacing API doesn't expose)
- Desktop integration (notifications for upcoming races, quick access via system tray)

## 7. Testing Tools

### Unit & Integration: Vitest
- **Rationale:** Native TypeScript support, fast execution (ESM, watch mode), compatible with Vite ecosystem
- **Coverage:** Built-in coverage reports (Istanbul), enforces 80% threshold

### E2E: Playwright
- **Rationale:** Reliable browser automation, cross-browser testing (Chromium, Firefox, WebKit), built-in wait strategies
- **Features:** Screenshot/video on failure, network mocking, parallel execution

### Test Containers (Docker)
- **Purpose:** Isolated test databases, Redis instances
- **Rationale:** Prevents test pollution, matches production environment, automatic cleanup
- **Services:** PostgreSQL, Redis, S3 (MinIO)

**Testing Strategy:**
- Unit tests: Core domain logic (pure functions, business rules)
- Integration tests: Repository implementations, API endpoints
- E2E tests: Critical user flows (create league, register for race, view results)

## 8. DevOps & Infrastructure

### Docker & Docker Compose
- **Purpose:** Local development, E2E testing, consistent environments
- **Services:**
  - PostgreSQL (primary database)
  - Redis (caching, rate limiting, job queue)
  - MinIO (S3-compatible storage for local dev)
- **Rationale:** Developers get production-like environment instantly

### Redis
- **Use Cases:**
  - Caching (league standings, frequently accessed driver stats)
  - Rate limiting (API throttling, abuse prevention)
  - Bull queue (background jobs: race result processing, email notifications)
- **Rationale:** Proven performance, simple key-value model, pub/sub for real-time features

### Object Storage
- **Production:** AWS S3 (logos, exported reports)
- **Development:** MinIO (S3-compatible, Docker-based)
- **Rationale:** Cost-effective, scalable, CDN integration

### Bull Queue (Redis-backed)
- **Jobs:** Process race results, send notifications, generate reports
- **Rationale:** Offloads heavy tasks from HTTP requests, retry logic, job prioritization

### CI/CD: Placeholder
- **Options:** GitHub Actions, GitLab CI
- **Rationale:** TBD based on hosting choice (GitHub vs. self-hosted GitLab)

## 9. Monorepo Tooling

### npm Workspaces
- **Rationale:** Built-in, zero configuration, dependency hoisting
- **Structure:** `/src/apps/*`, `/src/packages/*`, `/tests/*`

### Build Orchestration: Under Evaluation

**Option A: Turborepo**
- **Pros:** Fast incremental builds, remote caching, simple config
- **Cons:** Vercel-owned (vendor lock-in risk)

**Option B: Nx**
- **Pros:** Advanced dependency graph, affected commands, plugins
- **Cons:** Steeper learning curve, more complex config

**Decision Timeline:** Start with npm workspaces alone. Evaluate Turborepo/Nx if build times become bottleneck (unlikely at current scale).

## 10. Development Tools

### Code Quality
- **ESLint:** Enforce coding standards, catch common mistakes
- **Prettier:** Consistent formatting (no debates on tabs vs. spaces)
- **Rationale:** Automated code reviews reduce friction, onboarding time

### Pre-Commit Hooks
- **Husky:** Git hook management
- **lint-staged:** Run linters only on changed files
- **Rationale:** Fast feedback loop, prevents broken commits reaching CI

### TypeScript Configuration
- **Strict Mode:** All strict flags enabled
- **No Implicit Any:** Forces explicit types
- **Rationale:** Type safety as first-class citizen, not opt-in feature

### Runtime Validation
- **Zod:** Schema definition, runtime validation, type inference
- **Use Cases:**
  - API request/response validation
  - Environment variable parsing
  - Form validation (shared between frontend/backend)
- **Rationale:** Single source of truth for data shapes, generates TypeScript types automatically

---

## Decision Status Summary

**Finalized:**
- Language: TypeScript (strict mode)
- Runtime: Node.js 20+
- Database: PostgreSQL 15+
- Auth: iRacing OAuth + JWT
- Companion: Electron + Nut.js
- Testing: Vitest + Playwright + Test Containers
- Infra: Docker + Redis + S3/MinIO
- Monorepo: npm workspaces
- Dev Tools: ESLint + Prettier + Husky + Zod

**Under Evaluation (Deferred to Implementation):**
- Backend framework: Express vs. Fastify vs. Hono
- Frontend framework: React + Vite vs. Next.js
- ORM: Prisma vs. TypeORM
- Build orchestration: Turborepo vs. Nx (if needed)
- CI/CD: GitHub Actions vs. GitLab CI

**Deferred Decisions Rationale:**
- Backend/frontend frameworks: Choice depends on deployment target (cloud vs. edge vs. self-hosted)
- ORM: Both options integrate cleanly with Clean Architecture; decision based on team preference during implementation
- Build tools: Optimize when proven bottleneck (YAGNI principle)

---

## Cross-References

- **Architecture Patterns:** See [ARCHITECTURE.md](./ARCHITECTURE.md) for how these technologies map to Clean Architecture layers
- **Project Overview:** See [CONCEPT.md](./CONCEPT.md) for business context driving technology choices
- **Setup Instructions:** See [README.md](../README.md) for installation and getting started

---

*Last Updated: 2025-11-21*