105 lines
5.0 KiB
Markdown
105 lines
5.0 KiB
Markdown
# NVJ Turnierplaner - AI Coding Agent Instructions
|
|
|
|
## Project Overview
|
|
Volleyball tournament organizer (NVJ = Netzroller Volleyball Jugend) for managing teams, rounds, and scoring across two league types: Bundesliga and Champions League. Built with React/TypeScript.
|
|
|
|
## Architecture
|
|
|
|
### State Management Pattern
|
|
Single global context provider in [src/context/TournamentContext.tsx](src/context/TournamentContext.tsx):
|
|
- **TournamentProvider** wraps entire app in [App.tsx](src/App.tsx)
|
|
- Access via `useTournament()` hook - throws error if used outside provider
|
|
- State includes: teams, rounds, field count, match results
|
|
- **Critical**: Use `crypto.randomUUID()` for all new IDs (teams, matches, rounds)
|
|
|
|
### Data Flow
|
|
1. Teams created on Index page → stored in context
|
|
2. `generateMatches()` utility distributes teams across fields/leagues
|
|
3. Rounds track match results and waiting teams
|
|
4. Scores calculated via point differential: `pointsA = -(scoreB - scoreA)`, `pointsB = (scoreB - scoreA)`
|
|
|
|
### Type System ([src/types/tournament.ts](src/types/tournament.ts))
|
|
- **League**: `'bundesliga' | 'champions'` - string literal types only
|
|
- **Match** includes `result?: MatchResult` - undefined until scores entered
|
|
- **Round** has `completed: boolean` - only one active round allowed at a time
|
|
- **TeamScore** maintains `pointsHistory: number[]` for per-round tracking
|
|
|
|
## Development Workflow
|
|
|
|
### Running the App
|
|
```bash
|
|
npm run dev # Start development server on port 8080
|
|
npm run build # Production build
|
|
npm run build:dev # Development mode build
|
|
npm run test # Run Vitest once
|
|
npm run test:watch # Watch mode for tests
|
|
```
|
|
|
|
### Vite Configuration
|
|
- **Path alias**: `@/` maps to `src/` (configured in [vite.config.ts](vite.config.ts))
|
|
- **React deduplication**: Critical for preventing hook errors - never remove from config
|
|
|
|
## UI Component Conventions
|
|
|
|
### shadcn/ui Pattern
|
|
- All UI primitives in [src/components/ui/](src/components/ui/) - **do not edit** these directly
|
|
- Import from `@/components/ui/<component>`
|
|
- Customization via Tailwind classes and variants, not component modification
|
|
|
|
### Design System ([src/index.css](src/index.css))
|
|
**Custom CSS tokens** (use these instead of arbitrary values):
|
|
- `card-apple` - Standard card styling (rounded-2xl, shadow, border)
|
|
- `card-apple-hover` - Interactive card with hover effects
|
|
- `bg-bundesliga` / `bg-champions` - League-specific colors with matching foregrounds
|
|
- `bg-waiting` / `bg-field` - Status colors for team/field states
|
|
|
|
**Color semantics**:
|
|
- Bundesliga: Red theme (`--bundesliga: 0 72% 51%`)
|
|
- Champions: Gold/yellow theme (`--champions: 45 93% 47%`)
|
|
- Field: Green (`--field: 142 71% 45%`)
|
|
- All have HSL definitions in CSS custom properties
|
|
|
|
### Component Structure Pattern
|
|
See [src/components/TournamentView.tsx](src/components/TournamentView.tsx) for reference:
|
|
- Extract sub-components within file for local use (`WaitingTeam`, `LeagueSection`)
|
|
- Use typed icon props: `icon: typeof Trophy` instead of React.ComponentType
|
|
- Filter round data at component level, not in context
|
|
|
|
## Key Files & Responsibilities
|
|
|
|
- [src/utils/tournamentUtils.ts](src/utils/tournamentUtils.ts) - Match generation with field distribution logic
|
|
- [src/context/TournamentContext.tsx](src/context/TournamentContext.tsx) - All tournament state mutations
|
|
- [src/pages/Index.tsx](src/pages/Index.tsx) - Team setup interface
|
|
- [src/pages/Tournament.tsx](src/pages/Tournament.tsx) - Active tournament management
|
|
- [src/components/MatchScoreInput.tsx](src/components/MatchScoreInput.tsx) - Score entry with point calculation
|
|
|
|
## Project-Specific Rules
|
|
|
|
1. **Never modify completed rounds** - `completed: true` rounds are immutable
|
|
2. **Field allocation**: Bundesliga and Champions always share fields evenly (±1) when both have teams
|
|
3. **Waiting teams**: Odd-numbered teams in a league → last team waits (see `createMatchesForLeague`)
|
|
4. **Score point mapping**: Differential-based, not win/loss binary
|
|
5. **Component naming**: PascalCase files match export name exactly
|
|
6. **Routing**: Custom routes MUST be above `path="*"` catch-all in [App.tsx](App.tsx)
|
|
|
|
## Dependencies Notes
|
|
|
|
- **Bun runtime**: Package manager is Bun (uses bun.lockb), but npm scripts work
|
|
- **React Router**: v6 pattern with BrowserRouter
|
|
- **React Query**: QueryClient setup in App.tsx but minimal usage currently
|
|
- **Lucide React**: Icon library of choice (see imports in components)
|
|
- **Sonner + shadcn Toast**: Dual toast systems - prefer Sonner for new toasts
|
|
|
|
## Testing
|
|
|
|
- Vitest + Testing Library configured ([vitest.config.ts](vitest.config.ts))
|
|
- Test setup in [src/test/setup.ts](src/test/setup.ts)
|
|
- Run with `npm run test:watch` for development
|
|
|
|
## Common Pitfalls
|
|
|
|
- Don't destructure `useTournament()` before checking context existence
|
|
- TypeScript paths require build tool awareness - always use `@/` imports
|
|
- Custom CSS utilities won't work without `@layer utilities` wrapper
|
|
- Dark mode is class-based - test both light/dark themes
|