Swiss Volleyball Scouting Platform Development Guide
You are assisting with **Habicht (UniSports)**, a Next.js 14/React/TypeScript platform for Swiss volleyball scouting. The platform supports player and recruiter roles, Swiss club integration, video uploads via Cloudinary, and CV generation.
Project Architecture
Directory Structure
**`app/`** — Next.js 14 app directory routes and pages**`components/`** — UI components (player, shared, modals)**`lib/`** — Helper functions, Prisma client, business logic**`prisma/`** — Database schema and migrations**`scripts/`** — Data import/export utilities (see `scripts/README.md`)**`data/`** — Static JSON files (Swiss clubs, cantons, leagues)**`contexts/`** — React contexts (language, theme, auth)**`types/`** — TypeScript type definitionsTechnology Stack
**Frontend**: Next.js 14 (app directory), React, TypeScript, Tailwind CSS**Backend**: Next.js API routes (`app/api/`)**Database**: PostgreSQL with Prisma ORM (`prisma/schema.prisma`)**Authentication**: NextAuth.js (see `app/api/auth/` and `types/next-auth.d.ts`)**File Storage**: Cloudinary for images and videos**Deployment**: Vercel (see `VERCEL_SETUP.md`)Key Data Flows
1. **Player Registration** → Profile creation → Club matching → Video uploads → CV export
2. **Recruiter Access** → Player search → Video viewing → Contact requests
3. **Swiss Club Integration** → Club data (`lib/clubsDatabase.ts`) → Matching logic (`lib/clubMatcher.ts`) → Player profiles
Development Workflow
Setup Commands
```bash
Install dependencies
npm install
Start development server
npm run dev
Build for production
npm run build
Push database schema changes
npm run db:push
Open Prisma Studio
npm run db:studio
Run data import scripts
npx ts-node scripts/<script-name>.ts
```
Database Management
Schema defined in `prisma/schema.prisma`After schema changes, run `npm run db:push` to sync databaseUse Prisma Studio (`npm run db:studio`) for data inspectionSee `scripts/README.md` for scraping and importing player dataCode Conventions
TypeScript
All business logic and components must be fully typedExtend types in `types/` directory as neededReference `types/next-auth.d.ts` for auth session typesStyling
Use Tailwind CSS utility classes exclusivelyNo custom CSS files unless absolutely necessaryFollow existing component patterns for consistencyReact Patterns
Use React Context for global state (language, theme, auth)Server components by default; use `"use client"` directive only when neededDynamic routes follow pattern: `app/[resource]/[id]/page.tsx`API Integration
Use axios or native fetch for client-server communicationAPI helpers in `lib/` directoryFollow RESTful conventions for new endpointsSwiss-Specific Features
Club Integration
**Club database**: `lib/clubsDatabase.ts` — Static data and club linking logic**Club matcher**: `lib/clubMatcher.ts` — Matches players to Swiss clubs**Data files**: `data/` — Canton, league, and club static dataPlayer Features
**Video upload**: `components/player/VideoUpload.tsx` with Cloudinary integration**CV export**: `lib/generateCV.ts` — Player CV generation**Profile**: Dynamic routing via `app/players/[id]/page.tsx`Recruiter Features
**CV export**: `lib/generateRecruiterCV.ts` — Recruiter CV generation**Player search**: Filter by club, position, canton, league**Hybrid profiles**: `app/hybrids/[id]/page.tsx` for dual player/recruiter rolesIntegration Configuration
Environment Variables
Configure in `.env`:
**Cloudinary**: For image/video uploads**Swiss Volley API**: Optional integration for official data**Database**: PostgreSQL connection string**NextAuth**: Authentication secrets and providersExternal Services
**Cloudinary**: Upload helpers in `lib/` — use for all media uploads**Swiss Volley API**: Optional; check `lib/` for usage patterns**Club websites**: Linking logic in `lib/clubMatcher.ts` and `lib/clubsDatabase.ts`Common Development Tasks
Adding a New Feature
1. Update `prisma/schema.prisma` if new data models needed
2. Run `npm run db:push` to sync database
3. Create API routes in `app/api/[feature]/`
4. Build UI components in `components/[feature]/`
5. Add types to `types/` directory
6. Follow Next.js app directory conventions
Working with Player Data
1. Reference `scripts/README.md` for import workflows
2. Use `scripts/import-volleybox-data.ts` for external data sources
3. Test club matching logic with `lib/clubMatcher.ts`
4. Validate Swiss-specific data (cantons, leagues) against `data/` files
UI Component Development
Reference existing patterns in `components/shared/`For modals, see `components/shared/BackgroundPickerModal.tsx`Use TypeScript props interfaces for all componentsApply Tailwind classes for stylingDatabase Changes
1. Modify `prisma/schema.prisma`
2. Run `npm run db:push` (development) or create migration (production)
3. Update TypeScript types if needed
4. Test with Prisma Studio
Key File References
Dynamic Routes
`app/players/[id]/page.tsx` — Player profile page`app/hybrids/[id]/page.tsx` — Hybrid player/recruiter profile`app/api/players/` — Player API endpoints`app/api/videos/` — Video management endpointsBusiness Logic
`lib/clubsDatabase.ts` — Swiss club data and helpers`lib/clubMatcher.ts` — Club matching algorithm`lib/generateCV.ts` — Player CV export`lib/generateRecruiterCV.ts` — Recruiter CV exportComponents
`components/player/VideoUpload.tsx` — Video upload interface`components/shared/BackgroundPickerModal.tsx` — Modal pattern exampleData Import
`scripts/import-volleybox-data.ts` — External data import`scripts/README.md` — Complete data workflow documentationBest Practices
1. **Always type your code** — No `any` types unless absolutely necessary
2. **Follow Next.js conventions** — Use app directory structure and file-based routing
3. **Swiss-specific logic** — Check `lib/` and `data/` before implementing club/canton/league features
4. **Cloudinary for uploads** — Never implement custom file storage
5. **Prisma for database** — Use ORM features; avoid raw SQL unless required
6. **Tailwind for styling** — Maintain design consistency with utility classes
7. **Reference existing patterns** — Check similar features before implementing new ones
8. **Read documentation** — `README.md` and `scripts/README.md` for workflows
Troubleshooting
**Database issues**: Check Prisma schema and run `npm run db:push`**Club matching failures**: Validate data in `lib/clubsDatabase.ts`**Upload errors**: Verify Cloudinary configuration in `.env`**Auth problems**: Review NextAuth setup in `app/api/auth/` and `types/next-auth.d.ts`**Build errors**: Check TypeScript types and Next.js app directory structureFor detailed questions or issues, consult `README.md` or open a GitHub issue in the repository.