sneakyklaus/docs/PROJECT_OVERVIEW.md

Sneaky Klaus - Product Overview

Vision

Sneaky Klaus is a simple, self-hosted web application for organizing Secret Santa gift exchanges. It removes the friction of coordinating gift exchanges by handling participant registration, random matching, and email notifications—all while maintaining the secrecy that makes Secret Santa fun.

The application is designed for individuals, families, or small organizations who want full control over their data without relying on third-party services.

---

Core Principles

• Simplicity first: Participants should be able to join an exchange in under a minute
• No participant accounts: Participants authenticate via email magic links, not passwords
• Privacy by design: Only the gifter knows who they're buying for; the system never reveals matches to anyone else
• Self-hosted: All data stays on infrastructure you control
• Mobile-friendly: Works seamlessly on phones, tablets, and desktops

---

User Roles

Administrator

• Single admin account for the entire installation
• Creates and manages all gift exchanges
• May optionally participate in exchanges they create
• Authenticates with email and password
• Can recover password via email reset link

Participant

• Joins exchanges via shareable registration links
• No password required—authentication via email magic link
• Can participate in multiple exchanges with the same email address
• Can view their assigned recipient and the participant list (but not other matches)

---

Gift Exchange Lifecycle

An exchange progresses through the following states:

Draft → Registration Open → Registration Closed → Matched → Completed

State Descriptions

1. Draft: Exchange is created but not yet accepting registrations
2. Registration Open: Participants can join via the shareable link
3. Registration Closed: No new registrations; admin configures exclusions and triggers matching
4. Matched: Participants have been assigned recipients; notifications sent
5. Completed: Exchange date has passed; data retained for 30 days then purged

State Transitions

• Forward progression through states is the normal flow
• Backward movement is permitted:
  • Reopening registration after closing (before matching) adds new participants
  • Reopening registration after matching clears all existing matches and requires fresh re-matching
• Admin controls all state transitions manually (except automatic completion based on date)

---

Features

Exchange Management (Admin)

Creating an Exchange

• Name/title for the exchange
• Description (optional)
• Suggested gift budget/price range
• Maximum participant limit (configurable per exchange; minimum is always 3)
• Expected close date (when registration should end)
• Exchange date (when gifts should be exchanged)
• Timezone for all dates

Editing an Exchange

• All fields are editable until matching has occurred
• After matching, exchange details are locked

Registration Link

• Each exchange has a unique, shareable registration link
• Link can be shared via any channel (email, messaging apps, etc.)
• Link remains active while registration is open

Closing Registration & Matching

• Admin manually closes registration when ready
• Before matching, admin can define exclusion rules (e.g., "Person A should not be matched with Person B")
• Admin triggers the matching process
• System randomly assigns each participant a recipient following Secret Santa best practices:
  • No self-matching
  • Exclusion rules are honored
  • Single cycle preferred (A→B→C→A) to ensure everyone gives and receives exactly once

Handling Issues

• Re-matching: If needed, admin can trigger a complete re-match
• Manual assignment: Admin can manually override or assign specific matches
• Participant removal: Admin can remove participants at any stage

Participant Registration

Joining an Exchange

• Participant clicks the shareable link
• System checks if their email is already registered for this exchange
  • If yes: prompts to send magic link to access their registration
  • If no: shows registration form

Registration Form

• Name (display name for other participants)
• Email address
• Gift ideas (single multi-line text field for wishlist/preferences)

Self-Management

• Participants can withdraw from an exchange before registration closes
• Participants can update their gift ideas before registration closes
• After matching, profile information is locked

Matching & Notifications

Matching Algorithm

• Implements proper Secret Santa matching:
  • Creates a single cycle where possible (ensures no small isolated groups)
  • Honors all exclusion rules
  • Guarantees everyone gives exactly one gift and receives exactly one gift
• If matching is impossible due to exclusion rules, admin is notified with explanation

Participant Notifications

• Upon matching, each participant receives an email containing:
  • Name of their assigned recipient
  • Recipient's gift ideas
  • Gift budget for the exchange
  • Exchange date
• Email includes a magic link to view this information in the app

Participant Experience (Post-Matching)

Viewing Assignment

• Participants can log in via magic link at any time
• Dashboard shows:
  • Who they are buying for
  • That person's gift ideas
  • Gift budget
  • Exchange date
  • List of all participants in the exchange (names only, not matches)

Reminders

• Automatic reminder emails as exchange date approaches
• Reminders are opt-in only (participant chooses during registration)
• Suggested reminder schedule: configurable by admin (e.g., 7 days, 3 days, 1 day before)

Admin Notifications

• Admin can opt-in to receive notifications for:
  • New participant registration
  • Participant withdrawal
  • Registration closed confirmation
  • Matching complete
  • Matching failures/issues
• Notification preferences are configurable per exchange or globally

---

Data Management

Retention Policy

• Exchange data (participants, matches, gift ideas) is retained for 30 days after the exchange date
• After 30 days, all exchange data is automatically purged
• Admin can manually delete exchanges at any time

Privacy Considerations

• Participant email addresses are only visible to the admin
• Participants see each other's display names only
• Match assignments are never visible to anyone except:
  • The gifter (sees their own recipient)
  • The admin (for troubleshooting/manual assignment only)

---

Admin Account Management

Initial Setup

• First-time setup creates the admin account
• Requires email and password

Password Recovery

• Admin can request password reset via email
• Reset link sent to admin email address

---

Out of Scope

The following features are explicitly not included in Sneaky Klaus:

• Multiple admin accounts: Single admin only
• Participant-to-participant messaging: No anonymous or direct messaging between participants
• Reveal feature: No mechanism to reveal who was whose Secret Santa after the exchange
• Payment processing: No built-in payment or gift card purchasing
• Gift tracking: No tracking of whether gifts were purchased or delivered
• Social features: No comments, reactions, or social sharing within the app
• Wishlist links: No integration with external wishlists (Amazon, etc.)
• Calendar integration: No .ics exports or calendar app integration
• Multi-language support: English only (initial release)
• Themeing/customization: No custom branding per exchange

---

Success Metrics

A successful implementation of Sneaky Klaus will:

1. Allow an admin to create an exchange and have participants registered within 5 minutes
2. Enable participants to complete registration in under 60 seconds
3. Successfully match any valid participant set (where exclusions don't make matching impossible)
4. Deliver all notification emails reliably via Resend
5. Work smoothly on mobile devices without requiring a native app
6. Maintain complete secrecy of match assignments until intentionally revealed by gifters

---

Glossary

Term	Definition
Exchange	A single Secret Santa event with its own participants, dates, and matches
Participant	A person registered in an exchange who will give and receive a gift
Match/Assignment	The pairing of a gifter to their recipient
Exclusion	A rule preventing two specific participants from being matched
Magic Link	A single-use, time-limited URL sent via email for passwordless authentication
Registration Link	The shareable URL used to join an exchange