# Requirements Document

## Introduction

This feature replaces the paper-based jury evaluation process (Bewertungsbogen and Auswertungstabelle) for the **15. UNIKAT Ideenwettbewerb** with a digital, mobile-friendly voting application. A panel of **6 jurors** evaluates **11 teams** via their smartphones during the Prämierungsfeier on **19. Mai 2026, 18 Uhr** at **Science Park Kassel, Universitätsplatz 12** (hosted by Universität Kassel). Results are displayed in real time on a beamer/projector for the audience.

**Scoring system:** 5 equally-weighted criteria, each scored on a 1–10 scale (configurable). Maximum score per juror per team: 50. Aggregation: simple sum across all jurors, average = total / number of jurors.

**Visual design basis:** Projekt-KIQ-HP (React 19 + Vite) — dark theme (#0a0a0a background), neon green accents (#00FF00), glassmorphism panels, Outfit font, lucide-react icons. Premium event look.

**Tech stack:** React 19 + Vite, react-router-dom, lucide-react icons. NO Supabase — use a lightweight real-time backend (e.g., simple JSON server, or localStorage + polling for MVP since only 6 jurors).

**Reference documents (in repo):**
- `Jury-Voting/Teams/` — folder containing team/project descriptions (11 teams)
- `Jury-Voting/UNIKAT_IDEENWETTBEWERB_2026_Einladung_Prämierungsfeier.pdf` — event invitation
- `Jury-Voting/Bewertungsbogen Jury 2026.doc` — the paper scoring form (5 criteria, 1–10 scale)
- `Jury-Voting/Auswertungstabelle 2026.xlsx` — the paper results table (simple sum aggregation)

## Glossary

- **Voting_App**: The web application that jurors and the audience interact with
- **Juror**: A registered panel member who submits scores for each team (6 jurors this year: Cielejewski, Finke, Freyer, Knie, Meyer, Trieschmann)
- **Team**: A team/product/concept being evaluated (11 total in the current event)
- **Score**: A numeric rating (1–10) a juror assigns to a team for a given criterion
- **Criterion**: A dimension on which a team is evaluated (5 criteria: Gesamtidee, Kundennutzen, Markt, Realisierbarkeit, Präsentation)
- **Voting_Session**: A time-bounded event during which jurors submit their scores
- **Results_View**: The projector-optimized page that displays aggregated scores and rankings
- **Admin**: The person who configures the session, manages jurors, and controls the results display

## Concrete Event Data

### Jurors (6)

| # | Name |
|---|------|
| 1 | Cielejewski |
| 2 | Finke |
| 3 | Freyer |
| 4 | Knie |
| 5 | Meyer |
| 6 | Trieschmann |

### Teams (11)

| # | Team Name | Description | Contact |
|---|-----------|-------------|---------|
| 1 | Anima Lektor | Lektor for game language/text | Lukas Fleck |
| 2 | Das Any-Thing | Physical AI automaton that adapts to context | — |
| 3 | Doppelrad-Sortierer | AI-powered seed sorting machine for niche producers | — |
| 4 | DUAL | Fully reversible wood construction system | Nicole Kozlewski, Sebastian Görs |
| 5 | fömo | Funding management platform for social institutions | — |
| 6 | ISOmedi | Compact rechargeable medication case with protective micro-environment | — |
| 7 | Lian's Tempeh Chips | Tempeh-based snack product | Dr. Berlianti Puteri |
| 8 | Lumpen | Sustainable upholstery material from old clothing textiles | — |
| 9 | Mobile Sprinkleranlage | Mobile sprinkler system for fire protection | Björn Knoke |
| 10 | SafeSupply OS | Lightweight supplier risk & audit system for agri-food SMEs | Jesvin Jaksan |
| 11 | Second Nose | Digital smell detection module for smartphones | — |

### Scoring Criteria (5, equally weighted)

| # | Criterion (DE) | Criterion (EN) |
|---|----------------|----------------|
| 1 | Gesamtidee | Overall Idea |
| 2 | Kundennutzen | Customer Benefit |
| 3 | Markt | Market |
| 4 | Realisierbarkeit | Feasibility |
| 5 | Präsentation | Presentation |

**Scale:** 1–10 per criterion (configurable, default 1–10)
**Max per juror per team:** 50 points
**Aggregation:** Simple sum. Per-team total = sum of all juror scores. Average = total / 6.

### Presentation Schedule (partial, from Gesamtauswertung)

| Time | Team |
|------|------|
| 15:10–15:30 | DUAL |
| 16:10–16:30 | fömo |
| 16:30–16:50 | Lumpen (inferred) |
| 16:50–17:10 | Das Any-Thing |
| 17:10–17:30 | Doppelrad-Sortierer |
| 17:45–18:05 | Anima Lektor |
| 18:05–18:25 | Mobile Sprinkleranlage |

## Requirements

### Requirement 1: Juror Authentication

**User Story:** As a juror, I want a simple way to identify myself when I open the app on my phone, so that my votes are attributed to me without a complex login flow.

#### Acceptance Criteria

1. WHEN a juror opens the Voting_App on a mobile device, THE Voting_App SHALL present a juror selection list showing the 6 registered juror names (Cielejewski, Finke, Freyer, Knie, Meyer, Trieschmann)
2. WHEN a juror selects their name from the list, THE Voting_App SHALL grant access to the voting interface within 3 seconds
3. IF a juror selects a name that is already in use by another active session, THEN THE Voting_App SHALL display a warning and allow override or retry
4. THE Voting_App SHALL support 6 concurrent jurors in a single Voting_Session

### Requirement 2: Mobile-Friendly Voting Interface

**User Story:** As a juror, I want to score each team on my smartphone quickly and intuitively, so that the evaluation process is faster than the paper form.

#### Acceptance Criteria

1. THE Voting_App SHALL render a responsive voting interface optimized for mobile viewports (320px–428px width)
2. WHEN a juror navigates to a team, THE Voting_App SHALL display all 5 scoring criteria (Gesamtidee, Kundennutzen, Markt, Realisierbarkeit, Präsentation) with a 1–10 input for each
3. WHEN a juror selects a score for a criterion, THE Voting_App SHALL persist the score immediately without requiring a separate save action
4. THE Voting_App SHALL display all 11 teams in a navigable list with clear indication of which teams have been scored and which are pending
5. WHILE a juror is scoring a team, THE Voting_App SHALL display the team name and short description

### Requirement 3: Score Persistence and Conflict Handling

**User Story:** As a juror, I want my scores to be saved reliably even if my phone loses connection briefly, so that no votes are lost.

#### Acceptance Criteria

1. WHEN a juror submits a score, THE Voting_App SHALL persist the score to the server within 2 seconds under normal network conditions
2. IF the network connection is lost, THEN THE Voting_App SHALL store scores locally and synchronize them when connectivity is restored
3. WHEN a juror changes a previously submitted score, THE Voting_App SHALL overwrite the previous value with the new score
4. THE Voting_App SHALL prevent a juror from submitting scores for the same criterion on the same team more than once without explicit overwrite intent

### Requirement 4: Real-Time Results Aggregation

**User Story:** As an admin, I want the results to update in real time as jurors submit scores, so that the audience sees a live leaderboard on the projector.

#### Acceptance Criteria

1. WHEN a new score is persisted, THE Voting_App SHALL recalculate the aggregated result for the affected team within 1 second
2. THE Voting_App SHALL calculate a total score per team by summing all juror scores across all 5 criteria (simple sum, max possible = 6 jurors × 5 criteria × 10 points = 300)
3. THE Voting_App SHALL calculate an average score per team (total / number of jurors who have scored)
4. THE Voting_App SHALL rank teams from highest to lowest total score
5. IF two or more teams have the same total score, THEN THE Voting_App SHALL display them with equal rank

### Requirement 5: Beamer/Projector Results Display

**User Story:** As an event organizer, I want a dedicated results page optimized for projection on a large screen, so that the audience can follow the voting live.

#### Acceptance Criteria

1. THE Results_View SHALL be optimized for landscape display at 1920×1080 resolution
2. THE Results_View SHALL use the dark theme (#0a0a0a background) with neon green (#00FF00) accents, glassmorphism panels, and Outfit font for a premium event look
3. WHEN aggregated scores change, THE Results_View SHALL update the displayed rankings within 2 seconds without requiring a page refresh
4. THE Results_View SHALL display each team name, its total score, its average score, and its current rank
5. WHILE a Voting_Session is active, THE Results_View SHALL indicate that voting is in progress
6. WHEN a Voting_Session ends, THE Results_View SHALL display the final rankings with a clear "Final Results" indicator

### Requirement 6: Session Management

**User Story:** As an admin, I want to configure and control the voting session, so that I can set up teams, criteria, and start/stop voting at the right time.

#### Acceptance Criteria

1. THE Voting_App SHALL provide an admin interface to create and configure a Voting_Session
2. WHEN an admin creates a Voting_Session, THE Voting_App SHALL allow configuration of team names and descriptions (pre-populated with the 11 teams for this event)
3. WHEN an admin creates a Voting_Session, THE Voting_App SHALL allow configuration of scoring criteria and their scale (pre-populated with 5 criteria, 1–10 scale)
4. WHEN an admin starts a Voting_Session, THE Voting_App SHALL enable score submission for all 6 registered jurors
5. WHEN an admin ends a Voting_Session, THE Voting_App SHALL disable further score submission and mark results as final
6. THE Voting_App SHALL allow the admin to register jurors by name (pre-populated with the 6 jurors for this event)

### Requirement 7: Voting Progress Visibility

**User Story:** As an admin, I want to see which jurors have completed their scoring, so that I know when all votes are in and I can close the session.

#### Acceptance Criteria

1. THE Voting_App SHALL display a progress overview showing how many of the 11 teams each juror has fully scored (all 5 criteria submitted)
2. WHEN all 6 jurors have submitted scores for all 11 teams and all 5 criteria, THE Voting_App SHALL indicate that voting is complete
3. THE Voting_App SHALL allow the admin to view individual juror completion status without revealing their specific scores

### Requirement 8: Data Export

**User Story:** As an admin, I want to export the final results, so that I have a digital record comparable to the previous paper-based Auswertungstabelle.

#### Acceptance Criteria

1. WHEN a Voting_Session has ended, THE Voting_App SHALL provide an export of all scores in a tabular format (CSV or XLSX)
2. THE Voting_App SHALL include in the export: team names, juror names, individual scores per criterion (Gesamtidee, Kundennutzen, Markt, Realisierbarkeit, Präsentation), and aggregated totals
3. THE Voting_App SHALL include the final ranking and average scores in the export
4. THE Voting_App SHALL format the export to match the structure of the original Auswertungstabelle (teams as rows, jurors × criteria as columns)

---

## Open Questions (resolved)

| # | Question | Resolution |
|---|----------|------------|
| 1 | Scoring scale | **1–10 per criterion** (configurable, default 1–10) |
| 2 | Criteria | **5 criteria:** Gesamtidee, Kundennutzen, Markt, Realisierbarkeit, Präsentation |
| 3 | Weighting | **Equally weighted** — simple sum, no weighting factors |
| 4 | Aggregation | **Simple sum** across all jurors. Average = total / number of jurors |
| 5 | Juror anonymity | **TBD** — not specified in paper documents. Default: scores visible only to admin |
| 6 | Idea metadata | Team name + short description shown to jurors (from Teams/ folder) |
| 7 | Comments | **Not included** — paper form has no free-text field; digital version omits it too |