sneakyklaus/docs/ROADMAP.md

Sneaky Klaus - Implementation Roadmap

Overview

This roadmap defines the phased implementation approach for Sneaky Klaus, a self-hosted Secret Santa organization application. The roadmap progresses from foundational infrastructure through core features to enhancement and polish.

Key Architectural Decisions

The following decisions have been approved and are fixed:

• Frontend: Pure server-side rendering with Jinja2 templates (no JavaScript framework)
• Background Jobs: APScheduler (in-process, no separate job queue)
• Password Requirements: Minimum 12 characters, no complexity requirements
• Magic Link Expiration: 1 hour for links, 7-day sliding window for sessions
• Reminder Defaults: 7 days and 1 day before exchange date (configurable per exchange)
• Minimum Participants: Hard requirement of 3 participants per exchange

Phase Definitions

Phase 0: Foundation and Architecture

Goal: Establish technical foundation and architectural design

Deliverables:

• Architecture Decision Records (ADRs) for core technology choices
• System design documentation (v0.1.0)
• Database schema design
• API/route specifications
• Component design documentation
• Development environment setup

Stories: None (pre-implementation architectural work)

Dependencies: None

MVP Status: Prerequisite for MVP

---

Phase 1: Core Admin & Exchange Management (MVP)

Goal: Enable admin to create and manage gift exchanges

Stories:

• 1.1 Initial Admin Setup
• 1.2 Admin Login
• 1.4 Admin Logout
• 2.1 Create Exchange
• 2.2 View Exchange List
• 2.3 View Exchange Details
• 2.6 Generate Registration Link
• 3.1 Open Registration

Dependencies: Phase 0 complete

MVP Status: This is the MVP

Exit Criteria:

• Admin can create account, log in, and log out
• Admin can create exchanges with all required fields
• Admin can view list of exchanges
• Admin can generate and copy registration links
• Admin can open registration for exchanges

---

Phase 2: Participant Registration & Authentication

Goal: Enable participants to join exchanges and authenticate

Stories:

• 4.1 Access Registration Page
• 4.2 New Participant Registration
• 4.3 Returning Participant Detection
• 5.1 Magic Link Request
• 5.2 Magic Link Login
• 5.3 Participant Session
• 10.1 Registration Confirmation Email

Dependencies: Phase 1 complete

Exit Criteria:

• Participants can access registration page via link
• Participants can register with name, email, and gift ideas
• Returning participants are detected and can request magic link
• Magic links authenticate participants correctly
• Participant sessions persist appropriately
• Confirmation emails sent successfully

---

Phase 3: Exchange State Management & Matching

Goal: Enable complete exchange lifecycle from registration to matching

Stories:

• 2.4 Edit Exchange
• 3.2 Close Registration
• 3.3 Reopen Registration (Pre-Matching)
• 7.1 View Participants for Exclusions
• 7.2 Add Exclusion Rule
• 7.3 Remove Exclusion Rule
• 7.4 Exclusion Validation
• 8.1 Trigger Matching
• 8.2 Matching Algorithm
• 8.3 Matching Failure Handling
• 8.4 View Matches (Admin)
• 10.2 Match Notification Email

Dependencies: Phase 2 complete

Exit Criteria:

• Admin can edit exchange details
• Admin can close and reopen registration
• Admin can configure exclusion rules
• Matching algorithm successfully creates valid assignments
• Match notification emails sent to all participants
• Admin can view all matches for troubleshooting

---

Phase 4: Participant Dashboard & Self-Management

Goal: Enable participants to view assignments and manage profiles

Stories:

• 4.5 View Participant List (Pre-Matching)
• 6.1 Update Profile
• 6.2 Withdraw from Exchange
• 6.3 Update Reminder Preferences
• 11.1 View My Assignment
• 11.2 View Exchange Information
• 11.3 View Participant List (Post-Matching)

Dependencies: Phase 3 complete

Exit Criteria:

• Participants can view and update their profiles
• Participants can withdraw before registration closes
• Participants can view their assignment after matching
• Participants can view exchange information and participant lists
• Participants can manage reminder preferences

---

Phase 5: Advanced Matching & Admin Features

Goal: Handle edge cases and provide advanced administrative control

Stories:

• 2.5 Delete Exchange
• 3.4 Reopen Registration (Post-Matching)
• 4.4 Admin Self-Registration
• 8.5 Re-Match Participants
• 8.6 Manual Match Override
• 9.1 Remove Participant (Admin)
• 9.2 Handle Post-Match Participant Removal

Dependencies: Phase 4 complete

Exit Criteria:

• Admin can delete exchanges
• Admin can reopen registration after matching (with match clearing)
• Admin can participate in their own exchanges
• Admin can trigger re-matching
• Admin can manually override individual matches
• Admin can remove participants with appropriate re-matching

---

Phase 6: Notifications & Reminders

Goal: Complete notification system with reminders and admin notifications

Stories:

• 10.3 Reminder Emails
• 10.4 Admin Notification: New Registration
• 10.5 Admin Notification: Participant Withdrawal
• 10.6 Admin Notification: Matching Complete
• 10.7 Configure Admin Notifications
• 14.1 Configure Reminder Schedule

Dependencies: Phase 4 complete (can run parallel to Phase 5)

Exit Criteria:

• Reminder emails sent according to configured schedule
• Admin receives opt-in notifications for key events
• Admin can configure notification preferences globally and per-exchange
• Admin can configure reminder schedule per exchange

---

Phase 7: Data Management & Lifecycle

Goal: Implement data retention and exchange lifecycle completion

Stories:

• 1.3 Admin Password Recovery
• 3.5 Mark Exchange Complete
• 3.6 Automatic Exchange Completion
• 12.1 Automatic Data Purge
• 12.2 View Data Retention Status

Dependencies: Phase 5 complete

Exit Criteria:

• Admin can recover password via email
• Exchanges automatically complete after exchange date
• Exchange data purged 30 days after completion
• Admin can view retention status and purge timeline
• Admin receives warning before data purge

---

Phase 8: Polish & Responsive Design

Goal: Ensure excellent user experience across all devices

Stories:

• 13.1 Mobile-Friendly Participant Experience
• 13.2 Mobile-Friendly Admin Experience

Dependencies: Phase 7 complete

Exit Criteria:

• All participant flows work well on mobile devices
• All admin flows work well on mobile devices
• Touch targets appropriately sized
• No horizontal scrolling required
• Tested across common mobile browsers

---

Phase Dependencies Graph

Phase 0 (Foundation)
    ↓
Phase 1 (MVP: Core Admin & Exchange Management)
    ↓
Phase 2 (Participant Registration & Authentication)
    ↓
Phase 3 (Exchange State Management & Matching)
    ↓
Phase 4 (Participant Dashboard & Self-Management)
    ↓
    ├── Phase 5 (Advanced Matching & Admin Features)
    └── Phase 6 (Notifications & Reminders) [parallel]
         ↓
    Phase 7 (Data Management & Lifecycle)
         ↓
    Phase 8 (Polish & Responsive Design)

MVP Definition

The MVP is Phase 1: Core Admin & Exchange Management

An implementation reaches MVP when:

1. An admin can create an account
2. An admin can log in and out securely
3. An admin can create gift exchanges with all required fields
4. An admin can view a list of their exchanges
5. An admin can generate shareable registration links
6. The application is deployable via Docker

This represents the minimum foundation for a functional Secret Santa application, even though it doesn't yet support participant registration or matching.

Implementation Notes

Story Prioritization Within Phases

Stories listed within each phase are roughly prioritized, but developers should:

• Implement database models and schemas before UI
• Implement authentication before protected routes
• Consider natural groupings (e.g., all CRUD operations for a feature together)

Testing Strategy

Each phase should include:

• Unit tests for business logic
• Integration tests for database operations
• End-to-end tests for critical user flows
• Tests written before or alongside implementation (TDD encouraged)

Documentation Updates

As each phase completes:

• Update design docs if implementation reveals necessary changes
• Document any deviations from original design with rationale
• Update ADRs if architectural decisions change

Deployment Considerations

• Docker image should be buildable and runnable from Phase 1 onward
• Each phase should result in a deployable, functional (if limited) application
• Database migrations should be reversible where possible

Success Criteria

The implementation is complete when:

1. All 8 phases are delivered
2. All acceptance criteria for all stories are met
3. Application passes end-to-end testing
4. Documentation is complete and accurate
5. Application is production-ready for self-hosting

Timeline Estimates

Actual timeline depends on development velocity. Rough estimates:

• Phase 0: 2-3 days (design work)
• Phase 1: 3-5 days (MVP)
• Phase 2: 3-4 days
• Phase 3: 5-7 days (complex matching logic)
• Phase 4: 2-3 days
• Phase 5: 3-4 days
• Phase 6: 2-3 days
• Phase 7: 2-3 days
• Phase 8: 2-3 days

Total estimate: 24-37 days of development time