# Implementation Plan: Jury Voting

## Overview

Build a full-stack web application for the 15. UNIKAT Ideenwettbewerb jury voting process. The app enables 6 jurors to score 11 teams on 5 criteria (1–10) via smartphones, with real-time results displayed on a beamer. Stack: React 19 + Vite frontend, Express.js backend, JSON file persistence, SSE for live updates. TypeScript throughout.

## Tasks

- [x] 1. Project scaffolding and configuration
  - [x] 1.1 Initialize Vite + React 19 + TypeScript project in `Jury-Voting/`
    - Run `npm create vite@latest` with React + TypeScript template
    - Configure `vite.config.ts` with proxy to Express backend (port 3001)
    - Add dependencies: `react-router-dom`, `lucide-react`
    - Add dev dependencies: `vitest`, `fast-check`, `@testing-library/react`, `jsdom`
    - _Requirements: 5.2 (dark theme, Outfit font, glassmorphism)_

  - [x] 1.2 Set up Express.js backend in `Jury-Voting/server/`
    - Create `server/` directory with TypeScript configuration
    - Install: `express`, `cors`, `tsx` (for dev), `typescript`
    - Create `server/index.ts` entry point with basic Express app on port 3001
    - Add `npm run dev:server` script using `tsx watch`
    - _Requirements: 3.1 (score persistence)_

  - [x] 1.3 Define shared TypeScript interfaces in `Jury-Voting/shared/types.ts`
    - Create `Session`, `Team`, `Juror`, `Criterion`, `Score`, `TeamResult`, `PendingScore` interfaces
    - Create `SessionConfig` interface with criteria and scale settings
    - Export all types for use by both frontend and backend
    - _Requirements: 6.2, 6.3 (configurable teams, criteria, scale)_

  - [x] 1.4 Create seed data file `Jury-Voting/server/data/seed.json`
    - Pre-populate 11 teams from `Teams/` folder (id, number, name, description)
    - Pre-populate 6 jurors (Cielejewski, Finke, Freyer, Knie, Meyer, Trieschmann)
    - Pre-populate 5 criteria (Gesamtidee, Kundennutzen, Markt, Realisierbarkeit, Präsentation)
    - Set default session config (scale 1–10)
    - _Requirements: 6.2, 6.3, 6.6_

- [x] 2. Backend data layer and core logic
  - [x] 2.1 Implement JSON file store (`server/store.ts`)
    - Read/write `server/data/session.json` atomically (write to temp, rename)
    - Create `.bak` backup before each write
    - Initialize from `seed.json` if `session.json` doesn't exist
    - Expose typed read/write functions for session, teams, jurors, scores
    - _Requirements: 3.1, 3.2 (persistence, reliability)_

  - [x] 2.2 Implement score aggregation logic (`server/aggregation.ts`)
    - `calculateTeamResult(teamId, scores[])` → total, average, jurorCount, complete
    - `calculateRankings(teamResults[])` → sorted results with dense ranking (ties get same rank)
    - `getCompletionStatus(jurorId, teamId, scores[])` → 'complete' | 'partial' | 'pending'
    - Pure functions, no side effects — easy to test
    - _Requirements: 4.2, 4.3, 4.4, 4.5_

  - [ ]* 2.3 Write property test: Score Aggregation Correctness
    - **Property 4: Score Aggregation Correctness**
    - Generate random valid scores (1–10) for arbitrary juror/team/criterion combinations
    - Assert: total equals arithmetic sum of all score values for a team
    - Assert: average equals total / distinct jurors who scored
    - **Validates: Requirements 4.2, 4.3**

  - [ ]* 2.4 Write property test: Ranking Correctness with Ties
    - **Property 5: Ranking Correctness with Ties**
    - Generate random team totals, compute rankings
    - Assert: rankings sorted descending by total
    - Assert: equal totals receive equal rank numbers
    - **Validates: Requirements 4.4, 4.5**

  - [ ]* 2.5 Write property test: Team Completion Status
    - **Property 1: Team Completion Status**
    - Generate random subsets of criteria scores for a juror-team pair
    - Assert: 5 scores → 'complete', 1–4 → 'partial', 0 → 'pending'
    - **Validates: Requirements 2.4, 7.1**

  - [x] 2.6 Implement last-write-wins conflict resolution (`server/conflict.ts`)
    - Compare timestamps on incoming score vs stored score
    - Accept score with later `updatedAt` timestamp
    - Return conflict info (409) if client sends older timestamp without force flag
    - _Requirements: 3.3, 3.4_

  - [ ]* 2.7 Write property test: Last-Write-Wins Score Resolution
    - **Property 3: Last-Write-Wins Score Resolution**
    - Generate sequences of score updates with varying timestamps for same (jurorId, teamId, criterionId)
    - Assert: final persisted value equals the value with the most recent timestamp
    - **Validates: Requirements 3.3**

- [ ] 3. Backend API endpoints
  - [x] 3.1 Implement session endpoints
    - `GET /api/session` — return current session state
    - `POST /api/session/start` — set status to 'active', record startedAt
    - `POST /api/session/end` — set status to 'ended', record endedAt
    - Validate: cannot start if already active, cannot end if not active
    - _Requirements: 6.4, 6.5_

  - [x] 3.2 Implement team and juror endpoints
    - `GET /api/teams` — return all teams
    - `GET /api/jurors` — return all jurors
    - _Requirements: 6.2, 6.6_

  - [x] 3.3 Implement score endpoints
    - `POST /api/scores` — submit/update a score (validate: session active, score 1–10, valid jurorId/teamId/criterionId)
    - `GET /api/scores/:jurorId` — return all scores for a juror
    - `GET /api/scores` — return all scores (admin only)
    - On successful score submission, trigger SSE broadcast
    - _Requirements: 2.3, 3.1, 3.3_

  - [ ]* 3.4 Write property test: Session Gate
    - **Property 6: Session Gate**
    - Generate score submissions with random session states ('setup', 'active', 'ended')
    - Assert: accepted if and only if session status is 'active'
    - **Validates: Requirements 6.4, 6.5**

  - [x] 3.5 Implement results and progress endpoints
    - `GET /api/results` — return aggregated TeamResult[] with rankings
    - `GET /api/progress` — return juror completion matrix (jurorId → count of fully-scored teams)
    - `GET /api/export/csv` — generate and return CSV file
    - Progress endpoint must NOT include individual score values
    - _Requirements: 4.1, 7.1, 7.3, 8.1_

  - [ ]* 3.6 Write property test: Progress Privacy
    - **Property 7: Progress Privacy**
    - Generate random score sets, call progress endpoint logic
    - Assert: response contains juror completion counts but no individual score values
    - **Validates: Requirements 7.3**

- [x] 4. SSE real-time infrastructure
  - [x] 4.1 Implement SSE endpoint (`server/sse.ts`)
    - `GET /api/results/stream` — establish SSE connection
    - Maintain list of connected clients
    - On score change, broadcast `scores_updated` event with full results payload
    - Handle client disconnect (remove from list)
    - Set appropriate headers: `Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`
    - _Requirements: 4.1, 5.3_

  - [x] 4.2 Create frontend SSE hook (`src/hooks/useSSE.ts`)
    - Custom React hook that connects to `/api/results/stream`
    - Parse incoming events and update local state
    - Auto-reconnect on connection loss (EventSource built-in)
    - Return: `{ results, connected, lastUpdate }`
    - _Requirements: 5.3 (update within 2 seconds without page refresh)_

- [x] 5. Checkpoint - Backend complete
  - Ensure all tests pass, ask the user if questions arise.

- [x] 6. Frontend: Juror selection and routing
  - [x] 6.1 Set up React Router with route structure
    - Configure routes: `/`, `/vote`, `/vote/:teamId`, `/results`, `/admin`
    - Create `App.tsx` with `BrowserRouter` and route definitions
    - Create layout wrapper with dark theme base styles
    - _Requirements: 1.1, 2.1_

  - [x] 6.2 Implement `JurorSelect` page (`src/pages/JurorSelect.tsx`)
    - Fetch juror list from `GET /api/jurors`
    - Display 6 juror names as large glass-panel cards (tap targets for mobile)
    - On selection: store jurorId in localStorage, navigate to `/vote`
    - Show warning if juror already has active session (allow override)
    - _Requirements: 1.1, 1.2, 1.3, 1.4_

  - [ ]* 6.3 Write unit tests for JurorSelect
    - Test: renders 6 juror names
    - Test: selection stores jurorId and navigates
    - Test: shows conflict warning for active juror
    - _Requirements: 1.1, 1.2, 1.3_

- [ ] 7. Frontend: Voting interface
  - [x] 7.1 Implement `VotingDashboard` page (`src/pages/VotingDashboard.tsx`)
    - Fetch teams from `GET /api/teams` and scores from `GET /api/scores/:jurorId`
    - Display 11 `TeamCard` components in a scrollable list
    - Each card shows: team name, description snippet, status icon (✓ complete / ◐ partial / ○ pending)
    - Tap card navigates to `/vote/:teamId`
    - _Requirements: 2.1, 2.4, 2.5_

  - [x] 7.2 Implement `TeamScoring` page (`src/pages/TeamScoring.tsx`)
    - Display team name and description at top
    - Render 5 `ScoreSlider` components (one per criterion)
    - Each slider: range 1–10, shows current value, large touch target
    - Auto-save on change with 300ms debounce
    - Show green flash confirmation on successful save
    - Prev/Next team navigation buttons
    - _Requirements: 2.2, 2.3, 2.5_

  - [x] 7.3 Implement offline score queue (`src/hooks/useOfflineQueue.ts`)
    - On score change: save to localStorage `pendingScores` array immediately
    - Attempt POST to `/api/scores` — on success, mark as synced
    - On network failure: keep in queue, show subtle "offline" indicator
    - On reconnect: replay pending scores in order
    - Exponential backoff for retries (max 3 attempts per score)
    - _Requirements: 3.1, 3.2_

  - [ ]* 7.4 Write property test: Offline Queue Preservation
    - **Property 2: Offline Queue Preservation**
    - Generate random sequences of scores submitted while "offline"
    - Simulate sync, assert all scores present on server with original values/timestamps
    - **Validates: Requirements 3.2**

  - [ ]* 7.5 Write unit tests for TeamScoring
    - Test: renders 5 criteria with correct labels
    - Test: auto-saves on slider change (debounced)
    - Test: shows confirmation flash on save
    - Test: prev/next navigation works
    - _Requirements: 2.2, 2.3_

- [ ] 8. Frontend: Results view (beamer)
  - [x] 8.1 Implement `ResultsView` page (`src/pages/ResultsView.tsx`)
    - Full-screen layout, no navigation chrome
    - Connect to SSE via `useSSE` hook
    - Display `RankingTable` component with animated transitions
    - Show "Voting in Progress" or "Final Results" based on session status
    - Optimized for 1920×1080 landscape projection
    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6_

  - [x] 8.2 Implement `RankingTable` component (`src/components/RankingTable.tsx`)
    - Display ranked list: rank, team name, total score, average score
    - Animate rank changes (CSS transitions on position)
    - Highlight top 3 teams with special styling
    - Handle ties (same rank number displayed)
    - _Requirements: 4.4, 4.5, 5.4_

  - [ ]* 8.3 Write property test: Results Display Completeness
    - **Property 9: Results Display Completeness**
    - Generate random TeamResult objects, render ResultsView
    - Assert: each team's name, total, average, and rank are present in rendered output
    - **Validates: Requirements 5.4**

- [ ] 9. Frontend: Admin panel
  - [x] 9.1 Implement `AdminPanel` page (`src/pages/AdminPanel.tsx`)
    - Session controls: Start Voting / End Voting buttons with confirmation dialogs
    - Show current session status and timestamps
    - Warning when ending session with incomplete scores
    - _Requirements: 6.1, 6.4, 6.5_

  - [x] 9.2 Implement `ProgressMatrix` component (`src/components/ProgressMatrix.tsx`)
    - Fetch from `GET /api/progress`
    - Display 6×11 grid (jurors × teams) with completion indicators
    - Show per-juror totals (X/11 teams complete)
    - Indicate when all voting is complete (6/6 jurors × 11/11 teams)
    - No individual scores shown — only completion status
    - _Requirements: 7.1, 7.2, 7.3_

  - [x] 9.3 Implement CSV export functionality
    - Export button calls `GET /api/export/csv` and triggers download
    - CSV format: teams as rows, (juror × criterion) as columns, plus totals/averages/ranks
    - Match structure of original Auswertungstabelle
    - _Requirements: 8.1, 8.2, 8.3, 8.4_

  - [ ]* 9.4 Write property test: Export Round-Trip
    - **Property 8: Export Round-Trip**
    - Generate complete score sets, export to CSV, parse CSV back
    - Assert: all individual scores recovered, totals correct, averages correct, rankings correct
    - **Validates: Requirements 8.1, 8.2, 8.3, 8.4**

- [x] 10. Checkpoint - Core features complete
  - Ensure all tests pass, ask the user if questions arise.

- [ ] 11. Styling and visual polish
  - [x] 11.1 Implement global theme and CSS variables
    - Define CSS custom properties: `--bg-primary: #0a0a0a`, `--accent: #00FF00`, glassmorphism values
    - Import Outfit font from Google Fonts
    - Set up glassmorphism utility classes (backdrop-filter, border, shadow)
    - Dark scrollbar styling, smooth transitions
    - _Requirements: 5.2_

  - [x] 11.2 Style all components to match Projekt-KIQ-HP design
    - JurorSelect: glass-panel cards with hover/tap glow effect
    - VotingDashboard: team cards with status indicators, neon green accents
    - TeamScoring: custom slider styling (neon green track), score display
    - ResultsView: large typography, animated rank transitions, glassmorphism table
    - AdminPanel: clean grid layout, status badges
    - Mobile-first responsive design (320px–428px primary, scales up)
    - _Requirements: 2.1, 5.1, 5.2_

- [ ] 12. Deployment configuration
  - [x] 12.1 Create production build setup
    - Configure Vite to build static assets to `dist/`
    - Configure Express to serve static files from `dist/` in production
    - Single-port deployment: Express serves both API and frontend
    - Add `npm run build` and `npm start` scripts
    - _Requirements: all (deployment readiness)_

  - [x] 12.2 Create `docker-compose.yml` for containerized deployment
    - Single container: Node.js serving Express + static frontend
    - Volume mount for `server/data/` (persist scores across restarts)
    - Expose port 3001 (or configurable via env)
    - Add `.dockerignore` and `Dockerfile`
    - _Requirements: all (deployment readiness)_

- [x] 13. Final checkpoint - All features complete
  - Ensure all tests pass, ask the user if questions arise.

## Notes

- Tasks marked with `*` are optional property-based tests — skip for faster MVP delivery given the tight timeline (event: 19. Mai 2026)
- Each task references specific requirements for traceability
- Checkpoints at tasks 5, 10, and 13 ensure incremental validation
- Property tests validate the 9 correctness properties from the design document
- The app is designed for single-event use — simplicity over scalability
- All seed data (teams, jurors, criteria) is pre-populated; no manual setup needed at event time