# Sneaky Klaus - Product Backlog

## Overview

This backlog contains user stories for Sneaky Klaus, organized by epic. Stories follow the format:

> **As a** [role], **I want** [capability], **so that** [benefit].

Each story includes acceptance criteria to define "done."

---

## Epic 1: Admin Account Management

### 1.1 Initial Admin Setup

**As a** first-time user, **I want** to create an admin account during initial setup, **so that** I can manage gift exchanges.

**Acceptance Criteria:**
- Setup screen appears on first application access
- Requires email address and password
- Password must meet minimum security requirements
- After setup, user is logged in as admin
- Setup screen is not accessible after initial admin creation

---

### 1.2 Admin Login

**As an** admin, **I want** to log in with my email and password, **so that** I can access the admin dashboard.

**Acceptance Criteria:**
- Login form accepts email and password
- Invalid credentials show appropriate error message
- Successful login redirects to admin dashboard
- Session persists across browser refreshes

---

### 1.3 Admin Password Recovery

**As an** admin, **I want** to reset my password via email, **so that** I can regain access if I forget my password.

**Acceptance Criteria:**
- "Forgot password" link on login page
- Entering admin email sends reset link
- Reset link expires after reasonable time period
- Reset link can only be used once
- New password must meet security requirements
- Confirmation shown after successful reset

---

### 1.4 Admin Logout

**As an** admin, **I want** to log out of my account, **so that** I can secure my session.

**Acceptance Criteria:**
- Logout option available from admin interface
- Logout clears session
- Redirects to login page after logout

---

## Epic 2: Exchange Management

### 2.1 Create Exchange

**As an** admin, **I want** to create a new gift exchange, **so that** I can organize a Secret Santa event.

**Acceptance Criteria:**
- Form to create exchange with fields:
  - Name (required)
  - Description (optional)
  - Gift budget/price range (required)
  - Maximum participants (required, minimum 3)
  - Registration close date (required)
  - Exchange date (required)
  - Timezone (required)
- Exchange created in "Draft" state
- Exchange appears in admin dashboard after creation

---

### 2.2 View Exchange List

**As an** admin, **I want** to see all my gift exchanges, **so that** I can manage them.

**Acceptance Criteria:**
- Dashboard shows list of all exchanges
- Each exchange displays: name, state, participant count, exchange date
- Exchanges sorted by exchange date (upcoming first)
- Visual indicator for exchange state

---

### 2.3 View Exchange Details

**As an** admin, **I want** to view full details of an exchange, **so that** I can see its current status and participants.

**Acceptance Criteria:**
- Clicking an exchange opens detail view
- Shows all exchange information
- Shows list of registered participants
- Shows current state
- Shows registration link (when applicable)

---

### 2.4 Edit Exchange

**As an** admin, **I want** to edit exchange details, **so that** I can correct mistakes or update information.

**Acceptance Criteria:**
- All fields editable when exchange is in Draft, Registration Open, or Registration Closed state
- Cannot edit after matching has occurred
- Changes saved immediately
- Confirmation message after save

---

### 2.5 Delete Exchange

**As an** admin, **I want** to delete an exchange, **so that** I can remove cancelled or test exchanges.

**Acceptance Criteria:**
- Delete option available for any exchange
- Confirmation required before deletion
- Deletion removes all associated data (participants, matches)
- Exchange no longer appears in dashboard

---

### 2.6 Generate Registration Link

**As an** admin, **I want** a shareable registration link for each exchange, **so that** I can invite participants.

**Acceptance Criteria:**
- Unique link generated for each exchange
- Link is copyable to clipboard
- Link is displayed when exchange is in appropriate state
- Link leads to registration page for that specific exchange

---

## Epic 3: Exchange State Management

### 3.1 Open Registration

**As an** admin, **I want** to open registration for an exchange, **so that** participants can join.

**Acceptance Criteria:**
- "Open Registration" action available from Draft state
- Exchange state changes to "Registration Open"
- Registration link becomes active
- Participants can now access registration form

---

### 3.2 Close Registration

**As an** admin, **I want** to close registration, **so that** I can prepare for matching.

**Acceptance Criteria:**
- "Close Registration" action available from Registration Open state
- Exchange state changes to "Registration Closed"
- Registration link no longer accepts new registrations
- Existing participants can still access their profile via magic link

---

### 3.3 Reopen Registration (Pre-Matching)

**As an** admin, **I want** to reopen registration before matching, **so that** I can allow late additions.

**Acceptance Criteria:**
- "Reopen Registration" action available from Registration Closed state
- Exchange state changes back to "Registration Open"
- New participants can register
- Existing participants retained

---

### 3.4 Reopen Registration (Post-Matching)

**As an** admin, **I want** to reopen registration after matching, **so that** I can add participants who were missed.

**Acceptance Criteria:**
- "Reopen Registration" action available from Matched state
- Warning displayed that existing matches will be cleared
- Confirmation required
- All matches cleared upon confirmation
- Exchange state changes to "Registration Open"

---

### 3.5 Mark Exchange Complete

**As an** admin, **I want** to mark an exchange as complete, **so that** it's clear the event has concluded.

**Acceptance Criteria:**
- "Mark Complete" action available from Matched state
- Exchange state changes to "Completed"
- Exchange moves to completed section in dashboard
- 30-day retention countdown begins

---

### 3.6 Automatic Exchange Completion

**As a** system, **I want** to automatically mark exchanges as complete after the exchange date, **so that** data retention policies are enforced.

**Acceptance Criteria:**
- Exchanges in Matched state auto-transition to Completed after exchange date passes
- 30-day retention countdown begins automatically
- Admin can still access completed exchange data during retention period

---

## Epic 4: Participant Registration

### 4.1 Access Registration Page

**As a** potential participant, **I want** to access the registration page via shared link, **so that** I can join an exchange.

**Acceptance Criteria:**
- Registration link opens registration page
- Page displays exchange name, description, budget, and exchange date
- Shows registration form if registration is open
- Shows appropriate message if registration is closed
- Shows appropriate message if exchange doesn't exist

---

### 4.2 New Participant Registration

**As a** potential participant, **I want** to register for an exchange, **so that** I can participate in Secret Santa.

**Acceptance Criteria:**
- Registration form with fields:
  - Name (required)
  - Email (required, valid email format)
  - Gift ideas (optional, multi-line text)
  - Opt-in for reminder emails (checkbox)
- Email uniqueness checked within exchange
- Confirmation message after successful registration
- Confirmation email sent to participant

---

### 4.3 Returning Participant Detection

**As a** returning participant, **I want** to be recognized when I click the registration link again, **so that** I don't accidentally create duplicate registrations.

**Acceptance Criteria:**
- After clicking registration link, option to enter email to check existing registration
- If email found, prompt to send magic link
- If email not found, show registration form
- Clear messaging about what's happening

---

### 4.4 Admin Self-Registration

**As an** admin, **I want** to register myself as a participant in an exchange I created, **so that** I can participate in my own Secret Santa.

**Acceptance Criteria:**
- Option for admin to add themselves as participant
- Uses admin's email by default (editable)
- Admin registered same as any other participant
- Admin clearly marked in participant list (for admin view only)

---

### 4.5 View Participant List (Pre-Matching)

**As a** registered participant, **I want** to see who else has registered, **so that** I know who's participating.

**Acceptance Criteria:**
- Participant list visible after logging in via magic link
- Shows display names only
- Does not show email addresses
- Does not indicate any match information
- Updates as new participants register

---

## Epic 5: Participant Authentication

### 5.1 Magic Link Request

**As a** registered participant, **I want** to request a login link via email, **so that** I can access my exchange information.

**Acceptance Criteria:**
- "Access my registration" or similar option on registration page
- Enter email to request magic link
- If email registered, magic link sent
- If email not registered, appropriate message shown (without revealing registration status for security)
- Magic link expires after reasonable time period

---

### 5.2 Magic Link Login

**As a** participant, **I want** to log in by clicking the magic link, **so that** I can access my information without a password.

**Acceptance Criteria:**
- Clicking valid magic link logs participant in
- Redirects to participant dashboard
- Magic link can only be used once
- Expired link shows appropriate message with option to request new link

---

### 5.3 Participant Session

**As a** logged-in participant, **I want** my session to persist, **so that** I don't have to log in repeatedly.

**Acceptance Criteria:**
- Session persists across browser refreshes
- Session expires after reasonable inactivity period
- Participant can manually log out

---

## Epic 6: Participant Self-Management

### 6.1 Update Profile

**As a** registered participant, **I want** to update my gift ideas, **so that** my Secret Santa has current information.

**Acceptance Criteria:**
- Edit option available when logged in
- Can update name and gift ideas
- Cannot change email (request admin help)
- Only available before matching occurs
- Confirmation after save

---

### 6.2 Withdraw from Exchange

**As a** registered participant, **I want** to withdraw from an exchange, **so that** I can opt out if my circumstances change.

**Acceptance Criteria:**
- "Withdraw" option available before registration closes
- Confirmation required
- Participant removed from exchange
- Confirmation email sent
- Admin notified (if notifications enabled)

---

### 6.3 Update Reminder Preferences

**As a** participant, **I want** to change my reminder email preferences, **so that** I can control notifications.

**Acceptance Criteria:**
- Option to enable/disable reminder emails
- Available before exchange completes
- Changes take effect immediately

---

## Epic 7: Exclusion Rules

### 7.1 View Participants for Exclusions

**As an** admin, **I want** to see all participants when configuring exclusions, **so that** I can set up appropriate rules.

**Acceptance Criteria:**
- List of all participants displayed
- Available after registration is closed
- Shows participant names clearly

---

### 7.2 Add Exclusion Rule

**As an** admin, **I want** to add exclusion rules, **so that** certain participants won't be matched together.

**Acceptance Criteria:**
- Interface to select two participants who shouldn't be matched
- Exclusion is bidirectional (A won't give to B, B won't give to A)
- Multiple exclusions can be added
- Visual confirmation of added exclusion

---

### 7.3 Remove Exclusion Rule

**As an** admin, **I want** to remove exclusion rules, **so that** I can correct mistakes.

**Acceptance Criteria:**
- List of current exclusions displayed
- Option to remove each exclusion
- Removal is immediate
- Confirmation shown

---

### 7.4 Exclusion Validation

**As an** admin, **I want** to know if my exclusions make matching impossible, **so that** I can adjust before attempting to match.

**Acceptance Criteria:**
- Warning displayed if exclusions may prevent valid matching
- Explanation of which exclusions are problematic
- Matching blocked if mathematically impossible

---

## Epic 8: Matching

### 8.1 Trigger Matching

**As an** admin, **I want** to trigger the matching process, **so that** participants are assigned their recipients.

**Acceptance Criteria:**
- "Match Participants" action available from Registration Closed state
- Minimum 3 participants required
- Matching algorithm runs respecting all exclusions
- Exchange state changes to "Matched" on success
- Admin notified of success

---

### 8.2 Matching Algorithm

**As a** system, **I want** to randomly match participants following Secret Santa best practices, **so that** the exchange is fair and secret.

**Acceptance Criteria:**
- No participant is matched to themselves
- All exclusion rules are honored
- Each participant gives exactly one gift
- Each participant receives exactly one gift
- Single cycle preferred (A→B→C→A) when possible
- Randomization ensures unpredictability

---

### 8.3 Matching Failure Handling

**As an** admin, **I want** to be informed if matching fails, **so that** I can resolve the issue.

**Acceptance Criteria:**
- Clear error message if matching impossible
- Explanation of why (e.g., "Too many exclusions")
- Suggestions for resolution
- Exchange remains in Registration Closed state

---

### 8.4 View Matches (Admin)

**As an** admin, **I want** to view all matches, **so that** I can troubleshoot issues or handle disputes.

**Acceptance Criteria:**
- Admin can see full match list
- Shows who is giving to whom
- Only visible to admin
- Available after matching

---

### 8.5 Re-Match Participants

**As an** admin, **I want** to trigger a fresh re-match, **so that** I can resolve issues with current assignments.

**Acceptance Criteria:**
- "Re-match" option available in Matched state
- Confirmation required (warns all matches will be cleared)
- New random matching performed
- New notification emails sent to all participants
- Old matches completely replaced

---

### 8.6 Manual Match Override

**As an** admin, **I want** to manually assign or change specific matches, **so that** I can handle special circumstances.

**Acceptance Criteria:**
- Interface to change individual assignments
- Validation prevents invalid states (no self-matching, everyone has exactly one recipient)
- Changes saved immediately
- Affected participants receive updated notification

---

## Epic 9: Participant Removal (Post-Registration Close)

### 9.1 Remove Participant (Admin)

**As an** admin, **I want** to remove a participant at any stage, **so that** I can handle dropouts.

**Acceptance Criteria:**
- Remove option available for any participant
- Confirmation required
- If before matching: participant simply removed
- If after matching: triggers re-match requirement
- Removed participant notified via email

---

### 9.2 Handle Post-Match Participant Removal

**As a** system, **I want** to handle participant removal after matching, **so that** the exchange can continue.

**Acceptance Criteria:**
- When participant removed after matching, admin notified
- Option to auto-rematch (system re-runs matching)
- Option to manually reassign affected matches only
- All affected participants notified of changes

---

## Epic 10: Notifications

### 10.1 Registration Confirmation Email

**As a** newly registered participant, **I want** to receive a confirmation email, **so that** I know my registration was successful.

**Acceptance Criteria:**
- Email sent immediately after registration
- Includes exchange name and date
- Includes magic link to access registration
- Includes confirmation of provided details

---

### 10.2 Match Notification Email

**As a** participant, **I want** to receive an email with my match assignment, **so that** I know who to buy for.

**Acceptance Criteria:**
- Email sent immediately after matching
- Includes recipient's name
- Includes recipient's gift ideas
- Includes gift budget
- Includes exchange date
- Includes magic link to view in app

---

### 10.3 Reminder Emails

**As a** participant who opted in, **I want** to receive reminder emails before the exchange, **so that** I don't forget to buy a gift.

**Acceptance Criteria:**
- Reminders sent only to opted-in participants
- Reminder schedule configurable by admin
- Includes recipient info and exchange date
- Includes magic link to view full details

---

### 10.4 Admin Notification: New Registration

**As an** admin, **I want** to be notified of new registrations, **so that** I can track participation.

**Acceptance Criteria:**
- Email sent when new participant registers
- Only if admin has enabled this notification
- Includes participant name and exchange name

---

### 10.5 Admin Notification: Participant Withdrawal

**As an** admin, **I want** to be notified when a participant withdraws, **so that** I can follow up if needed.

**Acceptance Criteria:**
- Email sent when participant withdraws
- Only if admin has enabled this notification
- Includes participant name and exchange name

---

### 10.6 Admin Notification: Matching Complete

**As an** admin, **I want** to be notified when matching completes, **so that** I know the exchange is ready.

**Acceptance Criteria:**
- Email sent after successful matching
- Only if admin has enabled this notification
- Includes exchange name and participant count

---

### 10.7 Configure Admin Notifications

**As an** admin, **I want** to configure which notifications I receive, **so that** I'm not overwhelmed with emails.

**Acceptance Criteria:**
- Settings page for notification preferences
- Toggle for each notification type
- Can set globally or per-exchange
- Changes take effect immediately

---

## Epic 11: Participant Dashboard

### 11.1 View My Assignment

**As a** matched participant, **I want** to view who I'm buying for, **so that** I can purchase an appropriate gift.

**Acceptance Criteria:**
- Dashboard shows assigned recipient's name
- Shows recipient's gift ideas
- Shows gift budget
- Shows exchange date
- Available after matching occurs

---

### 11.2 View Exchange Information

**As a** participant, **I want** to view exchange details, **so that** I have all the information I need.

**Acceptance Criteria:**
- Shows exchange name and description
- Shows gift budget
- Shows exchange date and timezone
- Shows registration status/state

---

### 11.3 View Participant List (Post-Matching)

**As a** participant, **I want** to see who's in the exchange, **so that** I know the group.

**Acceptance Criteria:**
- List of all participant names
- Does not reveal who is matched to whom
- Does not reveal who my Secret Santa is

---

## Epic 12: Data Retention

### 12.1 Automatic Data Purge

**As a** system, **I want** to automatically purge exchange data after 30 days, **so that** participant data isn't retained indefinitely.

**Acceptance Criteria:**
- Completed exchanges tracked with completion date
- 30 days after completion, all data purged automatically
- Purge includes: participants, matches, gift ideas, emails
- Admin notified before purge (e.g., 7 days warning)

---

### 12.2 View Data Retention Status

**As an** admin, **I want** to see when exchange data will be purged, **so that** I can export if needed.

**Acceptance Criteria:**
- Completed exchanges show days until purge
- Clear indication of purge date

---

## Epic 13: Responsive Design

### 13.1 Mobile-Friendly Participant Experience

**As a** participant on a mobile device, **I want** the interface to work well on my phone, **so that** I can easily register and view my assignment.

**Acceptance Criteria:**
- Registration form usable on mobile
- Dashboard readable on mobile
- Touch targets appropriately sized
- No horizontal scrolling required

---

### 13.2 Mobile-Friendly Admin Experience

**As an** admin on a mobile device, **I want** to manage exchanges from my phone, **so that** I can administer on the go.

**Acceptance Criteria:**
- Admin dashboard usable on mobile
- Exchange creation/editing works on mobile
- Participant management works on mobile
- All critical functions accessible

---

## Epic 14: Reminder Configuration

### 14.1 Configure Reminder Schedule

**As an** admin, **I want** to configure when reminder emails are sent, **so that** I can customize the experience.

**Acceptance Criteria:**
- Settings to define reminder intervals (e.g., 7 days, 3 days, 1 day before)
- Can be set per-exchange or as default
- Only affects participants who opted in

---

## Story Status Key

| Status | Description |
|--------|-------------|
| 📋 Backlog | Not yet started |
| 🔄 In Progress | Currently being worked on |
| ✅ Done | Completed and tested |
| 🚫 Blocked | Cannot proceed due to dependency |

---

## Notes

- Stories are roughly ordered by dependency and priority within each epic
- Epics 1-4 represent core MVP functionality
- Epics 5-6 complete the participant experience
- Epics 7-9 handle the matching complexity
- Epics 10-14 are supporting features that enhance the experience
- Story estimates and sprint assignments to be added during planning sessions